gnuplot-beta

Help wanted: Minor *.doc -> *.tex problem

[Ethan M. <merritt@u.washington.edu>]

The current documentation contains section headings nested
as deep as level 6.  For example:

6 edf  
?binary general filetype edf
?filetype edf
?edf
 `edf` is one of the automatically recognized binary file types for images.

This is no problem for the interactive help system (doc2gih.c)
But the conversion to *.tex (doc2tex.c) handles only levels 1-5.

Can some TeX-savvy person contribute a patch deal with a 6th level
of indexing and section numbering? 

-- 
Ethan A Merritt       merritt@u.washington.edu
Biomolecular Structure Center
Mailstop 357742
University of Washington, Seattle, WA 98195

Re: Help wanted: Minor *.doc -> *.tex problem

[Hans-Bernhard B. <br...@ph...>]

Ethan Merritt wrote:
> The current documentation contains section headings nested
> as deep as level 6.  

... and they're all in "binary datafiles" section.  Which, IMHO,
suggests an obvious alternative to patching up doc2tex.c: changing the 
structure of that part of the docs to make it less deeply nested.

 >
> But the conversion to *.tex (doc2tex.c) handles only levels 1-5.

I don't know where you found this limitation --- it actually supports 
1..6 as it is (6 turns into \paragraph()).  See section() in doc2tex.c,
line 327.

While at it, there is one thing that might be worth considering, though:
gnuplot.tex currently is an "article" --- at 181 pages, I would think 
that it's time to acknowledge reality and finally escalate that to 
"report" (which means it can have chapters, not just parts and 
sections).  If we fiddle with the defaults a bit (such that chapter 
starts don't force themselves onto a new right page), that should be 
manageable.

Re: Help wanted: Minor *.doc -> *.tex problem

[Juergen W. <wie...@fr...>]

On Friday 01 April 2005 23:10, Hans-Bernhard Broeker wrote:
> > But the conversion to *.tex (doc2tex.c) handles only levels 1-5.
>
> I don't know where you found this limitation --- it actually supports
> 1..6 as it is (6 turns into \paragraph()).  See section() in doc2tex.c,
> line 327.

The problem is that \subsubsubsection is an alias to \paragraph (see
toc_entry.sty).  Both level 5 and 6 were \paragraph{}s this way.


Juergen

Re: Help wanted: Minor *.doc -> *.tex problem

[Juergen W. <wie...@fr...>]

On Friday 01 April 2005 21:22, Ethan Merritt wrote:
> Can some TeX-savvy person contribute a patch deal with a 6th level
> of indexing and section numbering?

Attached.

> 6 edf
> ?binary general filetype edf
> ?filetype edf
> ?edf
>  `edf` is one of the automatically recognized binary file types for images.

I think it's quite distracting that both section headings and
backquoted text get boldfaced.  Wouldn't it be nicer to have the
latter italic?  This could be done by substituting "{\\bf " with
"{\\em " in line 406.


Juergen

Re: Help wanted: Minor *.doc -> *.tex problem

[Ethan M. <merritt@u.washington.edu>]

On Friday 01 April 2005 01:19 pm, Juergen Wieferink wrote:
> 
> Attached.

Thanks.  Added to cvs.

> I think it's quite distracting that both section headings and
> backquoted text get boldfaced.  Wouldn't it be nicer to have the
> latter italic?  This could be done by substituting "{\\bf " with
> "{\\em " in line 406.

I agree.  Anyone else have opinions on this?


-- 
Ethan A Merritt       merritt@u.washington.edu
Biomolecular Structure Center
Mailstop 357742
University of Washington, Seattle, WA 98195

Re: Help wanted: Minor *.doc -> *.tex problem

[Hans-Bernhard B. <br...@ph...>]

Ethan Merritt wrote:
> On Friday 01 April 2005 01:19 pm, Juergen Wieferink wrote:

>>I think it's quite distracting that both section headings and
>>backquoted text get boldfaced.  Wouldn't it be nicer to have the
>>latter italic?  This could be done by substituting "{\\bf " with
>>"{\\em " in line 406.

> I agree.  Anyone else have opinions on this?

Fine with me.

And while we're at it, I've found yet another quirk that may need
addressing: gnuplot has some subsection count run up into three-digit 
numbers.  LaTeX doesn't anticipate that, and the resulting formatting
is quite spectacularly bad (see the lower half of page 9 of gnuplot.ps, 
i.e. the last couple subsections below section 'Set-show').

That said, I still think we should

1) switch from article to report
2) change doc2texi to turn what are now \section's into \chapter's
    (and so on down the hierarchy)

