@b0rk You discussed the GNU coreutils man pages and the relation to info pages. It's probably worth noting that in the latest coreutils release we link directly into the appropriate section of the full online documentation from each highlighted option in the man pages. More details at https://www.pixelbeat.org/docs/tty_links/
@b0rk Ingo schwarze@openbsd (current mandoc maintainer) has a lot of knowledge on this and loves to share it. You might consider reaching out.
mtrnord
@b0rk first time in my life of using Linux for easily 15 years now that I have heard about the info command... Not a single doc so far did mention it oO
@mtrnord yeah I think that’s very common! I’ve talked to many long time Linux users who have never heard of info and I think I just learned about it in the last few years too
Kazinator
@b0rk I think that the rsync synopsis shows something that the program itself should output with --help. Therefore, the value of repeating the same thing in the man page is not necessarily that great.
zekjur
@b0rk I think the Zsh man pages are well split, in the sense that “zshall” gives you all the sections, but if you know roughly which section you’re looking for, you can get to the more targeted (more manageable) part of the manual. Also, I can find the parts of the shell I’m looking for in these docs.
@b0rk nice timing - i just drafted my first man page for a little game i'm writing not two weeks ago. you've given me some good ideas. also, i occasionally use standalone info, lol 🫣
@b0rk usually really big info pages, like gcc or bash. i like info's page navigation features. the reason i use the standalone is just because i haven't gotten around to trying emacs yet (i've only been on linux since 2001, lol)
@b0rk I documented the entire TXR Language, including its sprawling Lisp dialect, as one man page.
It renders out to almost 1000 pages of PDF in letter size, using the default font sizes and margins.
I have a byzantine infrastructure for converting it to HTML, involving a version of man2html (the one written in C, from man-1.6g) to which I applied about 30 patches of my own. The otuput of that is post processed to do hyperlinks and TOC and whatnot:
The man page source starts with quite a few custom nroff macros, including its own support for auto-numbering its sections in the usual multi-level hierarchy.
I have a custom linting tool which inspects the man page for violations in the use of my custom macros; when I type "make txr-manpage.{html,pdf}" all that checking is run.
@b0rk Another good example is the main curl man page.
rodneylives.bsky.social
I find myself using tldr more than man pages. Man pages are absurdly complete and list every detail of operation, but that makes them wordy, spilling forth for dozens of screen-sized pages, and it becomes an effort just to sift through them. tldr just presents a basic description and typical uses.
Anarcat
@b0rk i'm going to be the one to do the bold move and openly question's GNU's approach on manual pages. the tail example is telling: the info version does *not* feature anything significant that should *not* be in a manual page. i understand for much more complex programs like Emacs, sure: you can't fit the Emacs manual inside manpages. fine. but for tail? that's religious dogmatism, those info pages belong in manual pages.
makes me wonder whether there's sort of a "middle ground" approach which adds some very basic examples to the man pages (which I think would add a lot of value and would be very easy to maintain) while leaving all of the gnarly details in the info documentation
@b0rk the "sync" issue is a self-inflected wound in the case of coreutils: i don't buy this being useful as its own manual, it's just a series of manpages!
@b0rk i've always found that section of the coreutils manual to be particularly unhelpful because it's exactly what belongs in each individual manpage. sure, some of it can be copied over, but those could live in a common, separate manual page that's cross-referenced
which I know other projects have solved but it's true that coming up with a good toolchain (asciidoc, RST, etc) for formatting man pages and converting the project to it isn't a trivial task
@b0rk rst is its own special beast, i find it hard to use compared to markdown, although it *is* more formally specified and better at building books...
knapjack
Are man pages the original mansplainers? 🤔
b0rk
my main thought as after reading some of the comments on this is that even though this post is mostly about formatting, (as usual) getting feedback from real users on documentation and making sure it addresses people’s problems is really important
@b0rk I understood what you really wanted after rereading your post few hours after my reply. 😬 🤭
I don't have any tool to improve man navigation. And I thought that it would be awesome to have one. I didn't dig it as I don't use it ~much~ enough. ^^
I have a tool for reading man pages using Vim, such that all the bold and italic stuff overstrike colorized, yet in a way that you can still search for identifiers in it.
Also, when I read the same man page multiple times, it remembers the last position I was reading and jumps there.
@b0rk I used a lot info command (and still sometimes when I’m offline, like troublesome new install. I do not think format is limiting ( and iirc there are links), just the formats are nearly impossible (and having two variants is not the best way) so also tools support. but all that is old remembered though (it was a can of worms, and I ran away with nightmares)
malin
@b0rk Can you do gpg next? Someone needs to do something about that thing.
It's a serious security flaw; some sysadmins can't handle basic operations because the programme and docs are an unsightly mess.
@b0rk I've been really happy reading man pages on https://www.mankier.com/. It's nicely formatted, hyperlinked, has a table of contents, tl;dr integration, and even allows you to add it as a search engine.
> If you have a complex command and aren't sure what it does, ManKier can help explain the programs and options. Just paste the command on /explain, e.g.: du -s * | sort -n | tail.
Woah 😮 You can even add a description to an /explain page and share it. Very cool site!
@castanearie@b0rk This made me realize what's missing from so many man pages: the TL;DR most often used commands.
elliotguest
@b0rk another interesting thing related to this is https://cheat.sh which is similar to tldr but just functions through curl or wget to the url
lovely blog post by the way
bnut
@b0rk it’d be interesting to talk about what’s displayed in --help on a command vs how man pages are used. I almost always use the former over the latter, and often forget about man
@b0rk You discussed the GNU coreutils man pages and the relation to info pages. It's probably worth noting that in the latest coreutils release we link directly into the appropriate section of the full online documentation from each highlighted option in the man pages. More details at https://www.pixelbeat.org/docs/tty_links/
@pixelbeat thanks, that way of using links is very interesting!
@b0rk
I find colorized man pages nicer to read. There's "batman", which uses "bat" to colorize them:
https://github.com/eth-p/bat-extras/blob/master/doc/batman.md
@b0rk Inspired in your article I've created this tool using Kilo Code https://github.com/oscaretu/man_pages_viewer
@oscaretu awesome, i’m excited to try it!
@b0rk Ingo schwarze@openbsd (current mandoc maintainer) has a lot of knowledge on this and loves to share it. You might consider reaching out.
@b0rk first time in my life of using Linux for easily 15 years now that I have heard about the info command... Not a single doc so far did mention it oO
@mtrnord yeah I think that’s very common! I’ve talked to many long time Linux users who have never heard of info and I think I just learned about it in the last few years too
@b0rk I think that the rsync synopsis shows something that the program itself should output with --help. Therefore, the value of repeating the same thing in the man page is not necessarily that great.
@b0rk I think the Zsh man pages are well split, in the sense that “zshall” gives you all the sections, but if you know roughly which section you’re looking for, you can get to the more targeted (more manageable) part of the manual. Also, I can find the parts of the shell I’m looking for in these docs.
Perl is similar with its many pages, see https://manpages.debian.org/trixie/perl-doc/index.html for a listing :)
@zekjur @b0rk I too love man pages of zsh!
@b0rk I just want to thank you for your constant drive to improve things. It’s inspiring
@b0rk for more friendly `man` in terminal i use such function:
# colored man
function man() {
env \
LESS_TERMCAP_mb=$(tput setaf 14) \
LESS_TERMCAP_md=$(tput setaf 11) \
LESS_TERMCAP_me=$'\E[0m' \
LESS_TERMCAP_se=$'\E[0m' \
LESS_TERMCAP_so=$(tput setaf 83) \
LESS_TERMCAP_ue=$'\E[0m' \
LESS_TERMCAP_us=$(tput setaf 14) \
man "$@"
}
@b0rk nice timing - i just drafted my first man page for a little game i'm writing not two weeks ago. you've given me some good ideas. also, i occasionally use standalone info, lol 🫣
@rsarson that's cool, what do you usually use info for?
@b0rk usually really big info pages, like gcc or bash. i like info's page navigation features. the reason i use the standalone is just because i haven't gotten around to trying emacs yet (i've only been on linux since 2001, lol)
@rsarson makes sense, thanks!
@b0rk
I documented the entire TXR Language, including its sprawling Lisp dialect, as one man page.
It renders out to almost 1000 pages of PDF in letter size, using the default font sizes and margins.
I have a byzantine infrastructure for converting it to HTML, involving a version of man2html (the one written in C, from man-1.6g) to which I applied about 30 patches of my own. The otuput of that is post processed to do hyperlinks and TOC and whatnot:
https://www.nongnu.org/txr/txr-manpage.html
The man page source starts with quite a few custom nroff macros, including its own support for auto-numbering its sections in the usual multi-level hierarchy.
I have a custom linting tool which inspects the man page for violations in the use of my custom macros; when I type "make txr-manpage.{html,pdf}" all that checking is run.
@b0rk
Stuff I fixed/improved/adjusted in the man2html utility in "man 1.6g":
https://www.kylheku.com/cgit/man/log/
@b0rk Another good example is the main curl man page.
I find myself using tldr more than man pages. Man pages are absurdly complete and list every detail of operation, but that makes them wordy, spilling forth for dozens of screen-sized pages, and it becomes an effort just to sift through them. tldr just presents a basic description and typical uses.
@b0rk i'm going to be the one to do the bold move and openly question's GNU's approach on manual pages. the tail example is telling: the info version does *not* feature anything significant that should *not* be in a manual page. i understand for much more complex programs like Emacs, sure: you can't fit the Emacs manual inside manpages. fine. but for tail? that's religious dogmatism, those info pages belong in manual pages.
@Anarcat this discussion makes me think that another issue is just it's hard to keep 2 different information sources in sync (which is also true!) https://lists.gnu.org/archive/html/coreutils/2017-03/msg00042.html
makes me wonder whether there's sort of a "middle ground" approach which adds some very basic examples to the man pages (which I think would add a lot of value and would be very easy to maintain) while leaving all of the gnarly details in the info documentation
@b0rk the "sync" issue is a self-inflected wound in the case of coreutils: i don't buy this being useful as its own manual, it's just a series of manpages!
@Anarcat personally i think i would struggle to integrate this "common options" section into the a man page format in a good way but i could be wrong https://www.gnu.org/software/coreutils/manual/coreutils.html#toc-Common-options
@b0rk i've always found that section of the coreutils manual to be particularly unhelpful because it's exactly what belongs in each individual manpage. sure, some of it can be copied over, but those could live in a common, separate manual page that's cross-referenced
@b0rk i mean just look at Exit status: https://www.gnu.org/software/coreutils/manual/coreutils.html#Exit-status that just says "yep, 0/1 is usual, then here are the exceptions" but utterly fails to explain *how* they behave! that's bonkers!
@Anarcat i just searched the coreutils mailing list for discussion of this and it seems like one hangup is the issue of authoring man pages https://lists.gnu.org/archive/html/coreutils/2025-09/msg00167.html
which I know other projects have solved but it's true that coming up with a good toolchain (asciidoc, RST, etc) for formatting man pages and converting the project to it isn't a trivial task
@b0rk roff and friends is total legacy, IMHO, not sure what the way out is... native markdown manuals?
@Anarcat I just worked on the dig man page recently which uses RST and it was straightforward, definitely much easier than roff. https://gitlab.isc.org/isc-projects/bind9/-/blob/main/bin/dig/dig.rst
I think they use Sphinx but not sure.
@b0rk rst is its own special beast, i find it hard to use compared to markdown, although it *is* more formally specified and better at building books...
Are man pages the original mansplainers? 🤔
my main thought as after reading some of the comments on this is that even though this post is mostly about formatting, (as usual) getting feedback from real users on documentation and making sure it addresses people’s problems is really important
@b0rk I understood what you really wanted after rereading your post few hours after my reply. 😬 🤭
I don't have any tool to improve man navigation. And I thought that it would be awesome to have one. I didn't dig it as I don't use it ~much~ enough. ^^
@flohw @b0rk
I have a tool for reading man pages using Vim, such that all the bold and italic stuff overstrike colorized, yet in a way that you can still search for identifiers in it.
Also, when I read the same man page multiple times, it remembers the last position I was reading and jumps there.
https://www.kylheku.com/cgit/mnpgr/about/
@b0rk The responses that rang truest to me were the one asking for more examples, particularly in the introduction.
@b0rk I used a lot info command (and still sometimes when I’m offline, like troublesome new install. I do not think format is limiting ( and iirc there are links), just the formats are nearly impossible (and having two variants is not the best way) so also tools support. but all that is old remembered though (it was a can of worms, and I ran away with nightmares)
@b0rk
Can you do gpg next? Someone needs to do something about that thing.
It's a serious security flaw; some sysadmins can't handle basic operations because the programme and docs are an unsightly mess.
@malin talked about that here recently https://social.jvns.ca/@b0rk/116035837768080814
@b0rk I've been really happy reading man pages on https://www.mankier.com/. It's nicely formatted, hyperlinked, has a table of contents, tl;dr integration, and even allows you to add it as a search engine.
@castanearie @b0rk
> If you have a complex command and aren't sure what it does, ManKier can help explain the programs and options. Just paste the command on /explain, e.g.: du -s * | sort -n | tail.
Woah 😮 You can even add a description to an /explain page and share it. Very cool site!
@castanearie thanks, this looks nice!
@castanearie @b0rk This made me realize what's missing from so many man pages: the TL;DR most often used commands.
@b0rk another interesting thing related to this is https://cheat.sh which is similar to tldr but just functions through curl or wget to the url
lovely blog post by the way
@b0rk it’d be interesting to talk about what’s displayed in --help on a command vs how man pages are used. I almost always use the former over the latter, and often forget about man