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
