RE: [ANNOUNCEMENT] Cygwin/XFree86 DocBook-based FAQ draft

["Harold Hunt" <huntharo at msu dot edu>]

Robert,

> * we should have multiple source files. Per topic or perhaps
> setup/user/developer. This allows better management of the content.
> Perhaps even one file per "topic". I know docbook can manage this for
> us.

Of course.  It should be evident from the User's Guide and XWin sources that
I support multiple files :)  However, I wasn't sure what the final divisions
of the FAQ would be, so I didn't want to break the source into several files
when I first posted it.

> * A make system should be provided. I'm happy to put that together (I
> suggest autoconf && automake be used as it has much smaller make files
> :} ). This is to make redistribution easier.

You really want to have the Cygnus DocBook-tools... then you just run
'db2html cygx-faq.sgml', or 'db2pdf cygx-faq.sgml', etc.

> * I suggest that we get a CVS area on cygwin.com for both the users
> guide and this faq. This will make multi-authoring easier. I consider
> making multi-author change control easy _very important_. What do you
> think? A CVS area for cygwin-xfree-doc would allow the docbook source
> and make system to be easily accessible to all the contributors, and
> allow effective interleaving of updates.

Might be easier to use SourceForge.

> * We need a stylesheet for this. (plain docbook sticks out like a sore
> thumb w.r.t. the website. This is my problem: I volunteered to create
> one for the straight html on the website... this is just

I don't think our sales will suffer as a result of not using a stylesheet :)

> * Have you considered docbook/xml rather than sgml? A year or so ago it
> was looking to be the continuity path for docbook... and it seemed a bit
> more flexable.

Yes, I have considered using DocBook XML instead of DocBook SGML, but at
this time DocBook XML is not a viable alternative.  The problem with DocBook
XML is, in the words of Norman Walsh on 2001-01-12, "You have to explicitly
pass the XML declaration to jade."  Now, that sounds all well and good,
until you realize that you can't tell the DocBook-tools utility 'db2html' to
pass the XML declaration on to jade.

In short, DocBook SGML works out of the box on most GNU/Linux distributions
and allows the use of DocBook-tools, whereas DocBook XML requires funky
command line parameters and/or a hacked set of DocBook-tools scripts.
DocBook XML won't take over until a good XSLT processor is included with
every GNU/Linux distribution; for now, DocBook XML is processed against the
SGML DTD, so there is almost no point in using DocBook XML.

On a side note, I have attempted to follow the stricter rules of XML in my
SGML files.  It is fairly likely that my SGML source will compile as DocBook
XML with very few changes.

Harold