← Back to context

Comment by ndsipa_pomu

1 month ago

Along with the "-h,--help" options, an option to show common usage examples would be useful. I find it much easier to learn from an example as you can modify and build upon it. Otherwise, it's a case of skimming through the man page and then switching back and forth between the man page and the command that I'm writing. (This is most common with tools that I don't use all the time, yet have expert features such as "ffmpeg")

10 comments

ndsipa_pomu

Reply
1718627440  1 month ago

> an option to show common usage examples would be useful.

That's what the man page is supposed to be (and most do contain example) and why GNU wanted to split it into info (tutorials and exhausting documentation) and man (reference and examples).

  • ndsipa_pomu  1 month ago

    Yep, the examples on man pages are helpful, but I'd like a slimmed down option to just show the examples and a one-line description for the examples.

    I usually end up just doing a quick web search for the command if it's not one that I'm familiar with (i.e. where I have read the man page).

    An extreme example of my issue would be trying to find BASH examples of how to process a list of files - the man page on BASH is fairly lengthy.

    Meanwhile, Greg's wiki provides this example of processing mp3 files:

      while IFS= LC_ALL=C read -r -d '' file; do
    some command "$file"
  done < <(find . -type f -name '*.mp3' -print0)

    • 1718627440  1 month ago

      Why do you serialize and then deserialize the list of files? Even if you do disable the splitting on reparsing the list, why don't you just do this:

          find . -type f -name '*.mp3' -exec some command {} ';'

      That sounds just unnecessary and bug prune. Unless you target some odd platform where find doesn't support '-exec', but it is even in POSIX. I think due to your use of process substitution, your code has a higher chance of being unportable, so why do you want to complicate your code?

      Stuff like that is why I personally prefer the man pages to random websites.

      Honestly for something as complex as a shell (which describes both a language, an editor, and an implementation) the man page is surprisingly short. (6418 lines for me) I have just found the section on process substitution in <1min, without even using the search, just by reading. I looked it up, because I didn't knew the name of that syntax, so I needed to actually look for what I wanted and I do not use the man page of bash often.

      7 replies →