[ANNOUNCEMENT] Cygwin/XFree86 DocBook-based FAQ draft

[Harold Hunt]

Robert,

Before you read what follows you're going to have to understand a couple
things:
1) I program and I write documentation... I do things... talking doesn't get
things done.  :)
2) I'm perfectly happy with my current system of building and distributing
the documentation.
3) I'll use any logical build system that someone else creates, but
motivating me to create such a system myself is going to be nearly
impossible :)
4) In my view, the number of people submitting patches to the documentation
(total over the last 8 months: 0) doesn't yet warrant the investment of time
in creating a documentation build system.  However, see #3.

------------------------------------------------------------------------

I forgot to mention, DocBook-tools were/are developed by Cygnus.
DocBook-tools are simply a set of scripts that make building DocBook easier.
You can download DocBook-tools from any Cygnus mirror in docbook-tools/,
such as:
http://mirrors.rcn.net/pub/sourceware/docbook-tools/

You may want to look at Cygwin's DocBook build system, which uses db2html...
I noticed a small blurb about building Cygwin documentation at:
http://sources.redhat.com/cygwin/faq/faq_4.html#SEC88

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

Unfortunately, db2html works the same on GNU/Linux as it does on Cygwin.  :)
db2html doesn't work with XML on either platform.

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

Building a printable copy with DocBook-tools is easy: db2pdf, db2ps, db2dvi,
and dv2rtf.

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

Cygwin builds their documentation with db2html, and they mention in their
FAQ that you must install DocBook-tools in order to build the documentation.
I don't see why it would be a problem for us to do the same thing.

One more thing: the XFree86 tree comes with an optional set of documentation
building tools and there is a good amount of DocBook SGML documentation in
the XFree86 tree.  I wonder if the optional documentation building tools are
things like Jade, DTDs, stylesheets, and a build system for DocBook?  You
may want to look at building our documentation as part of the XFree86 tree
if these tools are distributed with XFree86 CVS.

Harold