Whenever the discussion comes up about man pages and how documentation should be organized, I like to quote this section from the GNU coding standards about how Info documentation is structured:
----
Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.
Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.
[…]
In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. […]
That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.
This advice makes most sense for tools that have a clear linear flow from beginner to expert. As soon as something is complex enough to have multiple different personas or desired outcomes for the novice user it's considerably harder to structure docs pedagogically.
The extreme case of this is something like Nix, which is notorious for terrible docs, and I think that's in large part because even the basic "install my first package" could involve profiles, environments, flakes, whatever; there's like five ways to do everything and which one you want depends a lot what your "real" eventual goal is.
> Programmers tend to carry over the structure of the program as the structure for its documentation[…] the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it.
That's also the right way to structure the program. Deficient compilers and bad advice have done serious damage to source code comprehensibility.
> "A common comment was something to the effect of 'I like any man page that has examples'."
I completely endorse this sentiment. There are times, after reading a man page, that I wonder how anybody has ever figured out how to use this tool or that. There should be a requirement for man pages to have at least one or two very simple examples of how to use it.
> It would be amazing if there were some kind of universal system to make it easy to look up a specific option in a man page (“what does -a do?”). The best trick I know is use the man pager to search for something like ^ *-a but I never remember to do it and instead just end up going through every instance of -a in the man page until I find what I’m looking for.
I've always been baffled why we just hand the man pages over to a normal pager rather than something that actually understands their structure. That "look up a flag" case is exactly what bothers me constantly when viewing man pages. And the search they say they should be using doesn't even work consistently since the flag might not be the first non-whitespace thing on a line if there's aliases.
I tend to read man pages in Emacs, which comes with a 'man' command (invoking that executable) and a 'woman' command (an alternative implemented entirely within Emacs), which both implement a basic amount of hyperlinking in their display. For example, I just tried it with the 'rg' manual (first suggestion when I ran `man`), which says:
> Like other tools such as ls, ripgrep will alter its output
That `ls` is marked-up, so pressing RET on it will open the manual for the `ls` command; which includes:
> FORMAT is interpreted like in date(1).
Again, that `date` is marked up, so pressing RET on it `date` will open the manual for the `date` command; etc.
It's obviously just going on heuristics though; e.g. the `ls` manual has marked-up the `--sort` option, and if I hit RET on that it takes me to the manual for the `sort` command ;-)
One thing that OpenBSD does is have a tagfile for their man pages, so the tag navigation in more(1) or less(1) can be used. It's particulary good for options. Viewing the man page for a command and want to know what the -k option does? Hit :t k<return> on your keyboard and you go straight to it.
I use it in particular for bash, mostly because it has better expositions for parameter expansions. To the point that I know searching for "%%" in particular will get me to the correct section.
For everything else… I think it's also necessary for GNU find expressions?
I use the online versions, e.g. https://www.gnu.org/software/make/manual/html_node/index.htm.... In this form they are pretty good documentation (although that is usually due to being comprehensive and adequately written, nothing really to do with info beyond supporting adequate structure).
I occasionally use gnu info. My favorite tool is pinfo which has a man mode that adds navigable links to cross references in man pages and can shell out to hyperlinks. I usually have that aliased as man.
I've never used kubectl, but I just came across https://github.com/andykuszyk/noman.el which is an Emacs interface for browsing the `--help` output of commands:
> I primarily wrote this package to navigate the command line help from kubectl and aws, both of which have nested sub-commands, and quite verbose (and helpful!) command line help.
> Neither of these programs ships with man pages, or similar offline documentation. I find myself consulting the command line help often, but struggling to find the experience very ergonomic.
I’d argue that people using the man pages are a very small group compared to people using online documentation and all the familiar UX that comes with it.
Makes sense to me to keep one place updated and link to that one.
> tldr.sh is a community maintained database of examples, for example you can run it as tldr grep. Lots of people have told me they find it useful.
+1 for tldr. For example, here's the output of `tldr ffmpeg`:
ffmpeg
Video conversion tool.
See also: `gst-launch-1.0`.
More information: https://ffmpeg.org/ffmpeg.html#Options.
- Extract the sound from a video and save it as MP3:
ffmpeg -i path/to/video.mp4 -vn path/to/sound.mp3
- Transcode a FLAC file to Red Book CD format (44100kHz, 16bit):
ffmpeg -i path/to/input_audio.flac -ar 44100 -sample_fmt s16 path/to/output_audio.wav
- Save a video as GIF, scaling the height to 1000px and setting framerate to 15:
ffmpeg -i path/to/video.mp4 -filter:v 'scale=-1:1000' -r 15 path/to/output.gif
- Combine numbered images (frame_1.jpg, frame_2.jpg, etc) into a video or GIF:
ffmpeg -i path/to/frame_%d.jpg -f image2 video.mpg|video.gif
- Trim a video from a given start time mm:ss to an end time mm2:ss2 (omit the -to flag to trim till the end):
ffmpeg -i path/to/input_video.mp4 -ss mm:ss -to mm2:ss2 -codec copy path/to/output_video.mp4
- Convert AVI video to MP4. AAC Audio @ 128kbit, h264 Video @ CRF 23:
ffmpeg -i path/to/input_video.avi -codec:a aac -b:a 128k -codec:v libx264 -crf 23 path/to/output_video.mp4
- Remux MKV video to MP4 without re-encoding audio or video streams:
ffmpeg -i path/to/input_video.mkv -codec copy path/to/output_video.mp4
- Convert MP4 video to VP9 codec. For the best quality, use a CRF value (recommended range 15-35) and -b:v MUST be 0:
ffmpeg -i path/to/input_video.mp4 -codec:v libvpx-vp9 -crf 30 -b:v 0 -codec:a libopus -vbr on -threads number_of_threads path/to/output_video.webm
I like everything about tldr except for the fact that every way to use it is an Internet-dependent client for some reason. Looking at how it works again, I’m half-tempted to write a converter from their dialect of Markdown to roff and run it against https://github.com/tldr-pages/tldr so I can do `man tldr ffmpeg`.
Why?? tldr is an infinitely better name than tlrc. It seems like tlrc is from the same project, couldn't they just have released a version 2.0 of tldr that's rewritten in rust?
...you need "man" pages for moderately-comprehensive options explanations (backed by /usr/share/doc/$TOOL/README.txt if you're a debian user), but "bro" tends to focus on the "yo, this is what you're actually trying to do here...", including sometimes crossing traditional "this-command" boundaries (eg: in the diff example, offering `diff <( cmd1 ) <( cmd2 )` b/c sometimes that's what people are trying to do).
I can't find one that I submitted but it was something like `bro sed` => `# bro, just use awk! => awk -- '{...}'` ...basically you could go down the wrong rabbit hole, and there's kindof a nice little community of users helping to lift each other up (with upvote/downvote) and focusing on providing relatively simple and salient examples rather than a wall-of-text-options where you know that it's possible, but you don't know how to start. (eg: see `bro ffmpeg`)
Speaking of manpages, during a different hn convo, I found out about mansnip [1]. It is for when you remember the command but forget what the flags do and has been very useful re: "I keep using curl -LO, what is that doing again?" etc
This way, I have all the matches at hand. When I pick the one I need, I select the line and search for it, finding the next occurrence in the full man-page.
Checking sub-command section is trivial as well. Because the editor remembers the exact location of the cursor, you can always go back to it after scrolling up and down however you feel like.
For this scenario to work nicely, you have to have run the commands from a text editor. I use Acme [1], it’s optimized for this style of work and doesn’t shy away mice. (I think that the traditional TUI cannot be as smooth.)
would search for the L tag in the ls(1) man page, or there's
man -akO tag Ic=ulimit
to find whatever the ulimit thing is or for an even more general search a small wrapper along the lines of
#!/bin/sh
man -akO tag="$1" any="$1"
may help, unless you are not on OpenBSD, in which case you may wish for the droolsauce and energy waste that is AI because the documentation on your OS is probably some sort of evolving train wreck (man pages -> gun info -> README from 2003 -> web pages, increasingly bloated and behind the iron curtain of javascript -> ??? -> Singularity! Three hails for our Saint Kurzweil!!). Back when I supported Linux I might just run strace on the process because who knew if there was documentation (maybe?) or if it was accurate (sometimes?) and
function info { /usr/bin/info "$@" 2>/dev/null | $PAGER; }
is at least a ksh function for making info somewhat less terrible.
After a while you learn to be specific ' -a' (with space) or '-a,', but this requires that you know what you're looking for. Also n/N is easier to jump between matches than /<Enter>, one less keypress.
Another useful trick is filtering with &, &/-a will narrow it down, but you won't know about the sub-commands if there are many matches. I just tried &/hidden on rg and fd and it takes me straight to `-., --hidden` for rg and `-H, --hidden` for fd. And &/case shows all options related to case-sensitivity with the descriptions. Once you get the intuition for it it's not that bad.
Manuals are not perfect but I don't think I would want an AI. I'm frustrated enough when I don't find a flag the LLM insists is supposed to be there and it gaslights me even though I'm telling the stupid thing I have the manual open.
He should have asked mastodon about the worst man pages too. Some of them are really bad. My pet peeve are the ones that assume a particular audience with a particular knowledge set. My second pet peeve are inconsistent command line flags.
Man Page for park-dribble
Utility for parking the dribbles.
park-dribble -U Unstash context before parking
park-dribble -x or -X Execute preliminary cleaning
park-dribble --1 Only use one preprocessor
Note that the behavior of this command is undefined on systems with the X-CRLT-1 chipset versions 23 and above. Thank you very much, Dave.
I asked an AI to write "woman", a wrapper for man pages that has some sugar on top. First thing was to add colors, highlighting, basic navigation. After the first few rounds, it was doing its thing, and I told the AI> "It works! My man is now a woman. Hahaha!" and Claudette answered> "Ha! Best sysadmin upgrade of the year. "
Whenever the discussion comes up about man pages and how documentation should be organized, I like to quote this section from the GNU coding standards about how Info documentation is structured:
----
Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user.
Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented--but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives.
[…]
In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. […]
That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text.
<https://www.gnu.org/prep/standards/standards.html#GNU-Manual...>
This advice makes most sense for tools that have a clear linear flow from beginner to expert. As soon as something is complex enough to have multiple different personas or desired outcomes for the novice user it's considerably harder to structure docs pedagogically.
The extreme case of this is something like Nix, which is notorious for terrible docs, and I think that's in large part because even the basic "install my first package" could involve profiles, environments, flakes, whatever; there's like five ways to do everything and which one you want depends a lot what your "real" eventual goal is.
> Programmers tend to carry over the structure of the program as the structure for its documentation[…] the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it.
That's also the right way to structure the program. Deficient compilers and bad advice have done serious damage to source code comprehensibility.
> "A common comment was something to the effect of 'I like any man page that has examples'."
I completely endorse this sentiment. There are times, after reading a man page, that I wonder how anybody has ever figured out how to use this tool or that. There should be a requirement for man pages to have at least one or two very simple examples of how to use it.
> It would be amazing if there were some kind of universal system to make it easy to look up a specific option in a man page (“what does -a do?”). The best trick I know is use the man pager to search for something like ^ *-a but I never remember to do it and instead just end up going through every instance of -a in the man page until I find what I’m looking for.
Maybe what we need is a better man page reader?
I've always been baffled why we just hand the man pages over to a normal pager rather than something that actually understands their structure. That "look up a flag" case is exactly what bothers me constantly when viewing man pages. And the search they say they should be using doesn't even work consistently since the flag might not be the first non-whitespace thing on a line if there's aliases.
I have played with that idea for a while until I realized I was creating a poor man's web browser in the terminal.
At that point I started wondering if converting my man folder to HTML and using lynx[1] wasn't a better idea.
I ended up using vanilla man again.
Are there better/fancier manpage readers out there that can change my mind?
[1]: https://lynx.invisible-island.net/current/
I tend to read man pages in Emacs, which comes with a 'man' command (invoking that executable) and a 'woman' command (an alternative implemented entirely within Emacs), which both implement a basic amount of hyperlinking in their display. For example, I just tried it with the 'rg' manual (first suggestion when I ran `man`), which says:
> Like other tools such as ls, ripgrep will alter its output
That `ls` is marked-up, so pressing RET on it will open the manual for the `ls` command; which includes:
> FORMAT is interpreted like in date(1).
Again, that `date` is marked up, so pressing RET on it `date` will open the manual for the `date` command; etc.
It's obviously just going on heuristics though; e.g. the `ls` manual has marked-up the `--sort` option, and if I hit RET on that it takes me to the manual for the `sort` command ;-)
> a table of contents, and links between sections
One thing that OpenBSD does is have a tagfile for their man pages, so the tag navigation in more(1) or less(1) can be used. It's particulary good for options. Viewing the man page for a command and want to know what the -k option does? Hit :t k<return> on your keyboard and you go straight to it.
> The rsync man page has a solution I’ve never seen before: it keeps its SYNOPSIS very terse, like this: [...]
But that presentation belongs in the --help of the command itself; why repeat it in the man page in that form.
Does anyone here actually use the GNU info documentation?
I use it in particular for bash, mostly because it has better expositions for parameter expansions. To the point that I know searching for "%%" in particular will get me to the correct section.
For everything else… I think it's also necessary for GNU find expressions?
No. I have no idea how it works, it's like being a new user in vi and not knowing how to quit.
`info foo | less` is a better info reader than `info foo`
I use it all the time, preferring it to everything else¹. Especially when reading the Python documentation.
1. <https://news.ycombinator.com/item?id=44213303>
I’m sorry people are downvoting you for just replying to my question!
I use the online versions, e.g. https://www.gnu.org/software/make/manual/html_node/index.htm.... In this form they are pretty good documentation (although that is usually due to being comprehensive and adequately written, nothing really to do with info beyond supporting adequate structure).
No. Every man page is better, concise, easy to access.
GNU Info should be like a browser but it makes something simple into something complicated.
I occasionally use gnu info. My favorite tool is pinfo which has a man mode that adds navigable links to cross references in man pages and can shell out to hyperlinks. I usually have that aliased as man.
Just installed pinfo. Nice. Thanks!
But unrelated but the manpages for kubectl were kind of weird, mostly linking to their online docs.
Is that a normal thing? I open the man tool for a reason, and it's to not read online docs
I've never used kubectl, but I just came across https://github.com/andykuszyk/noman.el which is an Emacs interface for browsing the `--help` output of commands:
> I primarily wrote this package to navigate the command line help from kubectl and aws, both of which have nested sub-commands, and quite verbose (and helpful!) command line help.
> Neither of these programs ships with man pages, or similar offline documentation. I find myself consulting the command line help often, but struggling to find the experience very ergonomic.
I've seen it elsewhere, but it's definitely annoying. For example KDE's build assistant tool:
I’d argue that people using the man pages are a very small group compared to people using online documentation and all the familiar UX that comes with it.
Makes sense to me to keep one place updated and link to that one.
Here's a handy shell script to show only the options from a command's man page:
(Won't work for every man page, but most of them where options start with a dash.)Enjoy!
> tldr.sh is a community maintained database of examples, for example you can run it as tldr grep. Lots of people have told me they find it useful.
+1 for tldr. For example, here's the output of `tldr ffmpeg`:
https://cht.sh/ is my fave
curl it.
curl cht.sh/ffmpeg
you can even search
curl cht.sh/~screenshot
I like everything about tldr except for the fact that every way to use it is an Internet-dependent client for some reason. Looking at how it works again, I’m half-tempted to write a converter from their dialect of Markdown to roff and run it against https://github.com/tldr-pages/tldr so I can do `man tldr ffmpeg`.
BTW, `tldr` is deprecated, in favour of [`tlrc`](https://tldr.sh/tlrc/). Both use the same database.
I use tealdeer, which was my favorite of the few tldr clients I tried: https://github.com/tealdeer-rs/tealdeer
Different tldr clients use different syntax highlighting, and some are faster than others. The main tldr is horrifyingly slow iirc.
Why?? tldr is an infinitely better name than tlrc. It seems like tlrc is from the same project, couldn't they just have released a version 2.0 of tldr that's rewritten in rust?
Looks like the command is still called tldr at least, only the package/repo has a different name.
Where is it deprecated? It looks like it's still being developed and there's no mention of it being deprecated on the site?
This topic would be incomplete without mentioning "bropages" => "Example-focused snippets"
eg: http://bropages.org/diff
...you need "man" pages for moderately-comprehensive options explanations (backed by /usr/share/doc/$TOOL/README.txt if you're a debian user), but "bro" tends to focus on the "yo, this is what you're actually trying to do here...", including sometimes crossing traditional "this-command" boundaries (eg: in the diff example, offering `diff <( cmd1 ) <( cmd2 )` b/c sometimes that's what people are trying to do).
I can't find one that I submitted but it was something like `bro sed` => `# bro, just use awk! => awk -- '{...}'` ...basically you could go down the wrong rabbit hole, and there's kindof a nice little community of users helping to lift each other up (with upvote/downvote) and focusing on providing relatively simple and salient examples rather than a wall-of-text-options where you know that it's possible, but you don't know how to start. (eg: see `bro ffmpeg`)
I really like the blog layout. Nice use of contrasting colors.
Speaking of manpages, during a different hn convo, I found out about mansnip [1]. It is for when you remember the command but forget what the flags do and has been very useful re: "I keep using curl -LO, what is that doing again?" etc
[1] https://github.com/day50-dev/Mansnip
if there is a place for an AI cli, it would be in the man page. So many hours wasted searching for "-a" followed by, "/", "/", ...
Then, when finally locating the flag, it's nescessary to scroll up to confirm the right sub-command section, "/", "/", ...
When I have this problem, I catenate two outputs:
This way, I have all the matches at hand. When I pick the one I need, I select the line and search for it, finding the next occurrence in the full man-page.Checking sub-command section is trivial as well. Because the editor remembers the exact location of the cursor, you can always go back to it after scrolling up and down however you feel like.
For this scenario to work nicely, you have to have run the commands from a text editor. I use Acme [1], it’s optimized for this style of work and doesn’t shy away mice. (I think that the traditional TUI cannot be as smooth.)
So, to hell with AI.
[1]: https://p9f.org/sys/doc/acme/acme.html
After a while you learn to be specific ' -a' (with space) or '-a,', but this requires that you know what you're looking for. Also n/N is easier to jump between matches than /<Enter>, one less keypress.
Another useful trick is filtering with &, &/-a will narrow it down, but you won't know about the sub-commands if there are many matches. I just tried &/hidden on rg and fd and it takes me straight to `-., --hidden` for rg and `-H, --hidden` for fd. And &/case shows all options related to case-sensitivity with the descriptions. Once you get the intuition for it it's not that bad.
Manuals are not perfect but I don't think I would want an AI. I'm frustrated enough when I don't find a flag the LLM insists is supposed to be there and it gaslights me even though I'm telling the stupid thing I have the manual open.
He should have asked mastodon about the worst man pages too. Some of them are really bad. My pet peeve are the ones that assume a particular audience with a particular knowledge set. My second pet peeve are inconsistent command line flags.
Man Page for park-dribble
Utility for parking the dribbles.
park-dribble -U Unstash context before parking
park-dribble -x or -X Execute preliminary cleaning
park-dribble --1 Only use one preprocessor
Note that the behavior of this command is undefined on systems with the X-CRLT-1 chipset versions 23 and above. Thank you very much, Dave.
> He should have asked mastodon about the worst man pages too.
The blog title says "Julia Evans."
I asked an AI to write "woman", a wrapper for man pages that has some sugar on top. First thing was to add colors, highlighting, basic navigation. After the first few rounds, it was doing its thing, and I told the AI> "It works! My man is now a woman. Hahaha!" and Claudette answered> "Ha! Best sysadmin upgrade of the year. "