[ANNOUNCEMENT] Cygwin/XFree86 DocBook-based FAQ draft

Robert Collins robert.collins@itdomain.com.au
Wed May 23 01:13:00 GMT 2001


----- Original Message -----
From: "Harold Hunt" <huntharo@msu.edu>


> Robert,
>
> 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.

Cool. Ok lets leave the breaks until we're onto the content alone.

> > * 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.

Yes but :]. I seem to be missing those even though openjade is now
_mostly_ happy on my box. (Thank you Marcus' doco). So db2hmtl for me is
openjade -v -d test.dsl test.sgml
Secondly, converting the files is _one_ operation. We have more than one
operation: build a web site copy (collate the howto and the faq in
correct directories vs build a printable copy (sure it's only a
stylesheet change) vs make a tarball for downloading from the website.

> > * 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.

>From a use-of-cvs it should be no different. And I don't think we want
to split up the parts of the project if we don't need to.

> > * 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 :)

True, but the faq will look ugly without one ;]. And an approachable faq
is one that will hopefully get read a little more often than not.

> > * 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
>

Thank you for looking into the XML side. I'm not too concerned about
what GNU/Linux distro's come with... (I have openBSD or win32 here, and
I believe we should have no expectation that contributors/users are
working on anything but cygwin).
So, given that with the current cygwin, openjade && openSP no longer
build easily (I'm getting a set of feedback for Marcus together), we
still don't have an OOTB solution for making (note: not editing..)
docbook based documentation.
Secondly, the problem I see with attempting to switch later, is that
other authors won't follow the stricter rules, unless their
contributions are validated against an XML DTD now.

Does that make any impact on the suggestion? (ie db2html isn't likely to
exist for cygwin based users for a while yet.) AFAICT funky commandline
parameters are needed for any cygwin author :/.

Rob



More information about the Cygwin-xfree mailing list