Re: HELP with Cygwin docs needed

[Warren Young <warren at etr-usa dot com>]

On 4/24/2013 11:20, Corinna Vinschen wrote:
> - What is the advantage of changing the format?

Actually, a bit more looking makes me wonder if the docs actually *are* 
still SGML.  All the processing now seems to go through xmlto, rather 
than OpenJade.  Without digging through the CVS history, I suspect the 
conversion was already made, and the files just didn't get renamed to 
reflect their new format.  Perhaps that's because Cygwin is still hosted 
in CVS, so that a rename would break revision history.

Anyway, the advantage that prompted my question is that if you hadn't 
figured the problem out on your own, I think you would have gotten more 
help replies, faster, if you'd asked if anyone knew DocBook and xmlto 
instead of SGML and xmlto.  SGML DocBook is essentially a legacy 
document format now, used by those who can't or won't convert.

(I base that judgement on being a DocBook user for nearly a decade, and 
following the DocBook mailing list the whole time.  DocBook SGML was 
already on its way out when I got started, so I never even bothered 
going down that path.)

Other advantages of the XML dialect over the SGML dialect:

- SGML predates Unicode, so the tools typically don't support it.  XML 
was designed with Unicode in mind from the start.  Umlauts without 
hackery! :)

- The DocBook XSL stylesheets maintained by Norman Walsh are kept more 
up to date with the current DocBook dialect.  In fact, it's looking like 
DocBook 5 will never be available in an SGML dialect.

- The DocBook 4 and earlier specs were written so that the XML and SGML 
dialects are supposed to be treated identically by tools consuming them, 
but that guarantee has no substance without two equivalent sets of 
stylesheets.  Because the SGML stylesheets aren't kept up to date, the 
compatibility guarantee from the spec is toothless, unless you're 
willing to maintain your own set of stylesheets.

- The tools to process XML, XSL, XSLT, and XML-FO are also all kept in 
better shape than the old SGML based tools.

- Having never used the SGML dialect of DocBook, I do not know for 
certain, but I suspect it's easier to hack DocBook XML.  E.g. Via local 
XSLT stylesheet overrides.

- I think you could avoid the need for all that & and < hackery 
in your C code snippets in the docs if you used XML's CDATA feature.

>    I write the docs in vi.

Me, too. :)

>    don't want to use some GUI editor

Sadly, the GUI tools for DocBook XML really aren't where they ought to 
be, even if you wanted to use them.

For example, there *should* be a basic DocBook based word processor 
along the lines of LyX, but there isn't.

Instead, those wanting a simplified WYSYWYG presentation have to deal 
with monstrous XML powerhouses like oXygen.  And even then, WYSIWYG 
isn't the right term for for the experience.  It's more like the bad old 
days of web development where no two browsers gave the same result for a 
given bit of markup.

>    I wouldn't want to have relearning how to write the
>    docs, unless there's a definitive advantage here.

The XML and SGML dialects of DocBook really aren't that different, in 
the main.  You still have your <sect1> and <para> type stuff.  Where 
they differ is in the toolchain and the customization layers.

And as I now see, it looks like most of this work has been done already. 
 It looks like the main things remaining would be to rename *.sgml to 
*.xml and *.dsl to *.xsl to reflect their actual current contents, wrap 
the "SGML" fragment documents in proper XML containers, and then 
probably switch from the nonstandard doctool to XIncludes.

I suspect that if I did that, you won't immediately see a difference, 
except that all .sgml became .xml.

> - Will it work equally well to build the docs on Cygwin and on Fedora?
>    Are the tools part of a default distro in both environments?

The GNOME docs are split between DocBook XML and SGML[1].  So, yes, you 
can generally count on having the DocBook XML tools installed on Red 
Hattish Linuxes.  And if not, say because you've got a minimalist 
install, the tools are in the stock repos.

As for Cygwin, I've built my two DBX manuals under Cygwin before, just 
to prove it can be done.  I tend to build on Linux and OS X for normal 
development, however, so it's been a while since I've tried this.

[1] https://en.wikipedia.org/wiki/Xinclude
[2] http://goo.gl/jDmuw