Re: documentation format and html output

[Hans-Bernhard B. <HBB...@t-...>]

Am 18.08.2015 um 01:08 schrieb Karl-Friedrich Ratzsch:
> * I found that all tables appear twice in docs/gnupot.doc,

Actually, make that _four_times_ ;-)

$ grep 'back a single' gnuplot.doc
        ^B    moves back a single character.
#\verb~^B~ & move back a single character.\\
%^B@move back a single character.
^<tr>    <td><tt>^B</tt></td>    <td>move back a single character.</td></tr>

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

I think it's because it would be quite hopeless to extract usable table 
content for four different from the same input.  Making the doc2*** 
programs clever enough to do that would be more work than doing all the 
tables multiple times.

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

Some of it is.  doc2tex only picks up the hyperlinks.  All other HTML is 
for doc2html only.

> * "make html" throws a billion errors. I get an html output in the
> end, sometimes, but it looks very broken.

Latex2html _is_, for all intents and purposes, broken. It just doesn't 
want to work with current-day Perl any more.  And none of the 
alternatives really work, either, for what we want to do.  We may have 
to consider that type of HTML generate a dead parrot.

> * docs/README mentions a make target "pdffigures" that's gone, but
> there is one "pdf_figures" that imo does the job advertised.

Not really.  That target really just makes the figures, but not the pdf 
with the included.  You want "make pdf".

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

I'm quite sure there isn't.  A total of about 5 people in the world ever 
work on that document.  That's just not enough of a user base for anyone 
to create an Emacs mode or whatever for this really rather tricky file 
format.