Re: OVERVIEW_LINK_TO_TOC and other variables

[Patrice Dumas]

On Thu, Dec 23, 2021 at 04:55:36PM +0000, Gavin Smith wrote:
> On Tue, Dec 21, 2021 at 09:28:45PM +0000, Gavin Smith wrote:
> 
> > > > You could add @shortcontents at the start of the document to get a list
> > > > of chapters.  Do you think that would solve the problem?
> > > 
> > > It would.  However, the links don't work: clicking them does not lead 
> > > anywhere.
> > > 
> > > :|
> > 
> > Haven't looked into this yet.
> 
> So it looks like the default behaviour for the Short Table of Contents
> is to link to the corresponding part of the Table of Contents, even if
> there is none.  That's why the links didn't work.
> 
> This is customized with the OVERVIEW_LINK_TO_TOC variable.  It's not easy
> to find this out because the manual calls it the "Overview" and not the
> "Short Table of Contents":
> 
> 'OVERVIEW_LINK_TO_TOC'
>      If set, the cross-references in the Overview link to the
>      corresponding Table of Contents entries; default true.
> 
> My suggestion is to remove this variable and make the links in the
> @shortcontents link to the chapters themselves by default.  Any comments?

This has been set as the default while it was not the default in
texi2html, so it was set like that on purpose and I would guess that it
is expected by at least some users.  What I would propose, instead is
* to rename OVERVIEW_LINK_TO_TOC as SHORT_TOC_LINK_TO_TOC
* if there is no table of contents output, link to the chapters even
  if SHORT_TOC_LINK_TO_TOC is set

> I also propose removing BEFORE_OVERVIEW, AFTER_OVERVIEW, BEFORE_TOC_LINES
> and AFTER_TOC_LINES as they don't seem to be very useful.  These can easily
> produce invalidly nested HTML if not used correctly.

The documentation is clear on that subject.  I would propose renaming
BEFORE_OVERVIEW as BEFORE_SHORT_TOC and AFTER_OVERVIEW as AFTER_SHORT_TOC
but leave them in.

> I looked through mailing list archives and ChangeLog but couldn't find
> any mention of these variables.

That's because they come from texi2html, and, if I recall well, from the
Singular manual, so I would leave them, in case they are used in some
manual.

-- 
Pat