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.
You might be thinking of info pages. The man pages are just the instructions, feature flags, etc. generally, while info (when available) usually has a more general / layman description of the command with examples.
There’s other ways to get info. And man pages are a great way to learn how something is expected to work on your system. And it’s offline, without ads, scams, ai generated false info.
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.
Agreed! You can look elsewhere, and that’s how I, and I think many other folks, learned. The OP was talking about the manuals though, specifically mentioning /usr/bin. So to restate my point is not to say it’s impossible to learn linux, but that man pages are weird and bad place to push folks looking to learn.
initially when I was learning linux. I had troubles finding the command I needed. I could have first gone and read everything and then come back to try, which I did. But sometimes the man pages, the ubuntu and arch forums weren’t as great of a help as messing up myself.
Could there be a better way to document with slightly more examples: yes. Would it help: tons
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.
Agreed, and I think a larger part of it is that most folks pick it up based on context after long enough, so it’s rarely explained. The square brackets are optional arguments. So I could use ssh 192.168.1.1 or ssh postimo@192.168.1.1 with the first asking for the account after I connect, and the second just asking for the password. You can see how the computer took it in the response you got. hostname ]192.168.1.1 being it saw the @ and assumed everything after was the hostname and included the ]
It’s worth noting that you can’t just connect to a random machine like this, they need to also be running an ssh server. But I wouldn’t expect you to know that without reading a great deal more of the documentation 🫠
I’ve been using ssh for decades, you don’t have to explain it to me. It was a purely contrived example to simulate what I think a new user might experience if faced with that particular man page as their only documentation.
Oh my mistake, I didn’t mean to demean at all. Yeah I think even in your example there are baked in knowledge we’ve picked up that we don’t realize, and that a very likely response from fully fresh eyes would seeing the synopsis is “oh this isn’t for me.”
No worries, didn’t feel demeaned but wanted to be clear that it was an attempt to try to ignore ~23 years of ssh muscle memory to try to guess what might trip up a new Linux user
Very much true in my case - I couldn’t explain what the, like… “idiomatic” meaning of those brackets is, I only guess from context and experience, and it remains a minor peeve of mine that such symbology is widely used but rarely explained
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.
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.
That’s a fair point. Their problem is that they both have to be relatively concise and as exhaustive as possible, which makes it difficult to be user friendly. So the style is usually terse and more friendly to seasoned users than to the new ones.
I think beginning users would do well to invest in something like an introductory ORiley book rather than rely on the often highly dubious online stuff. I’ve seen so many absolutely atrocious “Linux for beginners” pages that I really wouldn’t recommend any.
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
this advice would not be helpful for an openbsd system
Sorry, I wasn’t aware of that. BSD usually has excellent pan man pages.
Here’s the relevant section in the Linux one:
The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections.
**bold text** type exactly as shown.
*italic text* replace with appropriate argument.
[-abc] any or all arguments within [ ] are optional.
-a|-b options delimited by | cannot be used together.
argument ... argument is repeatable.
[expression] ... entire expression within [ ] is repeatable.
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
Then the new user should real the ssh manpage which very clearly specifies that it is.
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
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.
deleted by creator
You might be thinking of
infopages. Themanpages are just the instructions, feature flags, etc. generally, whileinfo(when available) usually has a more general / layman description of the command with examples.deleted by creator
It’s possible. A lot of things merge the info and man pages now if both are installed, that could be the case here. Or Mac just documents it further.
There’s other ways to get info. And man pages are a great way to learn how something is expected to work on your system. And it’s offline, without ads, scams, ai generated false info.
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.
Agreed! You can look elsewhere, and that’s how I, and I think many other folks, learned. The OP was talking about the manuals though, specifically mentioning
/usr/bin. So to restate my point is not to say it’s impossible to learn linux, but that man pages are weird and bad place to push folks looking to learn.“No John, you are the neckbeards!”
I use the neckbeard to destroy the neckbeard
initially when I was learning linux. I had troubles finding the command I needed. I could have first gone and read everything and then come back to try, which I did. But sometimes the man pages, the ubuntu and arch forums weren’t as great of a help as messing up myself.
Could there be a better way to document with slightly more examples: yes. Would it help: tons
But this is just my opinion, and I am just a noob
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.
Agreed, and I think a larger part of it is that most folks pick it up based on context after long enough, so it’s rarely explained. The square brackets are optional arguments. So I could use
ssh 192.168.1.1orssh postimo@192.168.1.1with the first asking for the account after I connect, and the second just asking for the password. You can see how the computer took it in the response you got.hostname ]192.168.1.1being it saw the@and assumed everything after was the hostname and included the ]It’s worth noting that you can’t just connect to a random machine like this, they need to also be running an ssh server. But I wouldn’t expect you to know that without reading a great deal more of the documentation 🫠
I’ve been using ssh for decades, you don’t have to explain it to me. It was a purely contrived example to simulate what I think a new user might experience if faced with that particular man page as their only documentation.
Oh my mistake, I didn’t mean to demean at all. Yeah I think even in your example there are baked in knowledge we’ve picked up that we don’t realize, and that a very likely response from fully fresh eyes would seeing the synopsis is “oh this isn’t for me.”
No worries, didn’t feel demeaned but wanted to be clear that it was an attempt to try to ignore ~23 years of ssh muscle memory to try to guess what might trip up a new Linux user
Very much true in my case - I couldn’t explain what the, like… “idiomatic” meaning of those brackets is, I only guess from context and experience, and it remains a minor peeve of mine that such symbology is widely used but rarely explained
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.
That’s a fair point. Their problem is that they both have to be relatively concise and as exhaustive as possible, which makes it difficult to be user friendly. So the style is usually terse and more friendly to seasoned users than to the new ones.
I think beginning users would do well to invest in something like an introductory ORiley book rather than rely on the often highly dubious online stuff. I’ve seen so many absolutely atrocious “Linux for beginners” pages that I really wouldn’t recommend any.
This mentality suuucckkss
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
Sorry, I wasn’t aware of that. BSD usually has excellent
panman pages.Here’s the relevant section in the Linux one:
The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections. **bold text** type exactly as shown. *italic text* replace with appropriate argument. [-abc] any or all arguments within [ ] are optional. -a|-b options delimited by | cannot be used together. argument ... argument is repeatable. [expression] ... entire expression within [ ] is repeatable.Then the new user should real the ssh manpage which very clearly specifies that it is.
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 first