do you have a favourite man page?
-
@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
13. --version, --help -
I think my favourite man page example so far is this rsync man page (via @shnizmuffin) https://www.man7.org/linux/man-pages/man1/rsync.1.html
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 if something needs a solid man page, it's probably rsync.
Destroyer of files.
With great power comes great responsibility. -
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@jvns.ca i often work offline, so i like long and elaborate man pages that go into every absurd detail but also note in-program help mechanisms
nvimbecause it provides a jump start to:Tutorand:help quickrefzshallbecause it explains All the syntax
-
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 In the attention to detail category, the BUG detailed in the NetBSD sleep(1) man page is a favourite:
-
@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
13. --version, --help@shnizmuffin i didn’t even notice the option sorting, that’s so good
-
-
@b0rk i always think
hier(7)is really neat -
@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!
-
@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.
-
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 Why were example usages shunned by many man pages I'll never understand.
-
@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)
-
I think my favourite man page example so far is this rsync man page (via @shnizmuffin) https://www.man7.org/linux/man-pages/man1/rsync.1.html
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 Special shout out to the official web address, since it's got hyperlinks on all the options:
-
I think my favourite man page example so far is this rsync man page (via @shnizmuffin) https://www.man7.org/linux/man-pages/man1/rsync.1.html
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 Count on Apple to f*ck things up:
NAME
openrsync – synchronise local and remote filesSYNOPSIS
openrsync [-0468BCDEFHILOPRSTWVabcdefghiklmnopqrtuvxyz] [-e program]
[-f filter] [--address=sourceaddr] [--append]
[--backup-dir=directory] [--bwlimit=limit]
[--cache | --no-cache] [--etc.
-
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
false (8) is my favourite
-
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 grindr (SORRY)
-
I have a soft spot for "man ascii"
-
@d6 this is so cool, I've never looked at this before! makes me want to find out who wrote them.
-
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 man` flashed me recently
-
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 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
-
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've always thought the jq man page is quite good. Lots of good examples
