This is the mail archive of the
cygwin-apps
mailing list for the Cygwin project.
Re: HELP with Cygwin docs needed
- From: Warren Young <warren at etr-usa dot com>
- To: cygwin-apps at cygwin dot com
- Date: Wed, 24 Apr 2013 12:31:33 -0600
- Subject: Re: HELP with Cygwin docs needed
- References: <20130423152014 dot GG26397 at calimero dot vinschen dot de> <5178049C dot 7000108 at etr-usa dot com> <20130424172039 dot GA27256 at calimero dot vinschen dot de>
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