Notes on Clarifying Man Pages

----

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

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.

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.

Maybe what we need is a better man page reader?

+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

Is that a normal thing? I open the man tool for a reason, and it's to not read online docs

[1] https://github.com/day50-dev/Mansnip

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

Enjoy!

But that presentation belongs in the --help of the command itself; why repeat it in the man page in that form.

Replace it with a better format

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`)

Then, when finally locating the flag, it's nescessary to scroll up to confirm the right sub-command section, "/", "/", ...

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.