Menu ▾ ▴

#2353 Some problems of gnuplot.doc of version 5.5

None
closed-out-of-date
nobody
None
2023-01-16
2020-11-11
Shigeharu TAKENO
No

I found some problems of current docs/gnuplot.doc (2020-11-09).

1) In section "2 New features", level 4 section starts without level 3 section. The old level 3 section "3 Development version" seems to be omitted. But, it makes bad index for Windows help (.chm file).
2) HTML table includes '>' or '<' directly. I this these should be '>' or '<'.
3) There are some level 4 sections which have # or % lines and don't have explanations: expint, ibeta, igamma, invibeta, invigamma, SynchrotoronF, FresnelC, and FresnelS. In LaTeX/PDF file, these section are ignored. But, they exist with no contents in windows help or texi file. I this these sections should be commented out.
4) Explanations for Ai(z) and Bi(z) are "complex error function" in % lines, but they may not be fit to # line ("complex Airy function").
5) There are no % lines of BesselH1 and BesselH2 for Amos library.
6) 'sin' and 'cos' may be italic in some #TeX lines (Elliptic, Fresnel).
7) The position "Ffigure_smooth_path" may be incorrect. In fact, it will appear in the previous section in Windows help.
8) Some typo.

And I found 2 problems of docs/doc2tex.c and docs/windows/doc2html.c.

9) Some entry in function tables in LaTeX file will be indented
with one or two spaces. This may be caused by \label{} or
\index{} lines in LaTeX file. It may be solved by adding '%' to
the end of the line in doc2tex.c.
10) In windows help some lines of 'TeX ...' remain for #TeX line.
this is the problem of docs/windows/doc2html.c.

Attached patch is for above problems. Please check it.

1 Attachments
diff-70

Discussion

  • Ethan Merritt

    Ethan Merritt - 2020-11-11

    Most of this patch is very helpful. I am particularly happy to see a fix for the unwanted indentation of entries in the TeX tables.

    The one thing that does not work for me is moving the position of "Ffigure_smooth_path". The proposed change corrupts placement of the section heading in the TeX+pdf output. It looks to me that doc2tex.c and windows/doc2html.c disagree about the intended positioning of figures.

    Question: I think you are correct that the level 4 section heading are unnecessary inside a table. But this is true whether or not there is associated plain text following the heading, right? So maybe we could remove all the level 4 section heading inside a table, not just the ones have text. Would that break anything in the Windows documentation output?

     

  • Shigeharu TAKENO

    Shigeharu TAKENO - 2020-11-12

    The one thing that does not work for me is moving the position of "Ffigure_smooth_path". The proposed change corrupts placement of the section heading in the TeX+pdf output. It looks to me that doc2tex.c and windows/doc2html.c disagree about the intended positioning of figures.

    In Windows help, 1 section is 1 page. Original position of Ffigure_smooth_path (before "5 path"), the figure appears in the previous section's page of "smooth mcsplines", and the page of "smooth path" does not have any figure. For the Windows help, the line "Ffigure_smooth_path" is need to be after the line "5 path". If the position of my patch is not good for PDF, please try:

    ----- From -----
    --- docs/gnuplot.doc.ORG 2020-11-09 19:07:08.505616000 +0900
    +++ docs/gnuplot.doc 2020-11-12 16:55:05.646327000 +0900
    @@ -7579,7 +7579,6 @@
    FN Fritsch & RE Carlson (1980) "Monotone Piecewise Cubic Interpolation",
    SIAM Journal on Numerical Analysis 17: 238246.

    -Ffigure_smooth_path
    5 path
    ?commands path datafile smooth path
    ?plot datafile smooth path
    @@ -7589,6 +7588,7 @@
    ?path
    The smooth path option generates cubic splines to fit points in the order
    they are presented in the input data; i.e. they are not first sorted on x.
    +Ffigure_smooth_path
    This generates a smooth spline through a closed curve or along a trajectory
    that contains loops. This smoothing mode is supported for both 2D and 3D
    plot commands. As always, a separate curve is created for each set
    ----- To -----

    Question: I think you are correct that the level 4 section heading are unnecessary inside a table. But this is true whether or not there is associated plain text following the heading, right? So maybe we could remove all the level 4 section heading inside a table, not just the ones have text. Would that break anything in the Windows documentation output?

    If the level 4 section has the explanation part, it will be expanded the section title and the explanation on Windows help, texinfo file, and so on. But if it has only #line and %line, the section will be expanded to the section title only. So, I think any section heading without explanation part may be removed.

    Moreover, I think that lower case is better as the section title of new functions whose real function name is lower case: Expint, Gamma, Igamma, Invigamma, Ibeta, Invibeta. It will appear
    the index of Windows help. But indexes of other functions are lower case.

     

  • Ethan Merritt

    Ethan Merritt - 2020-11-13

    If the level 4 section has the explanation part, it will be expanded the section title and the explanation on Windows help, texinfo file, and so on.

    The doc2gih processing ignores all numeric section headers. It creates text sections for each line beginning with '?'.

    The doc2tex processing used for pdf and texinfo output also does not expand section text because of a numeric heading. Moving, adding, or removing a numerical section header does not change the creation of a help text section for these output types. It does of course change where the section title is printed. An index entry is created for both numeric headings and for lines beginning with '?'. Text lines inside a table do not appear in the final document; for example there is no text section in the PDF output for keyword "exp".

    If the windows code uses the numerical section heading as a trigger to create a text output section that is a very different method.

    Perhaps all the section headers with following text should be moved outside of the table?

     

  • Shigeharu TAKENO

    Shigeharu TAKENO - 2020-11-13

    In my understanding, .texi (and then .info) document is made by doc2texi.el, not by doc2tex. My gnuplot-ja.texi made by doc2texi.el (of Japanese version) includes "exp" section:

    @node exp, floor, erfc, Functions
