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.
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
hard agree
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.