do you have a favourite man page?
Uncategorized
119
Posts
85
Posters
0
Views
-
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 have a /least/ favorite, it’s sudoers(5). Dense paragraphs followed by an EBNF grammar of the config format 😭
What I would *expect* to find there is a practical discussion of how to set it up with some simple examples that will set me on my way. I appreciate that authentication is complex & sensitive, and this documentation is very detailed but … I always bounce off this manpage and end up on stackoverflow instead.
-
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
The fish shell ships a python script that extracts this information from the man pages and convert them into tab completions.
/usr/share/fish/tools/create_manpage_completions.py -
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!
Gli ultimi otto messaggi ricevuti dalla Federazione
-
This video is amazing...so amazing, I am skeptical. This is unbelievable dexterity for a robot. There have been huge leaps in the past couple decades, true, but this feels like it's too far, and out of nowhere.
But, there's another technology where China is kicking ass: Generative AI video, especially motion capture/application.
I assume there must be human witnesses, so it seems like word would get out at some point if it were fake, maybe I'm just overly skeptical.
-
Inconsiderate AI scrapers, I assume.
-
@sebzuen snac is a small Fediverse server - I self-host a server as a small playground for myself, it is fun :-)
-
-
Inside a Dutch Street Organ: The Art of Mechanical Music-Making
[James]’ Mechanical Organ of Dutch origin has been around longer than he has, but thanks to being rebuilt over the years and lovingly cared for, it delivers its unique performances just as well as it did back in the day. Even better, we’re treated to a good look at how it works.
The organ produces music by playing notes on embedded instruments, which are themselves operated by air pressure, with note arrangements read off what amounts to a very long punch card. [James] gives a great tour of this fantastic machine, so check it out in the video embedded below along with a couple of its performances.
The machine is mobile and entirely self-contained. It would be wheeled out to a venue, where it would play music as long as one could keep cranking the main wheel and the perforated cardboard book containing the chosen musical arrangement hasn’t reached its end. As perforations in the card scroll by inside the machine, each hole triggers valves that operate pipes, percussion hits, and even operate animatronic figures.
Folded stacks of perforated cardboard make up the musical arrangement.
The air pressure needed to do all this comes from a reservoir fed by two bellows operated by continuous rotation of a large wheel, a job that requires a fair bit of effort. Turning that crank would likely have been the responsibility of the lowest-ranking person within reach. Today, the preferred method is a belt drive and electric motor.The perforated cardboard arrangements mean that the machine is just as programmable today as it ever was, and happily plays classics as easily as Lady Gaga, Daft Punk, and Queen. [James] has an enormous library of music, so take a moment to listen to it play “Night Fever” by the Bee Gees and Daft Punk’s “Get Lucky”.
One interesting tidbit [James] shares is that there is a bit of artistry and skill involved in arranging music for the machine. Some instruments play immediately when triggered (such as the pipes) while others trigger after a delay (like percussion), so one needs to take all this into account when punching the cardboard. There’s a bit more info on [James]’ website about his machine and its history.
In addition to being a fascinating piece of musical and mechanical history, it is another example of just how effective of a technology punched card was. Many of us might think of early computing or even music when we think of punched cards, but the original use was in running looms and knitting machines.
youtube.com/embed/KG_k6iyC2ME?…
youtube.com/embed/Ua0W3nVtZ0M?…
youtube.com/embed/EWO1-WE4oNw?…
Thanks [Keith Olson] for the tip!
-
-
-
@cosmattia ma invece come funziona se due PC sono sulla stessa rete?
