[resending, gcc-patches won't allow a screenshot attachment]
On 11/10/2015 03:27 PM, David Malcolm wrote:
Correct, readable and well-organized documentation are laudable goals...
but I think that, to a first approximation, we're already there: I just
feel that the content is hidden behind a poor tool chain.
Hmmm, I just searched bugzilla for "documentation", and got 539 bugs
back. :-S (Bugzilla doesn't seem to have a component keyword for
"docs" or "manual" or anything like that, so the doc issues aren't
really tagged as such in any way.)
I believe that no matter how good we make the .texi files, the issues
with URLs, HTML page-splitting, etc with how texinfo's HTML generation
works will hold gcc back.
I don't see these problems as being so severe that it's worth losing
edit history by reformatting the whole document, and the time/effort it
would take to do and proofread the conversion.
BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for
the generated manuals, to make them a little "prettier". Maybe
something like that would go a long way towards solving the perceived
problems here?
I'm interested in seeing that, though presumably the URL and
page-splitting issues would remain (is this at the CSS level, or do you
make deeper changes to the HTML generation?)
Yes, CSS. It's nothing fancy; we specify some fonts and colors, and put
a shaded box around code examples to set them off better. I'm not sure
we have any online examples of HTML manuals accessible outside Mentor.
Probably we could contribute the .css file if anybody wants to hack it
up further to improve GCC's default manual formatting, but I'd have to
check that we don't consider that shade of blue proprietary or anything
like that. ;-)
-Sandra
