5 ms·

You're right. I often think the man page should begin with a few examples, then launch into the neverending list of options. That is no way to learn. In foreig

You're right. I often think the man page should begin with a few examples, then launch into the neverending list of options. That is no way to learn. In foreign language 101, they start you off with a small group of examples. "Como estas?" "Muy bien. Y tu?" Afterward, they explain the rules of the language (this is a noun, this is a verb, this is how you conjugate for first-person singular, etc.). In fact, this is how we learn our first language as babies. Anyone remember Mom and Dad pulling out a flip chart? Or did they just talk to you a lot? The same goes with apprenticeships, I would think. The blacksmith starts the apprentice with simple tasks around the shop. I suppose he would intersperse it with the occasional pontification about principles and theory, but he would not sit down the pupil for weeks explaining everything before just letting him get his hands dirty. The Linux man pages are upside down. Examples don't come till the very end, if at all. Thankfully, like you said, there is now Stack Overflow.

ddevault 6y ago
>The Linux man pages are upside down. Examples don't come till the very end, if at all. You only learn the tool once. Every subsequent time you visit the man page, the information you're probably looking for is frontloaded. Just scroll to the bottom if you want examples?
- combatentropy 6y ago
  Fair points. After all, I know the keyboard shortcut to jump to the bottom (Ctrl-G).
  - teddyh 6y ago
    According to less(1), the key is: “G or > or ESC->”.
    - combatentropy 6y ago
      Sorry, I meant Shift-G. I can no longer edit that comment.
      - coliveira 6y ago
        In most keyboards Shift-G is the same as G, otherwise it would be g.
        combatentropy 6y ago
        Ha ha, you're right, in a way. It depends on whether you take G to mean the figure on the keyboard or the figure on the screen. The figure on most keyboards is G. Yet when you press it, it puts on the screen, g. Chromebooks are better in this way. Their keyboards are labeled in lowercase. I actually went back and forth between saying Shift-G, or just G, for this very reason. So I erred on the side of clarity.
        Reelin 6y ago
        I thought the way you wrote it was clear but these comments got me curious what the various conventions might be so I took a quick look at :help in Vim (since it lists an awful lot of key bindings). I'm now officially confused and don't think you can go too far wrong. In some contexts :help notates things as characters (ex zh, zH, and z<CR>). In other cases I'm seeing things written as <S-F11> and <C-G>. There's also CTRL-H (instead of <C-H>) but I'm not seeing shift written out like that for whatever reason. Sometimes they get mixed (I'm not sure what the rules are) such as for hh<Space> and hh<C-]>. Amusingly enough, :help appears to treat Meta-{char} as case sensitive but CTRL-{char} as case insensitive (I assume there's a reason). I also spotted a <kPlus> (for the keypad). What an amusingly pointless distraction!
    - devenblake 6y ago
      You can also use the key on many keyboards labeled "End".
- oblio 6y ago
  > You only learn the tool once. Every subsequent time you visit the man page, the information you're probably looking for is frontloaded. Just scroll to the bottom if you want examples? This is false for most tools we don't use daily. It's false even for tools we do use daily, in some cases (I have to google git commands every month or so for commands I use rarely). Most people are and remain perpetual intermediates: https://blog.codinghorror.com/defending-perpetual-intermediacy/ https://blog.codinghorror.com/defending-perpetual-intermedia... The experts are the exception.
  - sixstringtheory 6y ago
    I bristled just now at the opportunity to have my first strong disagreement with Mr. Spolsky. Then I read the article you linked. I don’t think it means what you think it means. He’s talking about users of the software, not developers. And I know, I know, developers are users of software too, perhaps more than the average user. But then he links to this article about homo logicus [0] in which he begins: > Of all the professional hubris I've observed in software developers, perhaps the greatest sin of all is that we consider ourselves typical users. > We are experts. Who could possibly design software better than us superusers? What most developers don't realize is how freakishly outside the norm we are. We're not even remotely average-- we are the edge conditions. Honestly, if you’re a hobbyist or moonlight as a FOSS contributor, fine, nbd. But if I found out an alleged professional working for me writing software was content to never figure something out like a git branch issue in the short term and grow over the long term in their total skillsets, I’d want them gone. I wouldn’t want a lazy, mediocre carpenter to build my house either. I’m perfectly content to let them build a ramshackle residence for themself where nobody has to suffer because of it. [0]: https://blog.codinghorror.com/the-rise-and-fall-of-homo-logicus/ https://blog.codinghorror.com/the-rise-and-fall-of-homo-logi...
    - deleted 6y ago
      [deleted]
    - oblio 6y ago
      > I wouldn’t want a lazy, mediocre carpenter to build my house either. I’m perfectly content to let them build a ramshackle residence for themselves where nobody has to suffer because of it. This is kind of funny since I'm European and we view most US houses as low quality McMansions :-))
- porknubbins 6y ago
  I always thought someday I would become a hardcore Linux hacker and know all the commands and flags but the reality is I have to relearn every time. Who spends that much time just in the command line these days? I’m sure some people do but I don’t know what they do unless its CTFs or security related.
  - viraptor 6y ago
    Devops-style workload means a lot of the time spent in the console. Even then, I lookup the quoting difference between $* and $@ every single time, and how to use `read`. Or more likely decide it's time to drop bash at that point...
    - GoblinSlayer 6y ago
      docker save | xz is about the longest pipeline I used, and since compression doesn't provide any meaningful advantage there (except for maybe checksum), I reduced it to just docker save.
  - saagarjha 6y ago
    I’m not sure why you think CTFs/security has an extra focus on the command line? Most of the security people I know spend their days staring into IDA…
    - Ekaros 6y ago
      As security person I run stuff in command line as many tools are there and they really are mostly scripts. I don't really need to do much shell magic to do stuff. If I actually need something special I will write a python script.
  - Reelin 6y ago
    > Who spends that much time just in the command line these days? Just stop using GUI utilities. It really is that simple. If you just don't use them you'll end up in a shell out of necessity because you still need to get things done. Of course, the majority of my time is spent in my web browser reading documentation followed closely by vim for writing things. Actual time spent interacting with CLIs is a small minority at the end of the day.
- GoblinSlayer 6y ago
  It takes a long time to scroll to the bottom of bash man page.
andi999 6y ago
In my hazy memory, the examples were somehow all about not the use case I was interested in.
divbzero 6y ago
> The Linux man pages are upside down. Examples don't come till the very end, if at all. man pages are meant to be a full reference, not a quick tutorial. To get the quick tutorial others have already mentioned cheat.sh [1] and tldr pages [2] is another good resource. [1]: https://cheat.sh/ https://cheat.sh/ [2]: https://tldr.sh/ https://tldr.sh/
- keyle 6y ago
  +1 for tldr.sh. It's fantastic, I use it all the time, sometimes randomly for stuff I haven't got installed to find out whether I should homebrew it or not. Unlike man pages, tldr can search and find docs for stuff you don't currently have installed. And it's fun to read. It's how man pages should be written, at least have a tl;dr before boring you to death.
- jai_ 6y ago
  They can still be both! You can flip the general structure of man pages to be examples first while still having all the complete reference material after.
  - thotsBgone 6y ago
    Or just use tldr, which already does what you want.
  - arp242 6y ago
    The downside of that is that searching for something would mean I'd first get the examples, and then the reference.
- vram22 6y ago
  > man pages are meant to be a full reference, not a quick tutorial. Yes, and for both quick and longer tutorials, there are also these things called books and courses - both of which are available in hard copy / offline as well as soft copy / online versions from many years now :) Many of us grew up using them and investing in them for our careers ...
