This is the mail archive of the cygwin-apps mailing list for the Cygwin project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: HELP with Cygwin docs needed

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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]