The idea that manuals in linux are a good way to learn and understand new software is peak linux neckbeard bs, and I will die on this hill. I congratulate OP on the exact type of autism that lets them feel this is an effective and useful method for learning new software, but if there is desire to have a greater adoption of linux maybe its bad to be snarky at folks for not instantly understand the terminal based documentation conventions of some dudes in the 70s. Maybe an alphabetical* list of all possible options is okay for referencing or searching, but is objectively insane way to learn or understand a problem.
THIS. I feel like linux man pages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages first
as a professional sociotechnical problem solver I will join you on this fatal hill
like take the 4 types of documentation in diátaxis
man pages usually fulfill the reference need, and sometimes kind of that of how-to guides if you’re lucky and your local man has examples
but that leaves more than 50% of documentation needs lacking
and discoverability is atrocious – you have to already know that the command (or commands) you need exists and what it’s called
one of the most useful things I learned in a linux sysadmin course was apropos / man -k, which lets you search installed man pages by keyword. but hardly anyone else seems to know about it – I only learned of it because a teaching assistant mentioned it off hand! – and even then it only helps if you guess the right keyword for your problem
ssh connects and logs into the specified destination, which may be specified as either [user@]hostname or a URI of the form ssh://[user@]hostname[:port]
That’s how I would interpret that part of the man page had I no familiarity with ssh. It doesn’t seem reasonable to expect the reader to know what those brackets mean.
You get to learn the notation conventions with <> and [] fairly early on. Maybe a very new user would make that mistake. If he doesn’t get it fairly quick, maybe computers aren’t for him.
Nah m8, I’m generally on board with asking people to read the manual, but these unexplained conventions are nonsense. Pages really should be explicit about notation being added to commands that aren’t actually a part of them
Sure, but that is very far from obvious, and very few people who don’t already have an understanding of this stuff are going to know to look there. When I search for how to do something on the internet I mostly find 2 kinds of sources: stuff that’s way dumbed down (and usually out of date/incorrect) and stuff full of unexplained notation/abbreviations/arbitrary conventions without any links to resources that explain them.
I guess my issue with the man pages is mostly that they just don’t try to be approachable to the not-so-tech-litterate folk who might be interested in Linux if we had resources that didn’t assume all this foreknowledge.
BS. I’ve been using linux for over 20 years and I still don’t know what those mean. I can only guess from context. It’s a stupid convention to just use symbols like that and never explain it.
Following the openbsd example from the original comment I replied to, it has absolutely nothing to say about what brackets mean, so this advice would not be helpful for an openbsd system: https://man.openbsd.org/man
On my personal linux system (arch derivative, by the way), it at least mentions brackets meaning optional, but only in the context of arguments:
[-abc] any or all arguments within [ ] are optional.
I think this would trip up some new users. The destination, with or without the username to connect as, may not seem like an “argument” to a new user since it doesn’t have a dash before it like the example does
It’s a good thing there are other resources, then. You can read tldr-pages. You can look at various official and unofficial wikis. You can look at Stackoverflow. You can look at Youtube tutorials. You can ask other people. Hell, you can ask a chatbot.
If the average user is unwilling to do that, maybe it’s better that Linux does not see a wider adoption.
is the fact that people can with effort and error figure out how to do something a reason not to make it easier for them to do?
I mean
you can in theory write multi-threaded bug-free C code – just read the docs and the specs and the source of your libs and never ever do something that seems to work but is subtly fatally incorrect
and yet we still have golang and rust and many other options to do things more safely and easily
if someone wants to use Linux but doesn’t want to memorize the Hundred Mandatory Commands and Thousand Flags lest they accidentally cat > /dev/sda, why shouldn’t there be a system for them?
The community abhors change. Especially changes that break conventions, even informal ones. Look at the temper tantrums people are throwing because Wayland does things differently from X.org. Changing output redirection in Bash, or how dd works, or any number of long-standing conventions because new users are unwilling to adapt to a new system and might end up dding over the root partition would break established workflows, and worse, existing scripts and services.
But the solution already exists, it’s called wrapper programs. You don’t have to manually update AUR packages because yay and paru already do that. You don’t have to figure out how fdisk and mkfs work because Gparted and Partition Manager do it for you.
Nevertheless, using a system should always and forever be the user’s responsibility. Otherwise Linux would turn into a locked-down play pen like Apple products.
The idea that manuals in linux are a good way to learn and understand new software is peak linux neckbeard bs, and I will die on this hill. I congratulate OP on the exact type of autism that lets them feel this is an effective and useful method for learning new software, but if there is desire to have a greater adoption of linux maybe its bad to be snarky at folks for not instantly understand the terminal based documentation conventions of some dudes in the 70s. Maybe an alphabetical* list of all possible options is okay for referencing or searching, but is objectively insane way to learn or understand a problem.
THIS. I feel like linux
manpages are as useful as an Analytical mechanics textbook for someone who just wants to drive. Like yes, sure, it’s amazing we have such a detailed documentation but for God’s sake just introduce basic usages firstas a professional sociotechnical problem solver I will join you on this fatal hill
like take the 4 types of documentation in diátaxis
manpages usually fulfill the reference need, and sometimes kind of that of how-to guides if you’re lucky and your localmanhas examplesbut that leaves more than 50% of documentation needs lacking
and discoverability is atrocious – you have to already know that the command (or commands) you need exists and what it’s called
one of the most useful things I learned in a linux sysadmin course was
apropos/man -k, which lets you search installedmanpages by keyword. but hardly anyone else seems to know about it – I only learned of it because a teaching assistant mentioned it off hand! – and even then it only helps if you guess the right keyword for your problemI am vexed by this situation
People don’t know about man -k because of all the man pages they should have read, they forgot the man one.
ssh [admin@]192.168.1.1 ssh: Could not resolve hostname ]192.168.1.1: No address associated with hostnameThat’s how I would interpret that part of the man page had I no familiarity with ssh. It doesn’t seem reasonable to expect the reader to know what those brackets mean.
You get to learn the notation conventions with <> and [] fairly early on. Maybe a very new user would make that mistake. If he doesn’t get it fairly quick, maybe computers aren’t for him.
Nah m8, I’m generally on board with asking people to read the manual, but these unexplained conventions are nonsense. Pages really should be explicit about notation being added to commands that aren’t actually a part of them
They’re explained right at the beginning of the manpage.
The man manpage. I’m sure it was the first one you read? Because you wanted to know how man worked?
Sure, but that is very far from obvious, and very few people who don’t already have an understanding of this stuff are going to know to look there. When I search for how to do something on the internet I mostly find 2 kinds of sources: stuff that’s way dumbed down (and usually out of date/incorrect) and stuff full of unexplained notation/abbreviations/arbitrary conventions without any links to resources that explain them.
I guess my issue with the man pages is mostly that they just don’t try to be approachable to the not-so-tech-litterate folk who might be interested in Linux if we had resources that didn’t assume all this foreknowledge.
BS. I’ve been using linux for over 20 years and I still don’t know what those mean. I can only guess from context. It’s a stupid convention to just use symbols like that and never explain it.
Read the man manpage and all will be revealed.
Following the openbsd example from the original comment I replied to, it has absolutely nothing to say about what brackets mean, so this advice would not be helpful for an openbsd system: https://man.openbsd.org/man
On my personal linux system (arch derivative, by the way), it at least mentions brackets meaning optional, but only in the context of arguments:
I think this would trip up some new users. The destination, with or without the username to connect as, may not seem like an “argument” to a new user since it doesn’t have a dash before it like the example does
This mentality suuucckkss
It’s a good thing there are other resources, then. You can read tldr-pages. You can look at various official and unofficial wikis. You can look at Stackoverflow. You can look at Youtube tutorials. You can ask other people. Hell, you can ask a chatbot.
If the average user is unwilling to do that, maybe it’s better that Linux does not see a wider adoption.
is the fact that people can with effort and error figure out how to do something a reason not to make it easier for them to do?
I mean
you can in theory write multi-threaded bug-free C code – just read the docs and the specs and the source of your libs and never ever do something that seems to work but is subtly fatally incorrect
and yet we still have golang and rust and many other options to do things more safely and easily
if someone wants to use Linux but doesn’t want to memorize the Hundred Mandatory Commands and Thousand Flags lest they accidentally
cat > /dev/sda, why shouldn’t there be a system for them?The community abhors change. Especially changes that break conventions, even informal ones. Look at the temper tantrums people are throwing because Wayland does things differently from X.org. Changing output redirection in Bash, or how
ddworks, or any number of long-standing conventions because new users are unwilling to adapt to a new system and might end updding over the root partition would break established workflows, and worse, existing scripts and services.But the solution already exists, it’s called wrapper programs. You don’t have to manually update AUR packages because
yayandparualready do that. You don’t have to figure out howfdiskandmkfswork because Gparted and Partition Manager do it for you.Nevertheless, using a system should always and forever be the user’s responsibility. Otherwise Linux would turn into a locked-down play pen like Apple products.