@subsubsection exp

@c ?expressions functions exp
@cindex exp
@findex exp

The `exp(x)` function returns `e` raised to the power of x, which
can be an integer, real, or complex value.

    By the way, we should consider which text is in the table, or out of the table. For example,

    @start table
4 [section title]    (1)
# [TeX table entry]  (2)
 [plain text]        (3)
@end table
4 [section title]    (4)
 [plain text]        (5)

    In texinfo file, or Windows help, the above help expand

    section title  (1)

  [plain text] (3)

section title (4)

  [plain text] (5)

    In LaTeX and pdf file,

    [TeX table entry] (2)

section title (4)

 [plain text] (5)

    (2) is short explanation of (1) as LaTeX form. (3) is alternative of (2) by plain text, and it should be short explanation. But (5) may be detailed document for (4).

     

  • Shigeharu TAKENO

    Shigeharu TAKENO - 2020-11-13

    In my understanding, .texi (and then .info) document is made by doc2texi.el, not by doc2tex. My gnuplot-ja.texi made by doc2texi.el (of Japanese version) includes "exp" section:

    @node exp, floor, erfc, Functions
@subsubsection exp

@c ?expressions functions exp
@cindex exp
@findex exp

The `exp(x)` function returns `e` raised to the power of x, which
can be an integer, real, or complex value.

    By the way, we should consider which text is in the table, or out of the table. For example,

    @start table
4 [section title]    (1)
# [TeX table entry]  (2)
 [plain text]        (3)
@end table
4 [section title]    (4)
 [plain text]        (5)

    In texinfo file, or Windows help, the above help expand

    section title  (1)

  [plain text] (3)

section title (4)

  [plain text] (5)

    In LaTeX and pdf file,

    [TeX table entry] (2)

section title (4)

 [plain text] (5)

    (2) is short explanation of (1) as LaTeX form. (3) is alternative of (2) by plain text, and it should be short explanation. But (5) may be detailed document for (4).

     

  • Ethan Merritt

    Ethan Merritt - 2020-11-13

    I am confused.

    The windows help system uses doc2texi.el? If I ever knew that I had forgotten. I thought we dropped support for texinfo output and therefore we no longer needed doc2texi.el.

    The help text I see fromversion 5.4 gnuplot.exe and wgnuplot.exe running under wine was apparently generated by docs/windows/doc2html.c.

    Please help me understand what is the difference between these two help systems. Which windows build uses doc2texi and which windows build uses doc2html?

     

  • Shigeharu TAKENO

    Shigeharu TAKENO - 2020-11-14

    I am sorry that my bad explanation confuses you.

    Of course, Windows help has no relation with doc2texi.el.

    Gnuplot can make many kind of document. I only take 2 format,
    Windows and TeXinfo format, for example other than the LaTeX
    format and PDF format.

    Windows help file wgnuplot.chm is made by docs/windows/doc2html.c.
    Texinfo file gnuplot.texi is made by docs/doc2texi.el.
    What I want to say is that the structure of sections for .chm
    is similar to the one for .texi, but is not similar to .tex
    and .pdf, because numerical section title and plain text part
    are used in the table for .chm and .texi files, though they
    are ignored and only # lines are used for .tex and .pdf files.

    The reason that I commented out some numerical section titles
    for new functions in the table is not to make the sections
    which have only section title and not have plain text contents
    in .chm or .texi files.

    To make correct help file of any format, 

    @start table
  ...
4 [section title]   (1)
# [TeX line]        (2)
 [alternative plain text to the TeX line]  (3)
...
@end table

    or 

    @start table
...
# [TeX line without section title]  (4)
...
@end table
4 [section title]  (5)
 [plain text for explanation]  (6)

    In .pdf file, (1) and (3) does not appear for the first style,
    but (5) and (6) appears for the second style.
    In Windows help and TeXinfo file, (1) and (3) are used for the
    first style, and (5) and (6) are used for the second style.
    So, the first style is not the same as the second style.

     

  • Shigeharu TAKENO

    Shigeharu TAKENO - 2020-11-19

    Ethan,

    I see your mail in gnuplot-beta mailing list at 2020-11-14:

    But I am also seeing reports or queries (E.g. Bug #2353) implying that
    the Windows build process needs a texinfo version produced by
    doc2texi.el
    Is that correct?

    Of cource it is not correct. Of cource, Texinfo file is no relation with Windows build. I am very sorry that my bad explanations make you confuse.

    Please ignore my any opinions.

     

  • Ethan Merritt

    Ethan Merritt - 2023-01-16
    • status: open --> closed-out-of-date
    • Group: -->
    • Priority: -->
     

Log in to post a comment.

MongoDB Logo MongoDB