Menu
▾
▴
gnuplot-beta
|
From: Karl-Friedrich R. <ra...@un...> - 2015-08-17 23:32:52
|
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
|
|
From: Ethan A M. <sf...@us...> - 2015-08-18 00:16:10
|
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 |
|
From: Hans-Bernhard B. <HBB...@t-...> - 2015-08-18 18:21:07
|
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.
|
|
From: Karl-Friedrich R. <ra...@un...> - 2015-08-18 23:34:20
|
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
|
|
From: Hans-Bernhard B. <HBB...@t-...> - 2015-08-19 22:01:38
|
Am 19.08.2015 um 01:34 schrieb Karl-Friedrich Ratzsch: > Am 18.08.2015 um 02:12 schrieb Ethan A Merritt: > 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. Well, maybe there's a reason all the existing links are spelled like this instead: ^ <a href="#positive"> positivelink ^ </a> ;-) > 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. Note that the note is already there --- only it's just about *roff output, so far. The limitation, and the reason for it, is the same for the other "clever" output formats, though: the doc2* tools can't generate correct table syntax for the various output formats as-is, much less if they're to mark-up parts of the tables' content, too, while trying to do that. > 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? Why make such a major change, when every self-respecting programmers' text editor can regex-search for, e.g., /^3/ ? > 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. Ah, but it is! For _plain_text_ tables, that is. |
|
From: Karl-Friedrich R. <ra...@un...> - 2015-08-20 21:29:32
|
Am 20.08.2015 um 00:01 schrieb Hans-Bernhard Bröker: > Am 19.08.2015 um 01:34 schrieb Karl-Friedrich Ratzsch: > >> 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. > > Well, maybe there's a reason all the existing links are spelled like > this instead: > > ^ <a href="#positive"> > positivelink > ^ </a> > > ;-) Ah! Still it never used, can't be, because there is a bug in doc2tex, the link gets two closing brackets too many. I uploaded a fix: https://sourceforge.net/p/gnuplot/patches/719/#646e >> 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? > > Why make such a major change, when every self-respecting > programmers' text editor can regex-search for, e.g., /^3/ ? Oh, I don't have so much respect for myself as a programmer. And you said nobody had an editor with syntax highlighting for the gnuplot docs. ;-) I noticed the diff format is rather similar, and i might perhaps dig myself into finally learning regular expressions and adjusting gedits highlighting scheme to the gnuplot.doc format. Let's see. Still, i see no harm in adding an empty line before every heading. Similar looking source code still works, but gets frowned upon. > >> 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. > > Ah, but it is! For _plain_text_ tables, that is. Which are indented much further. Ah! So the rule might better be "Plaintext tables get indented so as to at least leave a space in column 2." But plaintext always has fixed line feed anyway. Does that rule make any difference? (Of course it makes a lot of sense to indent tables.) Karl |
|
From: Hans-Bernhard B. <HBB...@t-...> - 2015-08-21 19:40:53
|
Am 20.08.2015 um 23:29 schrieb Karl-Friedrich Ratzsch: > Ah! Still it never used, can't be, because there is a bug in > doc2tex, the link gets two closing brackets too many. I uploaded a fix: > https://sourceforge.net/p/gnuplot/patches/719/#646e I think I'll do my own fix ;-) >> Why make such a major change, when every self-respecting >> programmers' text editor can regex-search for, e.g., /^3/ ? > Oh, I don't have so much respect for myself as a programmer. You misinterpreted that statement. It's the editor that's supposed to be self-respecting. "Programmers' text editor" is a somewhat well-established tool category. Note how the placement of the "'" makes a little difference :-) > And you said nobody had an editor with syntax highlighting for the > gnuplot docs. ;-) Well, you were asking about syntax highlighting, so I answered that question. If you had asked about navigating from node to node right away, you would got the answer about regexps in editors earlier. > Still, i see no harm in adding an empty line before every heading. Well, empty lines may have meaning, and may be passed through to some of the output formats. They might create silly blank space at the end of pages / paragraphs. That doesn't feel like a risk worth taking just to avoid typing something as easy as <Ctrl-Meta-s> ^ 3 or <ESC> <Ctrl-s> ^ 3 (in Emacs) or / ^ 3 (in Vi) ;-P And who's going to be making sure that those empty lines are consistently maintained in the future: you? Will you get mad at others if they remove them, or if they forget to add new ones when they add new sections? gnuplot.doc is newline-heavy enough as it is. We don't need to spend even more screen real estate for empty lines. > Which are indented much further. Ah! So the rule might better be > "Plaintext tables get indented so as to at least leave a space in > column 2." No. The blank in column two is actually an active character. It means "output this entire line verbatim" (for both LaTeX and plain text output). |
|
From: Christoph B. <us...@be...> - 2015-08-24 13:19:59
|
Am 18.08.2015 um 01:08 schrieb Karl-Friedrich Ratzsch: > > * "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. For this reason, that no proper LaTeX-to-HTML-converter exists, I proposed a standalone doc2html converter, of which I posted a first version as patch on sf: http://sourceforge.net/p/gnuplot/patches/683/. Since I got no real feedback I didn't go on. But the doc format isn't so complicated that one cannot have an own doc2html converter. One could use this converter to get one single-file documentation, a multi-file documentation and a responsive version using e.g. bootstrap or whatever. Christoph |
