New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Emit toc for manpage #4533
Comments
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. |
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 |
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 ( |
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 |
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. |
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. |
I am sorry to see this consciously so late, dear 0-issue!
in your manual page, it will be generated (for the given document types). 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!) |
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.The text was updated successfully, but these errors were encountered: