[l2h] Interaction between 'show_section_numbers' and 'short_index'

[Volker Simonis]

On Wednesday 26 June 2002 12:45, you wrote:
>
> > Hello alltogether,
> >
> > I found the following interaction between the two options
> > 'show_section_numbers' and 'short_index': if I use -show_section_numbers
> > the created index will contain only the section numbers, no difference if
> > the option -short_index was used or not. This is because of the following
> > code in 'makeidx.perl':
>
> Not all hyperlinked documents need have numbered sections.
> Hyperlinking can replace the need for numbering entirely.
> LaTeX2HTML tries to cater for both numbering and `without numbering'.
>
>
> When numbering *is* being used, then it makes sense
>
> to use it for the index links, as in:
> >     if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; }
>
> When numbering is *not* being used, then there is a possible
> problem in that the text automatically generated for hyperlink anchors
>
> can become quite long; hence the option:
> >     elsif ($SHORT_INDEX) { $words = &make_shortidxname; }
> >
> >     else { $words = &make_idxname; }
>
> There was never an intention for -short_index  to be used
> *as well as*   -show_section_numbers .
> It simply should not be needed.
>

Ok, perhaps I should explain what I am really doing. I'm writing some scripts 
which take the L2H output and generate the XML-files needed for the JavaHelp 
system (JavaHelp is a HTML-based Help system for Java-Programs, which needs 
some additional XML configuration files for generating a Table Of Contents 
View, an Index View and so on (see http://java.sun.com/products/javahelp/))

So for me it's reasonable to use -show_section_numbers AND -no_short_index, 
because i don't use the index page produced by L2H, except for producing the 
desired XML control files.

But even without this special use-case in mind I think the two features 
should be separated, or at least the dependency should be stated in the 
documentation.

> > I think this interaction is confusing, especially because it is not
> > documetned, neither at the description of 'show_section_numbers' nor at
> > the description of 'short_index'.
> >
> > I think the best thing would be to simply skip the first line, because
> > it's would be the only way to use 'show_section_numbers' and produce a
> > long index.
>
> Skipping the first line does not make sense to me.
> If you have numbering, then surely you expect to use it for indexing.
>

Yes, but it's impossible in this case to use -no_short_index in order to 
produce a long index.

> > Another point is that the function make_shortidxname uses a logical
> > numbering of chapters, parts and so on. So if I have for example a Table
> > Of Contentents
>
> Yes; it needs some means to make sensible short anchors, when nothing
> else is available. The internal numbering is what is chosen here.
>
> > before the first chapter, make_shortidxname will return '2' for an index
> > into the first chapter, whereas make_idxnum correctly returns '1'. This
> > is especially confusing when using -short_index together with
> > -show_section_numbers (which admittedly wasn't possible until now).
>
> But this should not happen.
>

> Are you using section-titles that include numbering within their names,
> such as  \section{Section 1} ?
>
> If your document has numbered sections, then you should be using LaTeX to
> automatically generate the numbers, and adjusting LaTeX macros to specify
> how to put these onto the page.
> In this case you can use  -show_section_numbers  with LaTeX2HTML,
> and get short index links automatically.
>

But it happens. Perhaps an excerpt from 'section.pl' will clarify my problem:

$key = q/0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0/;
$section_info{$key} = '0%:%'."$dir".q|tutorial.html%:%Titel%:%| unless 
($section_info{$key});
$noresave{$key} = "$nosave";
$done{"${dir}tutorial.html"} = 1;
 
$key = q/0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0/;
$section_info{$key} = '2%:%'."$dir".q|node1.html%:%Inhalt%:%| unless 
($section_info{$key});
$noresave{$key} = "$nosave";
$done{"${dir}node1.html"} = 1;
 
$key = q/0 0 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0/;
$section_info{$key} = '2%:%'."$dir".q|node2.html%:%<SPAN 
CLASS="arabic">1</SPAN>. Einleitung%:%| unless ($section_info{$key});
$noresave{$key} = "$nosave";
$done{"${dir}node2.html"} = 1;

As you can see, my first chapter "1. Einleitung" is correct numbered by LaTeX 
and L2H. But it is in the file 'node2.html', because my LaTeX file contains 
the TOC "Inhalt" before the first chapter, which has no LaTeX section number.

Now the subroutines 'make_idxname' and 'make_idxnum' correctly return "1. 
Einleitung" and "1." respectively as index for the first section, but 
'make_shortidxname' returns "2", because it uses that 'logical' structuring 
explained in the manual: "..For example, `2.1' means sub-node #1 of node #2, 
viewing the entire document as a tree-like structure..". This is correct for 
the nodes, but not for the section numbers.


> Hope this helps,
>
> 	Ross Moore
>

Anyway, thanks a lot for youre response. 

I also wanted to ask you what do you think about incorporating my scripts 
which generate the JavaHelp XML configuration files into L2H. Currently they 
are written in AWK, but if you see a chance to take this extensions into the 
main distribution, I could eventually reprogram them in Perl. I think the 
extensions are non-intrusive and would just add some more switches to L2H 
which in turn would lead to the generation of some xml-files. If yo're 
interested in the topic I can supply you with some more information about 
JavaHelp and how to create JavaHelp systems from LaTeX files with the help of 
L2H.

Volker