Re: documentation format and html output --

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

Am 18.08.2015 um 02:12 schrieb Ethan A Merritt:
> On Tuesday, 18 August, 2015 01:08:13 Karl-Friedrich Ratzsch wrote:
>> 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.
> 

Ah, I see. Lines beginning with "^ <a href" or "^ <a name" are
inserted as a hyperlink target or label by doc2tex:217 following,
other lines with first character "^" are ignored, and used by
doc2html only.

There are currently only two hyperlink labels in the whole text,
which are only referenced by using backquotes (in the "rgbformulae"
chapter).

Trying to link to them using

^ <a href="#positive">positivelink</a>

was not possible, pdflatex complains about runaway arguments and
unfound references. Hm. I'll look into this.


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

Doesn't, it does not even get boldfaced in a Table. TeX converts the
backquotes into typographic quotation marks instead. I'll add a note
to the README.


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

I wanted to add an empty lines before section heading, two for
levels 2,3, to make navigation in the source a bit easier. Any
objection to changing that style rule?


>> * "make html" throws a billion errors. I get an html output in the
>> ...  
> 
> "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.

I know, I've used htlatex for another project. Some things go quite
well, others not. And it's mostly unmaintained, too. I guess I don't
need to test against the html target anway, as it doesn't work on
gnuplot.doc directly but on the .tex file.


As for tips&tricks, I found the program docs/checkdoc, which does at
least some very basic syntax checking on gnuplot.doc. It is called
by "make check-local". And for syntax highlighting, i tried gedit
with the "diff" format, which is a bit similar. I think that could
be adapted without too much work. Already looks not bad now.


There is one comment in docs/README, saying

	Tables must have a space in column 2.

Any idea what this means? It is never done.


I've set up a patch to docs/README on sf.net, comments are of course
welcome. https://sourceforge.net/p/gnuplot/patches/719/


  Karl