Re: HTML output: section headers with diacritics not in table of contents

[Ingo Schwarze <schwarze@usta.de>]

Hi Mario,

Jan Stary wrote on Fri, Mar 25, 2022 at 10:20:30PM +0100:
> On Mar 25 21:59:26, mario.blaettermann@gmail.com wrote:
>> Am Fr., 25. März 2022 um 21:36 Uhr schrieb Jan Stary <hans@stare.cz>:
>>> On Mar 25 17:57:21, mario.blaettermann@gmail.com wrote:

>>>>> Regarding -O toc, you should be aware that a number of senior OpenBSD
>>>>> developers hated the feature so much that i disabled it completely
>>>>> on man.openbsd.org.  They argue the feature is superfluous, noisy,
>>>>> and the whole idea of prefixing a TOC to a manual page is misguided.

>>>> To mention, the TOC works at man.openbsd.org, for example:
>>>> http://man.openbsd.org/mandoc#Syntax_tree_output

>>> I don't see a TOC on that page.

>> What you've expected is probably a TOC like [1].

> Yes, because that's what mandoc calls a TOC:
> 
>   toc If an input file contains at least two non-standard sections,
>       print a table of contents near the beginning of the output.

Exactly.

To see what a "TABLE OF CONTENTS" (TOC) is, please look at

  https://man.bsd.lv/pf.conf.5

where i just enabled TOCs for demonstrational purposes and compare
that page to

  https://man.openbsd.org/pf.conf.5

where TOCs are disabled.

The mandoc(1) page never gets a TOC because it does not contain two
custom sections (in fact, not even one).

>> But the TOC generated
>> by Mandoc doesn't mean a real table of contents in this case, it's
>> merely a »hidden« TOC, which enables to click on section headers and
>> options to generate hyperlinks for that position. If you can open the
>> link mentioned above, and »Syntax tree output« is on top of the page
>> displayed in the browser, then this kind of TOC works.
>> [1] https://archlinux.org/pacman/makepkg.8.html

> I think these are 'tags' in the mandoc parlance.
> http://man.openbsd.org/mandoc#tag

Exactly, and that mandoc(1) terminology is motivated by this
pre-existing terminology:

  https://man.openbsd.org/less.1#T
  https://man.openbsd.org/ctags.1

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv