Re: documentation format and html output

[Ethan A M. <sf...@us...>]

On Tuesday, 18 August, 2015 01:08:13 Karl-Friedrich Ratzsch wrote:
> 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?)

Lines starting with ^ generate hyperlinks in the pdf documentation also,
created via the *.tex file.

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

Inside a table definition:
lines with space in the first character are for the *.gih output
lines with # are for *.tex
lines with ^ are for *.html
lines with % are for troff output, which probably hasn't been tested
      since forever

I do not know which of these may also be used by doc2ipf or doc2rnh.


> * 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?

Yes.

> And this does not work inside tables. (OK, im sure about this. I'll
> add a note to the README)

I have never tried to do that, so I don't know.

> * 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?

The README discourages blank lines as a matter of style, but I think
this has not been uniformly applied in practice.

> * "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.

"make html" has not worked usably for many years.  It used to
invoke latex2html, but that package is no longer supplied or supported
by current TeX bundles.  I've had somewhat better luck with htlatex,
but not enough luck to consider it a real option IMHO.
In particular I could never get it to include figures correctly.

> * ("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.

Those issues are both due to a relatively recent revision by HBB,
but I guess he forgot to update the README in parallel.
"make pdf" now includes the figures by default so there is no
need for a separate "make pdffigures" target in the Makefile.
Instead there is a "make pdf_nofig" target if you really need it.

> * 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?

Sorry, can't help there.

	Ethan


> 
> Best, Karl
> 
> 
> 
> 
> 
> 
> 
> 
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> gnuplot-beta mailing list
> gnu...@li...
> Membership management via: https://lists.sourceforge.net/lists/listinfo/gnuplot-beta