documentation format and html output

[Karl-Friedrich R. <ra...@un...>]

Hi,

I was trying to work on the documentation a bit, but got quite
confused. ;-) Perhaps someone here can enlighten me.

* I found that all tables appear twice in docs/gnupot.doc, only i've
got not idea where the one that is readymade html code (with "^" in
the first column) goes, and why there are two redundant versions.
Stuff with "^" in the first column should (says docs/README) go to
doc2{tex,html}, only i don't see it in the output of "make html" or
"make pdf". (waiiit, it's in the wxhelp html output! So is stuff
with "^" in fact only for doc2html, not doc2tex?)

docs/README explains only the other version (between "@start table",
 "@end table" delimiters), that is clear mostly.


* docs/README says that text between backquotes is set to boldface.
Is it correct that this also automatically creates a link (in html,
pdf), if there is an interactive "?help keyword" with the same name?
And this does not work inside tables. (OK, im sure about this. I'll
add a note to the README)


* is the rest of the explanation of the backquotes complete? I find
it really hard to understand, as if there is a line or two missing.


* I've tried adding a few extra empty lines and comments (with "C"
in the first column) here and there, to make the doc source a bit
more structured. I saw no problems, but do empty lines have any
significance except forcing a line break in continuous text?


* "make html" throws a billion errors. I get an html output in the
end, sometimes, but it looks very broken. There are errormessages
from latex2html that options are missing from the "inputenc" and
"hyperref" package. Only my latex2html version (2008) seems to not
have a hyperref package. (i also tried "make html" in the 4.6 tree,
and there it tries to call "htlatex" instead of latex2html.
docs/README in 5.1cvs says it wants to use htlatex, too, but doesn't?)

I tried searching the web a bit and found a few messages on
gnuplot-beta and in the bug tracker, but I'm not really clear how
the status of this is.


* ("docs/make distclean" is broken in 5.1cvs, i've already set up a
ticket on sf.net)


* docs/README mentions a make target "pdffigures" that's gone, but
there is one "pdf_figures" that imo does the job advertised. Change
that in the README? Otoh I don't really see how it is useful as a
standalone target, so perhaps the comment can go.


* lastly, does anyone have some hints/tricks for working with the
gnuplot.doc file? Some editor that is able to do a bit of syntax
highlighting, perchance?


Best, Karl