Re: Slashdot reply (draft 0.1)

["Greg Ferguson" <gferg@hoop.timonium.sgi.com>]

On Feb 11, 12:23am, Gregory Leblanc wrote:
> Subject: RE: Slashdot reply (draft 0.1)
> [snip]
> >
> >   - How can I submit my work to the LDP?
> >
> > 4 possibilities :
> > a. you can write in LinuxDoc : call your document an HOWTO
> > b. you can write in DocBook : call your document a DOCBOOK :-)
> > c. you are a master of TeX/LaTeX, pdf or any specific format
> > : call your
> >    document a GUIDE
> > d. you only know ascii and html : call your document a FAQ
>
> [...]
>
> Calling your document a FAQ because you don't know any breed of
> SGML other than HTML is silly.  If we're going to use the terms
> "FAQ", "HOWTO", "GUIDE", and whatever else, it should be because
> the document logically is a FAQ, because it's a series of
> questions, or a HOWTO, because it tells HOW TO do something.
> If we're going to classify documents by their format, let's just
> DO IT, and make categories based on format.  But the best thing
> for users is to classify documents by structure/content, and keep
> sections like HOWTO, FAQ, etc.

I agree with this 100%. DocBook is nothing more than an SGML instance.
It should be treated no differently than what the LDP does currently
with the Linuxdoc source documents (except in the processing phase
whereby we need to use the correct DTD/stylesheets/etc., but that's
all "behind-the-scenes" stuff anyway).

The consumer of the information could care less if the HOWTO they
are reading was derived from DocBook, LinuxDoc or DocFoo...what
they will be reading is the derived output from the source anyway -
be it HTML, plain text, PDF, etc.

Authors will need to know what source format to edit. A well-organized
directory structure should reflect that.

DocBook is not a "book", it's simply markup. There's no reason
whatsoever to distinguish it as a document classification (to the
"end-user"). The only reason I can think of to single out DocBook
usage is in the announcement/news areas we have on the LDP (or in
publicizing to outside sources) -

   "Yes, the LDP now accepts and processes Guides/Manuals, HOWTOs
    and FAQs that are submitted to us in DocBook SGML."

> If necessary, we could break sections down something similar to:
>
> LDP/
> LDP/FAQ/
> LDP/HOWTO/ (put the actual plain text HOWTO documents here)
> LDP/HOWTO/DocBook/ (put the DocBook source here)
> LDP/HOWTO/LinuxDoc/ (put the LinuxDoc source here)
> LDP/HOWTO/pdf/ (put pdf output here)
> LDP/HOWTO/ps/ (put PS output here)
> LDP/HOWTO/tex/ (put tex output here)
> LDP/HOWTO/html/ (put html output here)
> LDP/HOWTO/stuff I missed/ (put the stuff I missed here)
> LDP/GUIDE/
> ...

This looks very reasonable. We have to still decide on the mini-HOWTOs;
do they need to be distinguished in some manner? I would add an
extra hierarchy (for the sgml) to what Greg has recommended; and we
need an area for translations:

LDP/
LDP/HOWTO/                 (put the plain text HOWTO documents here)
LDP/HOWTO/pdf/             (put pdf output here)
LDP/HOWTO/ps/              (put PS output here)
LDP/HOWTO/sgml/
LDP/HOWTO/sgml/DocBook/    (put the DocBook source here)
LDP/HOWTO/sgml/LinuxDoc/   (put the LinuxDoc source here)
LDP/HOWTO/tex/             (put tex output here)
LDP/HOWTO/translations/
LDP/HOWTO/translations/es/
     ...all various lang translations; mirror similar dir structure...
LDP/HOWTO/html/            (put html output here)

For the Guides, a sub-directory below each format type indicates
the specific Guide, as in:

LDP/
LDP/GUIDES/
LDP/GUIDES/pdf/
LDP/GUIDES/pdf/<guide_1>/
LDP/GUIDES/pdf/<guide_2>/
... mirror similar dir structure as outlined above...

---

This is very similar to how metalab:/pub/Linux/docs is currently
structured, with a couple of exceptions (the existence of the
"other-formats" directory into which we have directories for
ps, html, dvi, sgml, etc.).

The only other thing I might suggest is placing the plain-text
HOWTOs in their own sub-directory off the main "HOWTO" directory.
Makes it easier to find/traverse the tree, and it's consistent
with the placement of the other derived output formats:

LDP/HOWTO/       (you *only* see sub-dirs, and a README)
LDP/HOWTO/plain  (put the plain text HOWTO documents here)

Something like that.

> [...]


regards,

-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg@sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com  | 410-785-2334 
Linux Doc Project - http://www.linuxdoc.org  |


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org