This is the mail archive of the cygwin-patches 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: [PATCH] DocBook XML toolchain modernization


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


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