do you have a favourite man page? thinking of writing a short blog post exploring man pages and what makes a good one and I'd love some more examples
my contribution: I think it's cool that `man curl` includes an example for every single option
@b0rk `man ascii` is the one i look at most often
@b0rk I love tealdeer (tldr) precisely because it fills the gap in examples for every common operation
@b0rk my favorite one is man after midnight (gimme gimme gimme!)
https://unix.stackexchange.com/questions/405783/why-does-man-print-gimme-gimme-gimme-at-0030
@b0rk I find the BUGS section on Linux's man page cu(1) pretty amusing
@b0rk sox(1), for Sound eXchange (the Swiss Army knife of audio manipulation). It's very long, yet gives examples of all of its filters and complicated syntax.
Its sound format conversion section got so long that it ended up in soxformat(7)
@b0rk I like the man page for strace, because it groups the options by categories: General/Startup/Tracing/Filtering/Output. This makes it easier to discover what is available for a specific purpose. Other man pages just list the options strictly alphabetically (let's say for example the GNU ls man page).
@raimue ooh that's really cool, I don't know how I never noticed that! I think I always assume man pages will be hard to use and I often don't even bother to check and miss it when they're actually well organized
@b0rk ffmpeg's seems pretty cool. It has graphs, even.
@b0rk `curl` is heads and shoulders above most other man pages I've read. Also, I have a terrible memory when it comes to curl, so it's always useful.
@b0rk I see a sibling mentioned ascii(5). urxvt(7) is a great reference to terminal escape codes, broadly applicable even if it's not the terminal you use. There's probably a better reference but it's the one I know to turn to when I have questions.
@b0rk My bash_history thinks I've used man gpg the most lately but that is not an endorsement 😭
@b0rk I am actually surprised how many people here don't know https://tldr.sh. Or at least, thats a feeling I had while reading the comments on bad manpages.
`$ tldr tar`
It's a user composed tl;dr; printing out commonly used commands.
And recently I learned from https://youtube.com/@breadonpenguins about cht.sh. Its even better. Simply type `$ curl cht.sh/cups` and you get a awesome cheatsheet covering basic Linux printer things.
It somehow aggregates multiple sources. One of the sources is actually the tldr.sh page.
@b0rk I love `man ascii`.
@b0rk Such a great page to point out. We all learn in different ways.
I don't just want to be told how something works. Please _show_ me how it works.
@b0rk I was particularly surprised and happy seeing a code example in xscreensaver-command man page [1], which showcases the way it (xscreensaver-command -watch) can be integrated into the system doing some dynamic stuff.
Despite it's Perl, which I can barely read, but it looked like a really nice addition.
@b0rk
I like section 7 in general - it can provide a good overview and tie together many different manpages relevant to a single topic that'd otherwise be hard to track down.
If I have to pick one, I guess it's
capabilities(7)
@b0rk I've always thought the jq man page is quite good. Lots of good examples
@b0rk I'm not sure, if I measure it by times I read it, it should be tar, but because of its number of options. Regarding the fun of reading it or the fact I'm confident I will find the information I need, none really qualify
@b0rk `man man` flashed me recently
@b0rk grindr (SORRY)
false (8) is my favourite
@b0rk Why were example usages shunned by many man pages I'll never understand.
@b0rk In the attention to detail category, the BUG detailed in the NetBSD sleep(1) man page is a favourite:
I think my favourite man page example so far is this rsync man page (via @shnizmuffin) https://download.samba.org/pub/rsync/rsync.1
it gives examples BEFORE giving an exhaustive list of options!
the synopsis just says "rsync [OPTION...] SRC... [DEST]" instead of giving you an exhaustive list of options like "-ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%"!
there's an "OPTION SUMMARY" section that gives you a 1-line summary of each option! (this feels SO SO much useful than the normal SYNOPSIS to me)
(2/?)
@b0rk
The rsync manpage is among the greatest. One of its great feature is the list of every return code and their meaning, really helpful when scripting!
I'm quite fond of the bash manpage
@shnizmuffin
i tried implementing this OUTPUT SUMMARY format for grep's man page, I can't tell if I like it or not but it's an interesting exercise to try to give a 1-line description of each item, categorize them, and then order them most-frequently-used-by-me first https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf
(probably some of the descriptions are wrong, I only thought about them for maybe 3 seconds each, also this is Mac grep)
(3/?)
@b0rk @shnizmuffin Count on Apple to f*ck things up:
NAME
openrsync – synchronise local and remote files
SYNOPSIS
openrsync [-0468BCDEFHILOPRSTWVabcdefghiklmnopqrtuvxyz] [-e program]
[-f filter] [--address=sourceaddr] [--append]
[--backup-dir=directory] [--bwlimit=limit]
[--cache | --no-cache] [--
etc.
@b0rk Special shout out to the official web address, since it's got hyperlinks on all the options:
@shnizmuffin thanks, will change my link!
I use `man date` very often when I have to format dates - most programming languages use the same syntax so it's convenient when I don't remember if %m is "month" or "minute"
I like it because I know where to look and it works for a *lot* of programming languages (Go and php being rare exceptions)
@b0rk @shnizmuffin if something needs a solid man page, it's probably sync. 
Destroyer of files.
With great power comes great responsibility.
@b0rk I don't believe to have a favourite. Yet, due to the rule (rather 'tip') "'Select' Isn't Broken", select(2) and the corresponding story behind the tip from the book "Pragmatic Programmer" comes to my mind :)
@b0rk I do like it too, even thought it makes the man page 7195 lines long 😃 .
I love the man bash
But although the lvm commands man. With useful examples that cover lot of case !
@b0rk the one I've used the most is `man bash`, because it's not just a man page, it's the documentation for the whole scripting language!
@technicaladept @nabnux i think for bash specifically I might prefer to use the html bash reference manual to reference the docs https://www.gnu.org/software/bash/manual/bash.html (which I believe has the same content but with better formatting)
@b0rk @nabnux these day's yes. Back in the day the next best was to send it to the line printer and read it on a fan fold continuous feed printout. Many people I knew kept a copy on their desk. https://en.wikipedia.org/wiki/Continuous_stationery#/media/File:Endlospapier_fan-fold_paper.jpg
@b0rk I was always partial to `man man`.
Great to introduce people to `man` so they can bootstrap their command-line-fu.
@b0rk Off the dome, I feel like I remember the man page for find almost always getting me where I needed to go
@b0rk it's `rsync` and it's not even close.
@shnizmuffin what do you like about it? (also: you mean this one right? https://linux.die.net/man/1/rsync)
i like that it takes a different approach to the SYNOPSIS and puts examples before the comprehensive list of all options, I haven't seen that a lot
@b0rk It leads with examples from most common to least common, and sorts its many options following similar logic.
It's basically ...
1. WTF am I looking at. (--verbose et al)
2. Sensible defaults (--archive)
3. How do I change one thing (-no-OPTION)
4. Filepath stuff
5. Link stuff
6. Permission stuff
7. File metadata stuff
8. Config stuff
9. Filter stuff
10. Shit one person needed once
11. --human-readable
12. please don't run forever
12 --version, --help
@shnizmuffin i didn’t even notice the option sorting, that’s so good
@b0rk Awesome post idea :-)
@b0rk The man page for telnet changed my life around 1992. I can't remember exactly why, but hopefully by posting this it'll spur my memory and I can go look it up and remember it and I'll let you know.
@b0rk I...don't think I've ever found a man page readable, tbqh. :(
@thatandromeda I have a hard time with them too, that's why I've been thinking about this
@b0rk @thatandromeda Often I pipe the output of `man` into `less`, then try to search for something like -n, which returns way too many results (e.g. mentions of that option before its definition). I wonder if a better `man` could be made that would let me search through an *index* of options instead of doing a full-text search.
@b0rk it's an uncool example these days but...
i always really appreciated how `man perl` links to 40+ other man pages that collectively describe the entire language and its standard library and tools. so if you are trying to learn about it everything you need is there and can be browsed or searched for. the prose is fairly engaging and well-written.
(these days online might make more sense but at the time having it available offline in a very lightweight format that was readable from the terminal was great.)
P.S. the manual pages are actually produced by perldoc which is also a very cool related tool.
@d6 this is so cool, I've never looked at this before! makes me want to find out who wrote them.
I have a soft spot for "man ascii"
@b0rk grep(1) because I have to pull it up every time I forget whether the string or the filename goes first! Also its example section is very good too.
@bretthaines the Mac grep man page?
@b0rk yes, my work computer is a mac so that's the one I pull up more often. I forgot the Linux one is different 😅
@b0rk i frequently use ascii(7)
I have a soft spot for `man ascii`
@b0rk my favourite is quite simple: `man ascii`
@b0rk The entire perl ecosystem. perlfunc(1), perlsyn(1), etc.
@aredridel @b0rk oh, my favorite there is perllol(1)
@arrjay @aredridel this is awesome, I love `perlcheat`, I've never seen anything like that in a man page
@b0rk @arrjay @aredridel perlre(1) — along with perlretut(1) and perlrequick(1) — are the Complete Beginner's Guide to Regular Expressions. The language is quite gentle, especially for a subject that so many people find difficult.
@b0rk mine's probably OpenBSD's utf8(7): https://man.openbsd.org/utf8
