Notes on Clarifying Man Pages

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...>

> "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.

> 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.

> 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?

> 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?

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

> 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

Here's a handy shell script to show only the options from a command's man page:

   showoptions() {
      man -s 1 "$*" |col -bx |awk '/^[ ]*-/,/^$/' |less
   }

Enjoy!

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, "/", "/", ...

[dead]

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. "