do you have a favourite man page?
Uncategorized
119
Posts
85
Posters
0
Views
-
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 @shnizmuffin hah, rsync’s man page (alongside Bash) is to me an example of everything wrong with manpages, because I’m usually looking for a reference explanation of an argument and I have to skip through all the unhelpful examples before getting the actual option explanation.
It’s a shame that GNU Info never stuck. A hierarchical documentation really is the best organization over the flat and not hyperlinked manpages.
(To be fair Info’s UX sucks)
-
@b0rk @shnizmuffin hah, rsync’s man page (alongside Bash) is to me an example of everything wrong with manpages, because I’m usually looking for a reference explanation of an argument and I have to skip through all the unhelpful examples before getting the actual option explanation.
It’s a shame that GNU Info never stuck. A hierarchical documentation really is the best organization over the flat and not hyperlinked manpages.
(To be fair Info’s UX sucks)
@b0rk @shnizmuffin (and Bash’s manpage sucks because it’s just the flattening of its huge and extensive Info doc. When searching is the only navigation option, it’s a chore)
-
@b0rk `man ascii` is the one i look at most often
-
@b0rk `man ascii` is the one i look at most often
-
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 I wish the examples from the Usage section came before anything else. Just put the most common/likely 2 or 3 use cases at the very beginning. This is both better for first time users and for people who used the tool before, but haven't in a long time and just need a brief reminder.
-
@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.
-
@b0rk @shnizmuffin hah, rsync’s man page (alongside Bash) is to me an example of everything wrong with manpages, because I’m usually looking for a reference explanation of an argument and I have to skip through all the unhelpful examples before getting the actual option explanation.
It’s a shame that GNU Info never stuck. A hierarchical documentation really is the best organization over the flat and not hyperlinked manpages.
(To be fair Info’s UX sucks)
@jlargentaye@mas.to @b0rk@social.jvns.ca @shnizmuffin@toots.inbutts.lol
(To be fair Info’s UX sucks)
So, just try #pinfo
-
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 This is probably not what you were looking for but "man ascii" is so good to have.
-
@b0rk This is probably not what you were looking for but "man ascii" is so good to have.
@rjbs i had no idea this was going to be the #1 most popular man page by far but I love it
-
@rjbs i had no idea this was going to be the #1 most popular man page by far but I love it
@b0rk For funsies I ran "man unicode" and got… "This is an implementation in Tcl of the Unicode normalization forms."
Wow.
-
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 @bagder I always really liked "man hier" on FreeBSD explaining the filesystem hierarchy. Such a good user experience for an OS. https://man.freebsd.org/cgi/man.cgi?hier(7)
When I was at Etsy on the team maintaining the developer VMs, we replicated it with info about what could be found on the VMs.
Also one of my best open source experiences ever was that my patch to a curl man page got accepted 😇😁 https://github.com/curl/curl/commit/1074cca8cd420eddf724e6e0b40e60e6a080ada1
-
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 I'm so happy with "tldr". Never touched a manpage since. ^^
-
@arrjay @aredridel this is awesome, I love `perlcheat`, I've never seen anything like that in a man page
@b0rk Right!? It's _so good_. Gold standard.
-
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 cmus-tutorial. The format makes it really easy to read, and I have referred to it many times.
-
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 hier(7)
I found it very early in my Unix career. I was exploring `/usr/spool/man/` to find out what there was. I stumbled on `hier.7` and it told me all the *other* places I should explore.
It might be how I found out about /etc/passwd.
-
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 I am slightly embarrassed to admit that until I read this thread, and despite using grep for decades, I was somehow unaware that there was a "-w" option. thank you for making it obvious!
-
@b0rk I am slightly embarrassed to admit that until I read this thread, and despite using grep for decades, I was somehow unaware that there was a "-w" option. thank you for making it obvious!
@shayman I'd never heard of it either!
-
@shayman I'd never heard of it either!
@b0rk amazing how you can overlook things in a long man page. "man page fatigue" sets in after about the 4th screen. Thanks for what you're doing!
-
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 my least favorite man pages were back when all the GNU tools man pages were just stubs telling you to use info. User hostility taken to a level only GNU could manage.
Gli ultimi otto messaggi ricevuti dalla Federazione
-
@cosmattia ma invece come funziona se due PC sono sulla stessa rete?
-
@DigiDavidex Ah ottima notizia! Ero rimasto ancora indietro quando era uscito e non si sapeva nulla se non solo che era open-source. Grazie! 🤗
-
Oh no. They got more The Pitt? I can't handle all the tension and gore, but it's such a good show.
-
RE: https://vmst.io/@iostat/116094117261501045
Getting a paper Burger King crown made up with “LAST TOOTER” printed on it
-
you telling me a cunning hammed this law?
-
I forgot I had a Ubisoft account. Stupid games companies forcing you to have a new account with every publisher. But now they're saying they're locking down the account unless I provide age verification.
Glad I had the foresight to pick the username WHAT_IS_THIS_BS because it sure is a whole lotta BS.
🥹
-
@MarfyMazie It's required by the UK's financial regulator!
-
How to Have a Good Family Life
