[PATCH] DocBook XML toolchain modernization

Tue Apr 30 21:54:00 GMT 2013

On 4/30/2013 14:27, Christopher Faylor wrote:
> On Tue, Apr 30, 2013 at 02:09:52PM -0600, Warren Young wrote:
>>   Embedding <html> within <html> is eeevil.
>
> faq.html is a pretty simple file and it seems to work.  Are there any
> non-religious advantages to doing this?

Conceivably browsers could stop tolerating it.

Given how tolerant browsers still are, that eventuality might seem 
unlikely, but such shifts have happened.

In the early web, this was considered acceptable HTML:

     <a name="foo">
     <h1>Foobie</h1>

In older browsers, this wouldn't do anything more than let you reference 
#foo within the document.

Today's browsers, though, see an open <a> tag and treat the entire rest 
of the page as one big hyperlink.  You can get weird effects, like 
paragraphs of text highlighting with the "clicked link" color when you 
click on such a page.  To fix it, you must close the tag, so:

    <a name="foo"/>
    <h1>Foobie</h1>

That, or change from named anchors to fragment identifiers:

     <h1 id="foo">Foobie</h1>

But I won't insist that you accept the new output. :)

>> - Any comments about the other items in my FUTURE WORK section?
>> Unconditional green light, or do you want to approve them one by one?
>
> You have the right to change anything in the doc directory.  Anything
> outside of that will require approval.

The final removal of doctool requires replacing the DOCTOOL/SGML 
comments in winsup/cygwin/{path,pinfo}.cc with Doxygen comments, and 
folding most of the contents of winsup/cygwin/*.sgml into Doxygen 
comments within the relevant source files.

I haven't deeply looked into this.  The only thing that looks at all 
tricky is posix.sgml, which might have to be artificially converted to a 
posix-api.h file just to fit within the Doxygen world.

All of this affects how cygwin-api.pdf and the HTML equivalents get 
built.  My changes so far don't affect these at all.

I assume you've come across Doxygen before in your travels.  I find its 
output far more useful for API references than DocBook.  And, Doxygen is 
in Cygwin, under someone else's maintenance now.