Emit toc for manpage

[0-issue]

It would be nice to have a :toc: emitted for manpages. Manpage viewers are starting to consider exploiting OSC-8 sequences to make man pages browsable, and table of contents will become even more relevant (to jump links within same page). If you would want, I can file another issue for supporting OSC-8 sequences (groff already supports them) for all hyperlinks.

[mojavelinux]

Can you point me to an existing man page that has a TOC? This seems like a very personal request and not one that's likely to be used or expected by most users. Plus, if we start adding a TOC now, it could be extremely disruptive to existing users who are not expecting the man page to have a TOC. This feels like something that should be handled by an extended converter.

[0-issue]

The reason why there aren't any manpages with toc's is because pagers haven't yet caught up to OSC-8 based hyperlinks (OSC-8 is pretty new). Here's an ongoing PR in less (the default man pager) that is considering support for OSC-8: gwsw/less#251. Anyhow, I thought for asciidoctor it should be quite easy to enable emitting toc and hyperlinks for manpages.

[mojavelinux]

It's not really about how easy it is, but how disruptive it would be. It has the potential to break a lot of existing builds since there was never any expectation before that a TOC would be generated in manpage output (and, like I said, it's very atypical for man pages to have one).

We could possibly consider having a dedicated attribute that controls whether the TOC is generated when producing a man page (mantoc?) or perhaps even a dedicated value for the toc attribute like man, though that seems odd.

[g-branden-robinson]

Can you point me to an existing man page that has a TOC?

groff -mandoc -Thtml has been producing them (for man(7)-format pages only) for about 25 years.

groff -mandoc -Tpdf has been producing them (for man(7)- and mdoc(7)-format pages) since groff 1.23.0, released last July. See, for example, the collected groff man pages document produced by the official build.

It's true that man pages generally don't construct their own TOCs by hand. There are exceptions like top(1). It's a good thing they don't, as the formatter could do so itself depending on the output device. And that is in fact how the PDF bookmarking and HTML navigation bar works (albeit with the latter presented in an ancient, dot-com-era style rather than HTML5).

So I don't know that there is much for asciidoctor to do here.