And hierarchy levels beyond 6 probably shouldn't generate any TOC 
entries (\paragraph*, or maybe just fall through to the default: case, 
i.e. do nothing in particular).

Re: Help wanted: Minor *.doc -> *.tex problem

[Ethan M. <merritt@u.washington.edu>]

On Friday 01 April 2005 01:10 pm, Hans-Bernhard Broeker wrote:
> Ethan Merritt wrote:
> > The current documentation contains section headings nested
> > as deep as level 6.
>
> ... and they're all in "binary datafiles" section.  Which, IMHO,
> suggests an obvious alternative to patching up doc2tex.c: changing the
> structure of that part of the docs to make it less deeply nested.

I found the problem because I was trying to add a new section
elsewhere. Adding additional levels is the only way I know of to
break the interactive help into shorter sections and have it
prompt for additional keywords.  So it's useful in the *.gih form.
In the printed docs it is maybe not so useful.  Levels beyond
4 or 5 may not need a separate TOC number of their own.
But it would be nice to have an index at the back that catches
them. Is that possible?

> > But the conversion to *.tex (doc2tex.c) handles only levels 1-5.
>
> I don't know where you found this limitation --- it actually supports
> 1..6 as it is (6 turns into \paragraph()).  See section() in doc2tex.c,
> line 327.

It did not work in practice.  Juergen's simple change fixed it.

-- 
Ethan A Merritt
Biomolecular Structure Center
University of Washington 98195-7742

Re: Help wanted: Minor *.doc -> *.tex problem

[Hans-Bernhard B. <br...@ph...>]

Ethan Merritt wrote:

[Ethan, a side note: you occasionally send mail encoded as Japanese
(Shift-JIS) for no readily apparent reason.  It's not a major hassle,
but you may want to check what's going on there...]

> I found the problem because I was trying to add a new section
> elsewhere. Adding additional levels is the only way I know of to
> break the interactive help into shorter sections and have it
> prompt for additional keywords.  So it's useful in the *.gih form.

Let's say: it can be, if not abused.  A node with only one subnode
doesn't make terribly much sense, IMHO.

I don't think keeping individual nodes short would be sufficient reason
to split them up.  It's more important to keep up the principle of
one subject matter <--> one node.

> In the printed docs it is maybe not so useful.  Levels beyond
> 4 or 5 may not need a separate TOC number of their own.

Levels beyond 6 already don't --- they'll just end up starting
plain paragraphs.

> But it would be nice to have an index at the back that catches
> them. Is that possible?

Possible: yes.  But it could turn into a major hassle to make it happen.
Currently, our LaTeX document has no index at all.  Adding the necessary
apparatus to generate one could prove quite tricky.

Re: Help wanted: Minor *.doc -> *.tex problem

[Ethan M. <merritt@u.washington.edu>]

On Sunday 03 April 2005 08:22 am, you wrote:
> but you may want to check what's going on there...]
>
> > I found the problem because I was trying to add a new section
> > elsewhere. Adding additional levels is the only way I know of to
> > break the interactive help into shorter sections and have it
> > prompt for additional keywords. =C2=A0So it's useful in the *.gih form.
>
> Let's say: it can be, if not abused. =C2=A0A node with only one subnode
> doesn't make terribly much sense, IMHO.
>
> I don't think keeping individual nodes short would be sufficient reason
> to split them up. =C2=A0It's more important to keep up the principle of
> one subject matter <--> one node.

The issue is how to allow access to the same help section via
multiple keywords for the 'help' command.

=46or example: There is a longish section on the 'with histogram'
style. It is located with the other plot style entries as:
  5 histograms
  ?commands set style histogram

So it is already 5 levels deep.  At the end of this section is an
explanation of the 'newhistogram' command.  Unfortunately, you cannot
find it by typing 'help newhistogram'.  It was not clear to me that
I could simply add a line
  ?newhistogram
without first creating a new section heading
  6 newhistogram

Upon experimentation, I see that in fact it is possible to add
the '?<foo>' form without a corresponding '6 <foo>' form.
This allows 'help newhistogram' to work, and does not add a
separate 6th level entry to the ToC.  However, it also causes
'help set style histogram' to terminate without printing this
last section.  So there's still a problem.

It wouldn't make any sense to bump 'newhistogram' up to a
parallel 5th level entry, because it isn't a plotting style on
its own.

Suggestions?


=2D-=20
Ethan A Merritt
Biomolecular Structure Center
University of Washington 98195-7742