Hacker News Reader

Comment by jancsika | Hacker News Reader

I can just never get past the arg/flag inconsistency/complexity across commands. Perhaps if the docs started with a simple example of what has been seen over time to be the most common incantation for each command it might be tolerable. But as it is, I spend more time dealing with idiosyncracies of a command than I do expressively piping stuff.

Perhaps if Rust had five mutually incompatible borrow-checkers which get called based on who wrote the code for a particular language construction-- that might get across the frustration I feel when using the shell. (Well, honestly I just StackOverflow for the shell incantation I need and that seems to work well enough.)

View on HN

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.

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.

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

> 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/

[2]: https://tldr.sh/

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.

The downside of that is that searching for something would mean I'd first get the examples, and then the reference.

Or just use tldr, which already does what you want.

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

+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.

Big +1 for tldr from me. And the commands are effectively a wiki (or maybe it's stored in git). Anyway you can contribute to them.

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

>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?

> 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-intermedia...

The experts are the exception.

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-logi...

> 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 :-))

If the carpenter does everything correctly I don't care if he doesn't keep everything in memory.

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.

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

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.

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

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…

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.

Fair points. After all, I know the keyboard shortcut to jump to the bottom (Ctrl-G).

According to less(1), the key is: “G or > or ESC->”.

You can also use the key on many keyboards labeled "End".

Sorry, I meant Shift-G. I can no longer edit that comment.

In most keyboards Shift-G is the same as G, otherwise it would be g.

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.

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!

It takes a long time to scroll to the bottom of bash man page.

> Perhaps if the docs started with a simple example of what has been seen over time to be the most common incantation for each command it might be tolerable.

You might enjoy https://cheat.sh which is usable via curl: `curl cheat.sh/grep`

Very impressive. I just made a function 'cheat' that takes a command name as input and curls this website. Thanks.

Thanks for sharing, that’s a great tool.

Using Fish as my shell somewhat makes this morn tolerable as it checks the manpages and automatically suggests flags in a tab-complete fashion. It also remembers previously run commands and suggests them, which helps with not having to remember exactly which flag does what, because the example comes from the last time you ran the command.

This is why I use PowerShell. Menu completion gives me all of the switches with their full name instead of cryptic abbreviations.

Perhaps if Rust had five mutually incompatible borrow-checkers which get called based on who wrote the code for a particular language construction-- that might get across the frustration I feel when using the shell.

You mean like the five mutually incompatible async solutions in rust?

The inconsistency sometimes bothers me too, but it makes me feel a little better to remember that so many of the CLI commands we take for granted are part of an old historical heritage. The inconsistency is part of that heritage--today's CLI wasn't designed all at once by one group, but rather evolved over 50+ years from many contributors, back when nobody expected that people would still be using `sed` in 2020.

For me, reflecting on that history helps dull the annoyance of having to type `grep --extended-regexp` but `sed --regexp-extended`.

(nit)

> `grep --extended-regexp` but `sed --regexp-extended`

Why not use `grep -E` and `sed -E`?

That's what I do on the command line (though I went so far as to just alias `grep` to `grep -E`), but when writing scripts I prefer to use expanded flags for clarity. When going back to a script one wrote a year ago, it's way easier to grok expanded flags instead of a bunch of single letters that have to be re-deciphered. (Especially with something like `grep` or `sed` that have 1,000 flags each.)

> Especially with something like `grep` or `sed` that have 1,000 flags each.

Sometimes I actually read the POSIX man pages instead of the standard ones — they are sometimes more useful because they have fewer features. Sometimes they are less useful because of their verbose language, though.

> more useful because they have fewer features

That’s probably why DuckDuckGo’s `!man man`/manpage.me default to FreeBSD manpages. But if you really want something non-verbose you may prefer tldr.sh, cht.sh, or bro pages.

Hint: if you're still using grep to search files rather than a file, install and start using the "newer generation" of greps (ag, ripgrep etc). You likely won't believe the speed.

I use ag many times a day to search 10,400 files comprising about 800k lines of code, and it is in every meaningful way completely instantaneous. It also understands repository structures, and so won't waste your time there.

It seriously changed my (programming) life.

Integrating rg and fzf into vim changed my programming life. I find that combo pretty incredible and something I haven't found in IntelliJ. I usually find myself switching back to my shell and then back to IntelliJ.

Yes, I probably should have said "use ag in the context of emacs" just to clarify how it gets used.

At least when you go to Stack Overflow or read the man page, if you find an answer, then it is likely to work. In contrast, if you go to Stack Overflow to find out how to do something with a GUI program, there's a good chance that the answer you find is for a different version than you are working with, and does not help at all.

Depends. Are you on macOS?

What is your specific claim here?

macOS tools generally do not match what Stack Overflow tells you.

Ah, yes - I have come across some differences in command-line flags and default behaviors between macOS and the nominally equivalent tools as implemented in Linux or specified by Posix, and sometimes, on Stack Overflow, you will find people answering Mac-specific questions on the Dunning-Krugeresque assumption that it is the same as the others. In general, one should always verify Stack Overflow answers before using, but that often gets you closer to the answer you need than one starting from a scenario that simply isn't available on your version of, say, Xcode.

The same goes for systems derived from BSD - in fact, I wonder if some of the differences between MacOS and Linux comes from the former's origins in Mach/BSD via Nextstep.

> I wonder if some of the differences between MacOS and Linux comes from the former's origins in Mach/BSD via Nextstep.

My understanding was that this is most of it. The problem is relatively basic—macOS uses the BSD versions of most unix tools, which means basic commands like sed sometimes function quite differently!

This is a really big deal.

Almost nothing in computerdom was designed from a developer-centric perspective and it blows my mind.

Maybe I'm 'opposite brained' but it's the first thing that I think about when making something, sometimes at the expensive of the algorithm.

There's a bird in the back of my mind literally every time I use the shell chirping at me to translate them all into something consistent, and then make actually useful manpages for them.

The world is complicated, we have too much to learn, communications and ramp-up are essential and part of the product even if there's genius under the hood. (I'm also looking at you Rust, Git).

I recommend https://tldr.sh/. Since I installed `tldr`, I rarely read the man pages.

> Perhaps if the docs started with a simple example of what has been seen over time to be the most common incantation for each command it might be tolerable.

Rsync’s man page opens with examples, and even though I never actually those specific commands, they are usually enough for me to remember how to do whatever I wanted to do.

It’s even worse if you man test: you’re directed to the shell builtins page, that’s a few hundred pages long.

For builtins, use help. 'help test'

tldr [0] is great for easy to understand example commands. It is community driven and there are many cli based programs you can install[1][2].

[0] https://tldr.sh/

[1] https://www.npmjs.com/package/tldr

[2] https://github.com/tldr-pages/tldr-python-client

That python client seems very lack of maintenance. It doesn't have proper color code for Windows at all.

That's true. I thought that was the one packaged by most linux distros but debian packages the haskell client [0]. Looks like they have some windows builds too.

[0] https://github.com/psibi/tldr-hs#readme

It's even worse when you bounce between Linux, FreeBSD, and MacOS.

You might want to look into the ‘tldr’ command for those simple shell examples. It’s a very helpful command.

Lookup tldr on github. It works as a replacement for man pages 90% of the time.

You would probably love the tldr[1] command, then. It's a user maintained library of common example incantations of any given command. Nowadays I check it before `man`.

[1] https://tldr.sh/

Reply on news.ycombinator.com