cygxfree doco 1.0h

[Robert Collins]

This "release"
http://users.bigpond.net.au/robertc/cygxfree-doc-1.0h.tar.gz
contains
* new draft users guides, contributors guide, migrated into the
authoring framework (Harold)
* XML/XSL Support for the faq. (Robert)

I'm nearly at the point where I can move onto the content review.
Why XSL? The XSL support was a critical step. The DSSSL/SGML stylesheets
are at end of life. They will be deprecated in docbook 5.0 (the next
release). The XML/DSSSL variant produced non-validatable HTML. However
XML with XSL is working very nicely.

Volunteers wanted! The following packages are needed to build the doco:
[o]nsgmls(found in jade/openjade).
xsltproc(found in libxslt).

I will generate binary packages for cygwin, and make those available to
anyone who wishes to build the doco, but I'm not able to commit to any
sort of regular maintenance for them. Thus maintainers are needed.

I have attached the various emails I've sent to the dependant packages
in puttin gthis together, along with a libxml2 patch that I haven't sent
off yet. The libxml1 patch will apparently break win32 builds (I can't
see how given what was in their download but ...). You will need to
apply those patches if you want to build these tools _correctly_ on
cygwin.

Likewise, there is a bug with libxslt 0.10.0 and before that prevents
doctypes being created in the output html files, this would prevent
successful HTML validation. (And such compliance is important IMO). That
patch will be needed on any platform.

Feedback on the build mechanism,
not the content,
is appreciated.

Now, lastly, a little remark on the tool selection.

For a starting point docbook is pretty much guaranteed to be the best
authoring language for our needs. It's used all over the place, for good
reason.
Within docbook you have 3 official choices:
Docbook SGML/DSSSL
Docbook XML/DSSSL
Docbook XML/XSL

The first 2 use any dsssl processor (openjade will compile, with the
instruction from marcus's site referred to by Harold a few days ago -
although a little investigation is needed). The 3rd uses any XSLT
processor that is XSLT 1.0 or therabouts comformant.

I've been through the reasoning above as to why XML/XSL makes sense for
us. What about tools for XSL? It's a standard, it'll be supported, piece
of cake. Yeah. Right.

There are two basic options: java (ie saxon) or non-java (ie
sablotron/libxslt/xalan).
Java: this is a problem on cygwin, due to all the JVM's having "\"
separators and being ignorant of the cygwin mount table.
nonjava: This should have been easy. However....
sablotron: Built real esay, with one trivial patch for it's xml
processor. Not functional enough to do the job, although it's real fast.
I'm keeping an eye on their mailing list, if/when it gets up to speed
I'll probably add  support to the configure script for it.
xalan: I recommend this, and xerces as an example of how to abuse
automake and autoconf such that all benefit they provide is lost.
libxslt: Very nice. The libxml[1|2] libraries could have been made a
little better portability wise (WIN32 != MSVC grrr) but otherwise no
problems. Static libraries only at this point I think, but they all have
the exports defined correctly such that it should be easy to make them
dlls' (they use libtool so that needs fixing first).

So xsltproc from libxslt is the _only_ tool I found that can do xsl
stylesheet processing from cygwin, without needed major ugly stylesheet
or dtd manipulation.

Now that the faq validates properly, my next task is inserting the web
page via the xsl driver. That should be trivial compared to what has
gone before though.

However that is at least 3 days away, with my expected week. Thus this
early partially converted announcement, to let everyone have a play.

Rob
-------------- next part --------------
A non-text attachment was scrubbed...
Name: buildoncygwin.patch
Type: text/x-diff
Size: 7835 bytes
Desc: not available
URL: <http://cygwin.com/pipermail/cygwin-xfree/attachments/20010527/a20914c0/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xml2cygwin.patch
Type: text/x-diff
Size: 4273 bytes
Desc: not available
URL: <http://cygwin.com/pipermail/cygwin-xfree/attachments/20010527/a20914c0/attachment-0001.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xsl.document.patch
Type: text/x-diff
Size: 1280 bytes
Desc: not available
URL: <http://cygwin.com/pipermail/cygwin-xfree/attachments/20010527/a20914c0/attachment-0002.bin>