[PATCH] DocBook XML toolchain modernization

Wed May 1 01:28:00 GMT 2013

On 4/30/2013 18:31, Christopher Faylor wrote:
>
> I don't think it's worth the
> effort and expense of duplicating Cygwin's CSS elsewhere

You might be mixing two of my proposals together.

This offer to provide a "FAQ body contents only" output would probably 
just be a ~10 line Perl script to extract the text between <body> and 
</body> in an input HTML file and store it in an output file, then tie 
the two together with a Makefile dependency.

The idea is that on your end, all you do is change the referent from 
.../winsup/doc/faq/faq.html to something like .../faq-body.html.

I have decided: the script shall be called bodysnatcher.pl. :)

Separately, I have proposed improving the styling of, e.g.:

	http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html

I would prefer not to copy and hack on your CSS file.  I'd be happier if 
I could just reference it via URL.[1]  Unfortunately, while the standard 
DocBook XSL stylesheets output HTML that is easy to style with CSS (lots 
of classes, well-named divs, etc.) its names are all different from 
those you have used in your HTML.

Later, we can talk about using bodysnatcher.pl more broadly, to make a 
version of the user guide that will pour into your new navbar HTML 
files.  At that point, we'll need to talk about a way to merge our two 
CSS variants.

By the way, the top page of cygwin.com has two different FAQ links.  The 
one that points to /faq/faq-nochunks.html should probably point to 
/faq.html.

> ...new DOCTOOL tags.  I don't know who first thought that adding
> these was a good idea

*shrug*

It's a common practice[2] to have verbose comments on public interfaces, 
and to format them in a way to make reference documentation generation 
easy.  Doxygen knows one common syntax for this, and its output is 
beautiful and useful.

Here's a Doxygen based reference manual I created:

     http://tangentsoft.net/mysql++/doc/html/refman/

If you decide it's better to fully extract the API docs from the code, I 
can go with that instead.

> if Corinna
> agrees when she gets back, I'd like to just get rid of these.

I have no problem waiting on some of this stuff until then.  I'm not in 
any hurry.  I'm just asking questions as they occur to me so I don't get 
blocked later when I decide to start making changes.

[1] http://goo.gl/6U6gG
[2] https://en.wikipedia.org/wiki/Comparison_of_documentation_generators