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

["Robert Collins" <robert dot collins at itdomain dot com dot au>]

----- Original Message -----
From: "Harold Hunt" <huntharo@msu.edu>
To: "Robert Collins" <robert.collins@itdomain.com.au>
Cc: "cygx" <cygwin-xfree@cygwin.com>
Sent: Wednesday, May 23, 2001 11:57 PM
Subject: RE: [ANNOUNCEMENT] Cygwin/XFree86 DocBook-based FAQ draft


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

Sure :]. I have the same attitude. I don't understand why you think (I
don't || you don't). However doing without communicating can lead to
misdirected work / work that isn't as effective as as what happens when
we discuss things _before they become part of the project_. Thats what
open source usually entails. You've got a neat contribution here. Good.
It needs to be examined _before_ it gets added to the project. And no,
it doesn't need to be perfect before it goes in, but the roadmap needs
to have a couple of steps in it.

> 2) I'm perfectly happy with my current system of building and
distributing
> the documentation.

Good. I'm not intending that _you_ need to change. I'm pointing out what
I believe is needed to get a maintainable (for me) system to replace the
current maintainable (for anyone) HTML page. I'm expecting that I'll
still be keeping the FAQ maintained, as noone has offered to step to
that role on an ongoing basis. Thus.... I want a build system.

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

Hmm. I offered to build it a few emails back. (To which your reply was
db2html :]).

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

Uhhh. Total over the last 2 months is around 5 patches. And they were of
the form "foo is wrong"... not "here's a diff". _Thats why the
investment_.

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

Yah. I've been around this one before (when you started on you
userguide). It was no-go then, but I am a lot better of this time.
openjade && OpenSP don't actuall install their system catalogs, one has
to do that oneself (and the tutorial for cygwin-sgml authoring neglected
to mention that). However I'm basically setup now and ready to go.

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

Well thats good news in a sense. I'm back on the hunt for a fully
user-friendly authoring system.

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

Harold, I _know_ that. Thats why I listed multiple different options.
And knowing that db2pdf is available

____does not tell the end user which style sheet for what size paper and
so on____.

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

Thank you again. I'm trying to get the docbook-tools happy...  I've not
suggested we don't use docbook. I've not suggesteed that db2html not be
the conversion tool - if it's on a users system (& we're not using xml
stylesheets). Having a make system would address the difficulty you saw
with db2html before though.

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

That could be very neat. However today we have 2 small problems:
(1) the XFree86 CVS tree is on the wrong server (same issue as using
sourceforge IMO).
(2) building X is a huge task, and I cannot imagine _end users_ (such as
myself - can develop, just aren't developing on X) who are FAQ
contributors doing that to build a FAQ page to see how their patch
looks.

Rob

>
> Harold
>
>