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.

[mojavelinux]

I just don't see the justification for using a TOC in the manpage output (toc is definitely support for HTML and PDF output). I've never seen a man page with a toc.

[g-branden-robinson]

I've never seen a man page with a toc.

As I noted in my comment from March 24, there is top(1), from procps-ng.

https://gitlab.com/procps-ng/procps/-/blob/master/man/top.1?ref_type=heads#L99

However, that page is not an idiomatic man(7) document in my opinion as a groff developer (and contributor to its own man pages as well as those of ncurses, procps, bash, and others). That document would be better migrated to an ms document like the good old Volume 2 of the Seventh Edition Unix Programmer's Manual (1979) and replaced with something leaner in man.

But, not my project, not my decision.

[sdaoden]

I am sorry to see this consciously so late, dear 0-issue!
A decade ago i had created an extension to the mdoc macro series of (g)roff, mdocmx, which can be used to create fully interactive manuals, in that you have internal and external links, and alongside, a TOC: if you place a

.Mx -toc -tree html pdf ps xhtml

in your manual page, it will be generated (for the given document types).
Actually, users can set an environment variable with (roff-typical, sorry) flags, alongside are mx-toc-disable, mx-toc-emerged, mx-toc-force, mx-toc-numbered, and mx-toc-name (to replace TABLE OF CONTENTS).
Ie i use it myself to force a TOC, i find it convenient because of the links to which i can jump to easily.

Now it must be said, whereas less(1) started supporting the TTY-wise machinery in January this year, the groff maintainer which has spoken up here already did not only implement the OSC8 feature so that less(1) and i have to use non-OSC8-"standard" means to create anchor-only constructs, but he also rejected upstreaming mdocmx and in the meantime has meddled with the mdocmx macros in a way that i can no longer follow upstream due to time constraints.

My initial dream was that we go away from HTML etc documentation to simply UNIX manuals on the terminal, but with internal and external links, and an optional toc (which could have ended as "man -toc" or whatever, you know).

So being able to drive a TOC for a TTY manual display in a fixed way is possibly a bit odd, if it is optional i personally am all for it!!

(Sorry again, 0-issue. Thanks for speaking up with Mr. Nudelman!)

[g-branden-robinson]

I am sorry to see this consciously so late, dear 0-issue!

And I am sorry to see you repeating irrelevancies and falsehoods here just as you have in so many other forums.

A decade ago i had created an extension to the mdoc macro series of (g)roff, mdocmx, which can be used to create fully interactive manuals, in that you have internal and external links, and alongside, a TOC: if you place a

.Mx -toc -tree html pdf ps xhtml

I don't agree with this approach in the slightest. The point of the man and mdoc formats is to describe a document (one which in turn describes some aspect of a Unix system). There is no reason for such documents to carry internal information directing the presence or cosmetic arrangement of a navigation feature like a table of contents. What if a tree is not the arrangement preferred by the reader? What if a simple list is easier for, say, a screen reader used by the visually impaired? The man page author need neither know nor care about such things; all they need to do is structure their document.

A similar argument goes for this list of output formats, which is (a) groff-specific and (b) fails to mention several groff output devices, including but not limited to ascii, latin1, utf8, cp1047, dvi, lbp, and lj4. What should users of such devices get? Nothing? To summarize, this proposed feature is neither portable nor robust to future development of output drivers.

in your manual page, it will be generated (for the given document types). Actually, users can set an environment variable with (roff-typical, sorry) flags, alongside are mx-toc-disable, mx-toc-emerged, mx-toc-force, mx-toc-numbered, and mx-toc-name (to replace TABLE OF CONTENTS). Ie i use it myself to force a TOC, i find it convenient because of the links to which i can jump to easily.

The best avenue for manipulating of table of contents (TOC) generation or similar features is likely the specification of registers or strings on the roff command line, as is already the case with many cosmetic details.

Now it must be said, whereas less(1) started supporting the TTY-wise machinery in January this year, the groff maintainer which has spoken up here already did not only implement the OSC8 feature so that less(1) and i have to use non-OSC8-"standard"

There is no standard for OSC 8, just a convention, and there is no convention for anchor placement that anyone but you has proposed. If you disagree, please cite the discussions and tell me why the groff mailing list was never notified of them.

I foresee adding automatic placement of anchors linked to (1) section headings, (2) subsection headings, and (3) the "tags" of tagged paragraphs (TP macro calls). I have discussed these plans openly on the groff and linux-man mailing lists. See, for example, here (1)(2), here, and here.

means to create anchor-only constructs, but he also rejected upstreaming mdocmx

That's true. mandoc(1) maintainer Ingo Schwarze also objected to your design and implementation.

and in the meantime has meddled with the mdocmx macros in a way that i can no longer follow upstream due to time constraints.

This is not only false but nonsense. There are no mdocmx macros in groff, so I can neither meddle with them nor leave them alone. They do not exist. If you are attempting to claim some sort of ownership over man or mdoc package internal interfaces to suit your own aims, that claim is unwarranted and untenable.

My initial dream was that we go away from HTML etc documentation to simply UNIX manuals on the terminal,

Good luck with your Steve Jobs-scale ambition to steer the public. My own objective is more modest: to get as much out of the man page browsing experience on the terminal as we can, so that people seldom feel a need to fire up a web browser (or PDF viewer) to peruse a man or mdoc document. Such output formats will still be necessary for some purposes, and I'd like groff to produce high-quality renderings in them. (I think we're much closer to that goal with PDF than with HTML.)

but with internal and external links, and an optional toc (which could have ended as "man -toc" or whatever, you know).

It's fine to have a TOC. Plenty of Web conversions of man pages infer a tree structure from a document and construct a TOC therefrom. My impression is that these converters are often ad hoc and frequently fail to produce such content in an idiomatic HTML5- or WAI-ARIA-conforming manner. I certainly don't mind making that job easier. What I object to is requiring man or mdoc authors to specify anything in particular about such a tree or TOC. They already specify a document title, section headings, and sometimes subsection headings and paragraph tags. These are already hierarchically arranged in a tree structure. That is enough. No more need be said.

In particular, anything like...

.Mx -toc -tree html pdf ps xhtml

...is wholly superfluous.

So being able to drive a TOC for a TTY manual display

It's pretty sloppy of you to continue to refer to terminal emulators as "TTY"s when Teletype machines, being paper-based devices, were inherently incapable of hyperlinking. OSC 8 is wholly alien to that technology. Its very syntactical structure is foreign to such devices.

This sort of confusion between paper teletypewriters and cursor-addressable video terminals has been responsible for much misunderstanding and poor decision-making in the use and development of Unix software, particularly pagers like less(1).

Please cease your guerilla campaign of confusing issues and mystifying developers.

Regards,
Branden

[mojavelinux]

While I don't disagree with the rebuttal, I'm going to stop this conversation here because it has drifted into a broader debate about how man pages should be authored. You're welcome to continue this debate somewhere else.

As far as this issue is concerned, if you need a TOC included in the manpage output (whether it's done manually or using a custom macro), you can do so by extending the manpage converter. You can learn how to extend the converter on the following page in the docs: https://docs.asciidoctor.org/asciidoctor/latest/convert/custom/#extend-and-replace-a-registered-converter