cygxfree doco 1.0h

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

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

---

• To: <xslt at gnome dot org>
• Subject: [xslt] PATCH: xsl:document doctypePublic and doctypeSystem
• From: "Robert Collins" <robert dot collins at itdomain dot com dot au>
• Date: Sun, 27 May 2001 23:08:25 +1000
• List-Id: The Gnome XSLT library mailing-list <xslt.gnome.org>
• References: <031901c0e5ed$476e8890$0200a8c0@lifelesswks> <20010526101956.O22882@imag.fr> <005301c0e6a5$ab16e2d0$0200a8c0@lifelesswks>
• Reply-To: xslt at gnome dot org

This patch is incomplete. There an autogenerated DOCTYPE that is
_always_ output on stdout. IMO (Based on what little I've seen of the
xslt and xml librarie) that DOCTYPE shouldn't be generated. The patch
presented here causes each file written to have it's doctype created (if
one is present). I'm not sure how to go about removing the autogenerated
one that gets written to stdout.

Rob

xsl.document.patch

---

---

• To: <Daniel dot Veillard at w3 dot org>
• Subject: build libxml-1.8.9 on cygwin
• From: "Robert Collins" <robert dot collins at itdomain dot com dot au>
• Date: Sat, 26 May 2001 21:11:43 +1000

Hi, the attached patch allows libxml to build properly on cygwin.

I've moved the #ifdef WIN32 conditionals to acconfig.h , allowing all
files that include config.h to get the
#ifdef WIN32
#include "win32config.h"
#else
... config.h content
#endif

I then changed the #ifdef WIN32 to
#if defined (WIN32) && !defined (__CYGWIN__).

I figured that as there was a win32config.h.in, then a dumy config.h
would be created when you create your win32config.h.

If this doesn't seem the right way to you, I'm happy to revisit this.

Rob

buildoncygwin.patch

---

xml2cygwin.patch