GNOME Bugzilla – Bug 103595
gtk-doc HTML output format unreadable by lynx browser
Last modified: 2004-12-22 21:47:04 UTC
The docs generated by gtk-doc for GNOME cannot be read by the lynx browser. The main issue seems to be around the termination of the <STYLE> element; lynx apparently doesn't like gtk-doc's habit of separating the closing > from the element-name, and in particular it can't parse the </STYLE> when it occurs thus: ... }</STYLE ></HEAD ><... If the above line containing "STYLE" is changed to read }</STYLE> or if the 'STYLE' closing tag is move to a separate line, then lynx can work fine. THis may indeed be brokenness in lynx, but the end result is that all of our HTML docs are inaccessible. Can we put a workaround in our stylesheet to change the output in this way?
lynx is broken in that it doesn't accept this valid (if unusually formatted) html. The formatting comes from the jade backend which is used. I don't remember exactly, but there may be a way to turn it off.
I talked to Daniel Viellard about this (he should know!). He says that the STYLE and SCRIPT tags in HTML have stricter rules than other tags, and that jade is at fault here; in his opinion jade should definitely *not* be outputting this format for STYLE and SCRIPT. He also inferred that breaking the closing element tag for STYLE may indeed be incorrect, even though it's OK for other tags.
I think this is a WONTFIX ... It's Jade's fault. Jade is not particular actively maintained, and gtk-doc now supports xsltproc. Parts of GNOME that aren't using xsltproc and Docbook XML yet should get upgraded. gtk-doc could probably post-process the output -- wouldn't be hard to write gtkdoc-fixuphtmloutput that gtkdoc-mkhtml calls, but I don't really see it as being that valuable.
Agree with Owen, unless you have some people with jade expertise and some free time, the time would be better spent fixing the toolchains and document for the XML path than trying to salvage the SGML one... Daniel
OK, so long-term fix is to move to XSLT, which is no surprise. Perhaps this means filing RFEs against various GNOME packages for that purpose? Maybe this should turn into a 'tracking' bug for those.
James Henstridge found a workaround for openjade which is to pass '-t sgml-raw' as the output format type rather than '-t sgml'. That is now in cvs, and in 1.0 which will be released soon. That only works if you're using openjade, though. Not for jade.
*** Bug 104030 has been marked as a duplicate of this bug. ***
Updating status_whiteboard field to reflect A11Y team's assessment of accessibility impact.
I think we should close this bug (soon) after opening new bugs for the API docs for modules which are in GNOME developer platform which haven't been ported to xsltproc from jade yet.
Ok, I've filed bug 111791 against GConf bug 111793 against at-spi bug 111794 against gail bug 111795 against libart bug 111796 against libgnome bug 111797 against libgnomecanvas bug 111798 against libgnomeui bug 111799 against libxml2 bug 111800 against libxslt this covers the 22 platform modules as per http://developer.gnome.org/dotplan/modules/ Closing this as WONTFIX now.
Okay this may sounds crazy but how do you make that switch ? I need something very practical, guidelines or instructions on-line are fine ... Daniel
Daniel, taking a look at the patch for bug 111794 (RESOLVED) may help. I expect the other patches will look much the same.