- bostonvaulter2 6y ago
deleted 6y ago
[deleted]
nvrspyx 6y ago
I've really come to appreciate PowerShell exactly for the "-Examples" argument for Get-Help (or help/man alias). Although I still prefer a POSIX shell, I've been messing around with PowerShell and quite enjoy it.
jancsika 6y ago
> Thankfully, like you said, there is now Stack Overflow. It's interesting because we can imagine a history where the docs were written much more professionally with such examples. And we can imagine that work having lowered the barrier to entry such that a critical mass of users becoming compositionally literate in shell scripting. (And perhaps shellcheck being written much earlier in this alternate history.) But Stack Overflow not only obsoletes such an effort, it IMO obsoletes becoming literate in shell scripting, at least in the way the author describes. SO's existence is equivalent to being able to write a natural language query on the command line which "automorphs" into the relevant Stack Overflow example. At that point you just need to understand basic piping, redirection, and enough of the syntax to spot-check the magic answer in order to make small changes for a use case. That's a different kind of skill.

ddevault 6y ago

>The Linux man pages are upside down. Examples don't come till the very end, if at all. You only learn the tool once. Every subsequent time you visit the man page, the information you're probably looking for is frontloaded. Just scroll to the bottom if you want examples?

combatentropy 6y ago
Fair points. After all, I know the keyboard shortcut to jump to the bottom (Ctrl-G).
- teddyh 6y ago
  According to less(1), the key is: “G or > or ESC->”.
  - combatentropy 6y ago
    Sorry, I meant Shift-G. I can no longer edit that comment.
    - coliveira 6y ago
      In most keyboards Shift-G is the same as G, otherwise it would be g.
      - combatentropy 6y ago
        Ha ha, you're right, in a way. It depends on whether you take G to mean the figure on the keyboard or the figure on the screen. The figure on most keyboards is G. Yet when you press it, it puts on the screen, g. Chromebooks are better in this way. Their keyboards are labeled in lowercase. I actually went back and forth between saying Shift-G, or just G, for this very reason. So I erred on the side of clarity.
        Reelin 6y ago
        I thought the way you wrote it was clear but these comments got me curious what the various conventions might be so I took a quick look at :help in Vim (since it lists an awful lot of key bindings). I'm now officially confused and don't think you can go too far wrong. In some contexts :help notates things as characters (ex zh, zH, and z<CR>). In other cases I'm seeing things written as <S-F11> and <C-G>. There's also CTRL-H (instead of <C-H>) but I'm not seeing shift written out like that for whatever reason. Sometimes they get mixed (I'm not sure what the rules are) such as for hh<Space> and hh<C-]>. Amusingly enough, :help appears to treat Meta-{char} as case sensitive but CTRL-{char} as case insensitive (I assume there's a reason). I also spotted a <kPlus> (for the keypad). What an amusingly pointless distraction!
  - devenblake 6y ago
    You can also use the key on many keyboards labeled "End".
oblio 6y ago
> You only learn the tool once. Every subsequent time you visit the man page, the information you're probably looking for is frontloaded. Just scroll to the bottom if you want examples? This is false for most tools we don't use daily. It's false even for tools we do use daily, in some cases (I have to google git commands every month or so for commands I use rarely). Most people are and remain perpetual intermediates: https://blog.codinghorror.com/defending-perpetual-intermediacy/ https://blog.codinghorror.com/defending-perpetual-intermedia... The experts are the exception.
- sixstringtheory 6y ago
  I bristled just now at the opportunity to have my first strong disagreement with Mr. Spolsky. Then I read the article you linked. I don’t think it means what you think it means. He’s talking about users of the software, not developers. And I know, I know, developers are users of software too, perhaps more than the average user. But then he links to this article about homo logicus [0] in which he begins: > Of all the professional hubris I've observed in software developers, perhaps the greatest sin of all is that we consider ourselves typical users. > We are experts. Who could possibly design software better than us superusers? What most developers don't realize is how freakishly outside the norm we are. We're not even remotely average-- we are the edge conditions. Honestly, if you’re a hobbyist or moonlight as a FOSS contributor, fine, nbd. But if I found out an alleged professional working for me writing software was content to never figure something out like a git branch issue in the short term and grow over the long term in their total skillsets, I’d want them gone. I wouldn’t want a lazy, mediocre carpenter to build my house either. I’m perfectly content to let them build a ramshackle residence for themself where nobody has to suffer because of it. [0]: https://blog.codinghorror.com/the-rise-and-fall-of-homo-logicus/ https://blog.codinghorror.com/the-rise-and-fall-of-homo-logi...
  - deleted 6y ago
    [deleted]
  - oblio 6y ago
    > I wouldn’t want a lazy, mediocre carpenter to build my house either. I’m perfectly content to let them build a ramshackle residence for themselves where nobody has to suffer because of it. This is kind of funny since I'm European and we view most US houses as low quality McMansions :-))
porknubbins 6y ago
I always thought someday I would become a hardcore Linux hacker and know all the commands and flags but the reality is I have to relearn every time. Who spends that much time just in the command line these days? I’m sure some people do but I don’t know what they do unless its CTFs or security related.
- viraptor 6y ago
  Devops-style workload means a lot of the time spent in the console. Even then, I lookup the quoting difference between $* and $@ every single time, and how to use `read`. Or more likely decide it's time to drop bash at that point...
  - GoblinSlayer 6y ago
    docker save | xz is about the longest pipeline I used, and since compression doesn't provide any meaningful advantage there (except for maybe checksum), I reduced it to just docker save.
- saagarjha 6y ago
  I’m not sure why you think CTFs/security has an extra focus on the command line? Most of the security people I know spend their days staring into IDA…
  - Ekaros 6y ago
    As security person I run stuff in command line as many tools are there and they really are mostly scripts. I don't really need to do much shell magic to do stuff. If I actually need something special I will write a python script.
- Reelin 6y ago
  > Who spends that much time just in the command line these days? Just stop using GUI utilities. It really is that simple. If you just don't use them you'll end up in a shell out of necessity because you still need to get things done. Of course, the majority of my time is spent in my web browser reading documentation followed closely by vim for writing things. Actual time spent interacting with CLIs is a small minority at the end of the day.
GoblinSlayer 6y ago
It takes a long time to scroll to the bottom of bash man page.

andi999 6y ago

In my hazy memory, the examples were somehow all about not the use case I was interested in.

divbzero 6y ago

> The Linux man pages are upside down. Examples don't come till the very end, if at all. man pages are meant to be a full reference, not a quick tutorial. To get the quick tutorial others have already mentioned cheat.sh [1] and tldr pages [2] is another good resource. [1]: https://cheat.sh/ https://cheat.sh/ [2]: https://tldr.sh/ https://tldr.sh/

keyle 6y ago
+1 for tldr.sh. It's fantastic, I use it all the time, sometimes randomly for stuff I haven't got installed to find out whether I should homebrew it or not. Unlike man pages, tldr can search and find docs for stuff you don't currently have installed. And it's fun to read. It's how man pages should be written, at least have a tl;dr before boring you to death.
jai_ 6y ago
They can still be both! You can flip the general structure of man pages to be examples first while still having all the complete reference material after.
- thotsBgone 6y ago
  Or just use tldr, which already does what you want.
- arp242 6y ago
  The downside of that is that searching for something would mean I'd first get the examples, and then the reference.
vram22 6y ago
> man pages are meant to be a full reference, not a quick tutorial. Yes, and for both quick and longer tutorials, there are also these things called books and courses - both of which are available in hard copy / offline as well as soft copy / online versions from many years now :) Many of us grew up using them and investing in them for our careers ...
bostonvaulter2 6y ago

deleted 6y ago

[deleted]

nvrspyx 6y ago

I've really come to appreciate PowerShell exactly for the "-Examples" argument for Get-Help (or help/man alias). Although I still prefer a POSIX shell, I've been messing around with PowerShell and quite enjoy it.

jancsika 6y ago

> Thankfully, like you said, there is now Stack Overflow. It's interesting because we can imagine a history where the docs were written much more professionally with such examples. And we can imagine that work having lowered the barrier to entry such that a critical mass of users becoming compositionally literate in shell scripting. (And perhaps shellcheck being written much earlier in this alternate history.) But Stack Overflow not only obsoletes such an effort, it IMO obsoletes becoming literate in shell scripting, at least in the way the author describes. SO's existence is equivalent to being able to write a natural language query on the command line which "automorphs" into the relevant Stack Overflow example. At that point you just need to understand basic piping, redirection, and enough of the syntax to spot-check the magic answer in order to make small changes for a use case. That's a different kind of skill.