I am begging developers of command line tools to simply write an example of the working command after the options.
reading a 1000 lines of documentation with a million -flags and -switches and then guessing how im supposed to use them is not fun. many many non coders want to use your program. Let us copy paste the working command and then edit to our needs
@nix
For that specific case, I personally just side stepped the options and wrote a wrapper script that just changes directories first. I do expect the controls are there somewhere, but I really didn't want to bother figuring them out.
(This script predates me using yt-dlp, originally for youtube-dl. Having a wrapper with the most common options I care about also lets me change tools easily.)
@nix Have you seen https://tldr.sh/ ? I find it indispensable.
Of course you are correct, this should be included in all command line tool documentation by the authors/maintainers, rather than relying on a third party tool to address the problem.
@nix yeah, the worst for me is when I download "weebl, a tool for doing X" and I have to read the whole documentation because they haven't just told me up front what the shortest working command for doing X is
(and obviously there are tools for which the idea of a "shortest working command" either isn't useful or doesn't make sense, but I think those are probably rarer than the reverse)
@nix the recommended order of sections in Perl's POD documentation had a "SYNOPSIS" section at the top (https://perldoc.perl.org/perlmodstyle#POD):
"Your SYNOPSIS section should contain a minimal example of use"
SYNOPSIS should be after NAME and before DESCRIPTION. Because most people reading your docs already know what the utility does and just want to know how to invoke it. I haven't wielded Perl in anger for quite some time, but it got a few things right when it came to communicating ideas, and I miss that.
@trurl @nix I think the issue is many (including me) took "should contain a minimal example of use" and stuck my-tool [options] [arguments] there, or worse my tool -acvheZLVHVEhvD --flag --other-flag -omgmakeitstop...
IMO, the spec would be better if it removed SYNOPSIS and said to put EXAMPLES up after NAME instead.
That said, I'll be making better SYNOPSISes from now on.
@nix Unix documentation started with "Here is the Man utility, it prints out a manual for a program, you should be able to reverse engineer the program from the manual".
Then came GNU who decided to replace Man with Info. It had more features, and used Hypertext. So it was harder to read, and important information got hidden in nested hypertext links.
And then came people who said "Just read the website. It has the source code".
And now there's apps who's documentation is a Discord server.
Honestly sounds like a decent use-case for LLM AI. Give the README to the AI as context and ask it to craft the command-line that you desire, and then just double check it
ah yeah, my favorite man pages are the ones I know I can rocket down towards the end to find some examples
YES!
Also, a couple of sensible examples with a brief description of what it'll do would be nice.
I am begging developers of command line tools to simply write an example of the working command after the options. reading a 1000 lines of documentation with a million -flags and -switches and then guessing how im supposed to use them is not fun. many many non coders want to use your program. Let us copy paste the working command and then edit to our needs
@nix I'm looking at you "ip". I've had just some networking issues and tried to guess what I'm supposed to do just with the manpage.
Yes, there are examples in «man ip-address», but still, it always feels unintuitiv to me. And I'm called Mr. Manpage at work, as I'm usually produce long commands without the need to look them up.
And I don't mourn after ifconfig, I know "ip" has to support IPv6 and other features. A swiss army knife has many features too, but it's easy to just open the blade.
@nix THIS!!!
Every time I look at a man page, I scroll to the bottom to look for examples first.
Even if I intend to read the whole man page, examples go a LONG way to understanding the overall vibe of the tool and to give context for the documentation.
@nix ... I've never missed an example section for ls, rm, grep, ...
And they all quite have some (optional) arguments.
@nix This is the reason why I have https://www.mankier.com/ bookmarked as a search provider. I look up most documentation there, because they *lead* with the examples.
It is so much better because 90% of the time I want to do something super-lame that's probably contained in the first 3 examples.
༺NIX༻
laskfar
lee
kfet
Jia Tan's mom
Eli the Bearded
Nelson
Dominique Cyprès
josch
nfilipes
Low Rank Jack
بلبل
lachlan slowly taming rust
ctrlsaltdelete
I’m Tired And Everything Hurts
atyh
deedend 
june
synlogic
Adlangx
Cody
Per Vognsen
Bynkii
dstu
Pat Brisbin
Omar Antolín
rastilin
Σ(i³) = (Σi)²
Raffaele Orabona
JW prince of CPH
Jay Blanc
івась тарасик
idlestate's SDF liason acct
federico 
HistoPol (#HP) 🏴 🇺🇸 🏴
nigel
Andy
*((char *)NULL) = '\0';
Bill Herndon
nickapos
pino
Claudius