9 ms·

"An enormous page full of switches and options, yet if you're a beginner it's basically useless." Maybe 30 years ago you could learn through manpages but today

by jerf 3y ago

"An enormous page full of switches and options, yet if you're a beginner it's basically useless." Maybe 30 years ago you could learn through manpages but today that's how all the man pages of all the useful commands look. If you think grep is nice it would be the exception; for me it is indeed short, simple and easily searchable, but too terse for a beginner to learn with easily. (Plus even the regex documentation only documents grep mode, not egrep or pgrep or anything else.) Very useful in its own way, but most man pages are useless for learning. I am disappointed at how few man pages take the opportunity to have a useful selection of "the 10 most popular things to do with this command" but web search has filled in reasonably decently. You do still have to understand the basics of how shell works, though, because most of them aren't quite what you want today and honestly a fair number of them aren't even what the poster thought they were. I am also in the habit of making sure that I understand every command line switch before I copy & paste a command off the internet, again, because many of them aren't what you need today. I don't always mean in a malicious manner, but things like either do or do not follow HTTP redirects in curl may or may not matter to you today, but the poster may be in the habit of setting it one way or another for no reason relevant to you.

markus_zhang 3y ago
Yeah man! Scenarios! Those documentations rarely bother with scenarios, which is all newbies need!
- fsckboy 3y ago
  within a magpage that section is called EXAMPLES there are not enough of them now, they used to be more prevalent
  - markus_zhang 3y ago
    Yeah some have examples but many don't. I think maybr that's not the purpose of manpages though, more suitable for a cookbook.
shrimp_emoji 3y ago
Man pages are pre-Internet Age help StackOverflow is Internet Age help ChatGPT is post-Internet Age help In ascending order of helpfulness (modulo LLM confabulation)
- ilyt 3y ago
  And in descending order of correctness. ChatGPT inherited "confidently wrong" and "misunderstanding question and then answering to question they misunderstood" from stackoverflow
  - charlieflowers 3y ago
    I wonder if chatgpt will start “closing” questions as “not a good fit for its Q&A format,” or “too opinionated,” or “a duplicate” of something that is acutely unrelated. Actually, this seems to be a case where chatgpt is smarter than the humans.
- bombcar 3y ago
  ChatGPT will not be able to hallucinate options to find and grep and ls because they all use every single letter of the alphabet.
- xg15 3y ago
  > (modulo LLM confabulation) As of now, there is no LLM without confabulation, so your third item is effectively "hypothetical fantasy ChatGPT that we hope will be available some time in the future", not the actual tools we have right now.
- manmal 3y ago
  A recent example: I used ChatGPT 4 to draft an mkvmerge command - take 2 video files, and merge them by only copying certain audio and subtitle tracks from the second file into the first file. The resulting command looked good at first sight, something like „mkvmerge -o output.mkv first.mkv —-no—video -s 1 -a 2 -a 3 -a 4“. The problem here is that there can only be one -a flag, so it should have been „-a 2,3,4“ instead. But mkvmerge didn’t really care and just discarded every -a flag except the last one. So I ended up with only one of the audio tracks copied over. I only noticed when I actually checked the resulting file that it had less audio tracks than it was supposed to. This would not have happened to a human after studying the man page - the documentation is very clear about the -a flag and I have no idea what led ChatGPT to come to the conclusion it did.
libele 3y ago
the openbsd manuals usually have examples. you can see how compact https://man.openbsd.org/grep.1 https://man.openbsd.org/grep.1 is compared to the gnu grep manual. i've been using https://git.causal.agency/exman/about/ https://git.causal.agency/exman/about/ to compare linux and bsd manpages, and it has saved me an incredible amount of time looking things up.
- fsckboy 3y ago
  perhaps gnu's manpages suffer because they focused so much effort on their info pages.
  - Cockbrand 3y ago
    Are info pages still a thing? I remember being very confused by them back when I started out with Linux, and eventually just stopped trying to understand how they worked.
    - drbaba 3y ago
      They are, but my impression is that only Emacs users use them to some extent. (Emacs has a built-in info reader that is better than the standalone client, and ships mainly info pages as its documentation.) Outside of Emacs, I’d say very few people know info is even a thing, and I remember some Linux distributions also stripped info pages from packages since everyone used man pages.
      - anthk 3y ago
        More than better, people doesn't know how to use GNU Info correctly.
        JdeBP 3y ago
        In fairness, if one were to come to more, pg, or less with no prior knowledge of the conventions, the madness of some of the character choices would be just as grating. Ironically, this sort of stuff -- the basic conventions like qhjkl0^$G + CRFFBSSPC keyboard navigation and :/? prompt modes -- is exactly what one initially learns from guides, tutorials, other people in IRC, and whatnot, long before coming to reference doco. The _Introduction to Linux_ book at TLDP covers the bare essentials of these conventions, q, b, and SPC, in the "quickstart" chapter 2. * https://tldp.org/LDP/intro-linux/html/sect_02_03.html https://tldp.org/LDP/intro-linux/html/sect_02_03.html
