#719 documentation update

[Karl Ratzsch]

I want to work on the documentation a bit, and my first goal was trying to correctly understand the format.

I've now updated informations in docs/README from what i've found, the change contains:

• formatting of the text (starred lists, more spacing)
• resorting of the example to match the style found in the actual docs (first heading, then keywords)
• proposed style change to have a line spacing before headings
• update on which control characters are used by which formats

I regard this by no means as ready for inclusion. Comments are welcome, I hope I've gotten most things right.

[Karl Ratzsch]

After Hans-Bernhard pointed out to me how

^ <a href="#lnktarget">

is correctly used, i found out why it is not actually used: docs/doc2tex.c:238 closes two curly brackets too many.

Attached patch fixes that.

To trigger the error, add

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

somewhere in docs/gnuplot.doc.

[Ethan Merritt]

I don't think that patch can be correct.
Yes there appear to be 2 extra closing brackets '}', but only one of them comes from this line of the source code. The other one comes several output lines later.

{\bf  (p.~\pageref{positive})}} \preverbatim   % first extra } is here
\begin{verbatim}
positivelink
}                               % second extra } is here

\end{verbatim}
\postverbatim

Or maybe the second } comes 2 lines too early. I'm not sure what the intent is.

.... after a bit of experimentation ...

That whole section of code is borked. The correct output is

{\bf positivelink}
{(p.~\pageref{positive})}

How to get there from doc2tex is left as an exercise :-)

[Karl Ratzsch]

(Ah, it breaks when you add a second space before "positivelink". The verbatim and boldface environment then cross. Didn't try that.)

My understanding was that the text "positivelink" in my example should be boldfaced, because it comes before "\</a>" in the doc source.

Otoh, pagelinks with boldfaced text are already done finely with backquotes. Perhaps the html link should only be a hypertext link, without page number? As it is not used at the moment, we could easily change it.

[Ethan Merritt]

I don't really care about the boldface. The part that is broken is that the text that is supposed to be hyperlinked ("positivelink" in your example) does not get printed until after the actual linkpoint ("(p. xxx)" as generated by the \pageref macro).

I suspect this is pointless. What is this mechanism needed for? The expansion of "see positive" is done correctly and serves the same purpose.

[Hans-Bernhard Broeker]

I just checked in my own go at a patch for this.