This is the mail archive of the
cygwin-patches
mailing list for the Cygwin project.
Re: [PATCH] DocBook XML toolchain modernization
- From: Warren Young <warren at etr-usa dot com>
- To: cygwin-patches at cygwin dot com
- Date: Tue, 30 Apr 2013 15:53:58 -0600
- Subject: Re: [PATCH] DocBook XML toolchain modernization
- References: <20130424172039 dot GA27256 at calimero dot vinschen dot de> <51782505 dot 5020502 at etr-usa dot com> <20130424185210 dot GE26397 at calimero dot vinschen dot de> <51783EBC dot 30409 at etr-usa dot com> <20130425084305 dot GA29270 at calimero dot vinschen dot de> <517F15AF dot 5080307 at etr-usa dot com> <20130430184703 dot GB6865 at ednor dot casa dot cgf dot cx> <51801469 dot 9070606 at etr-usa dot com> <20130430190706 dot GC6865 at ednor dot casa dot cgf dot cx> <51802510 dot 5000803 at etr-usa dot com> <20130430202737 dot GA1858 at ednor dot casa dot cgf dot cx>
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.