robohoe 3y ago
tealdear and tldr seems to do "top 10 most useful things you can do with this command"
jbm 3y ago
I remember offering to make a PR w/ examples for something when I was a junior dev and was politely told that they didn't want examples. I assumed - and still assume - that this was a generational difference in what people expected competence to look like. While this attitude made sense pre-internet, reading about every switch for common use cases is just not realistic today. Maybe if the number of command-line programs were less, and the complexity of each command was significantly less, I could see how it would be done, but not today.

by jerf 3y ago

markus_zhang 3y ago

Yeah man! Scenarios! Those documentations rarely bother with scenarios, which is all newbies need!

fsckboy 3y ago
within a magpage that section is called EXAMPLES there are not enough of them now, they used to be more prevalent
- markus_zhang 3y ago
  Yeah some have examples but many don't. I think maybr that's not the purpose of manpages though, more suitable for a cookbook.

shrimp_emoji 3y ago

Man pages are pre-Internet Age help StackOverflow is Internet Age help ChatGPT is post-Internet Age help In ascending order of helpfulness (modulo LLM confabulation)

ilyt 3y ago
And in descending order of correctness. ChatGPT inherited "confidently wrong" and "misunderstanding question and then answering to question they misunderstood" from stackoverflow
- charlieflowers 3y ago
  I wonder if chatgpt will start “closing” questions as “not a good fit for its Q&A format,” or “too opinionated,” or “a duplicate” of something that is acutely unrelated. Actually, this seems to be a case where chatgpt is smarter than the humans.
bombcar 3y ago
ChatGPT will not be able to hallucinate options to find and grep and ls because they all use every single letter of the alphabet.
xg15 3y ago
> (modulo LLM confabulation) As of now, there is no LLM without confabulation, so your third item is effectively "hypothetical fantasy ChatGPT that we hope will be available some time in the future", not the actual tools we have right now.
manmal 3y ago
A recent example: I used ChatGPT 4 to draft an mkvmerge command - take 2 video files, and merge them by only copying certain audio and subtitle tracks from the second file into the first file. The resulting command looked good at first sight, something like „mkvmerge -o output.mkv first.mkv —-no—video -s 1 -a 2 -a 3 -a 4“. The problem here is that there can only be one -a flag, so it should have been „-a 2,3,4“ instead. But mkvmerge didn’t really care and just discarded every -a flag except the last one. So I ended up with only one of the audio tracks copied over. I only noticed when I actually checked the resulting file that it had less audio tracks than it was supposed to. This would not have happened to a human after studying the man page - the documentation is very clear about the -a flag and I have no idea what led ChatGPT to come to the conclusion it did.

libele 3y ago

the openbsd manuals usually have examples. you can see how compact https://man.openbsd.org/grep.1 https://man.openbsd.org/grep.1 is compared to the gnu grep manual. i've been using https://git.causal.agency/exman/about/ https://git.causal.agency/exman/about/ to compare linux and bsd manpages, and it has saved me an incredible amount of time looking things up.

fsckboy 3y ago
perhaps gnu's manpages suffer because they focused so much effort on their info pages.
- Cockbrand 3y ago
  Are info pages still a thing? I remember being very confused by them back when I started out with Linux, and eventually just stopped trying to understand how they worked.
  - drbaba 3y ago
    They are, but my impression is that only Emacs users use them to some extent. (Emacs has a built-in info reader that is better than the standalone client, and ships mainly info pages as its documentation.) Outside of Emacs, I’d say very few people know info is even a thing, and I remember some Linux distributions also stripped info pages from packages since everyone used man pages.
    - anthk 3y ago
      More than better, people doesn't know how to use GNU Info correctly.
      - JdeBP 3y ago
        In fairness, if one were to come to more, pg, or less with no prior knowledge of the conventions, the madness of some of the character choices would be just as grating. Ironically, this sort of stuff -- the basic conventions like qhjkl0^$G + CRFFBSSPC keyboard navigation and :/? prompt modes -- is exactly what one initially learns from guides, tutorials, other people in IRC, and whatnot, long before coming to reference doco. The _Introduction to Linux_ book at TLDP covers the bare essentials of these conventions, q, b, and SPC, in the "quickstart" chapter 2. * https://tldp.org/LDP/intro-linux/html/sect_02_03.html https://tldp.org/LDP/intro-linux/html/sect_02_03.html

robohoe 3y ago

tealdear and tldr seems to do "top 10 most useful things you can do with this command"

jbm 3y ago

I remember offering to make a PR w/ examples for something when I was a junior dev and was politely told that they didn't want examples. I assumed - and still assume - that this was a generational difference in what people expected competence to look like. While this attitude made sense pre-internet, reading about every switch for common use cases is just not realistic today. Maybe if the number of command-line programs were less, and the complexity of each command was significantly less, I could see how it would be done, but not today.