Explain shell | Hacker News Reader

Explain shell

explainshell.com

329 pointsroyalharsh9552 comments

Explain shell is something that has helped me a lot, but the situation of needing it left me baffled for so long... Why can't I search by command + flag? For example, I know what command A does, but I'm not sure what flag C means. I can search for man A, but why can't I search man A --flag C to get only the relevan portion of the manpage?

This has baffled me for years. I'd have guessed that discoverability and documentation would be a core functionality and focus of open source developers.

Also, if I find a command which flag is not explained by explain shell, is there some source I can create PR to? Some DB, where I could propose the addition..?

The terminal was not built for that kind of automatic lookup, and I often find that options are only interesting in their contexts, so while it might in many cases be possible to show the docs for one option only I think you would have to write a man pages in a different style to make that really usefull. The best place for you to create a PR is against the original program, it says on Explainshell that everything is built upon the original man pages, or maybe you can create some kind of new service like http://www.bashoneliners.com https://www.commandlinefu.com to add your own documentation for random commands and options..

That said good documentation is a hard problem, what to document, how to do it, and what use it will have down the line. Your goal is not everyone elses goal, I always come to the problem from the other side: "I need this extra thing from this command, do I need to code somehting custom or is there something that can do it for me". So it's mostly a question of refrasing problems that fit the tools I have rather than looking up what one option does.

It's not the terminal's fault, it's because man lacks semantic markup.

There is sematic lookup, but I've never seen anyone use it except here on HN:

https://news.ycombinator.com/item?id=15776153

> $ apropos -s 3 Va=optind -a Va=optarg > https://man.openbsd.org/whatis.1

Bad wording on my part -- man doesn't support semantic markup by default.

But it does. From OpenBSD's mdoc(7):

The mdoc language supports authoring of manual pages for the man(1) utility by allowing semantic annotations of words, phrases, page sections and complete manual pages.

From GNU groff's mdoc(7):

The -mdoc package is a set of content-based and domain-based macros used to format the BSD man pages.

I'm not 100% sure when exactly mdoc was introduced, but the earliest appearance I can find is in /share/tmac/tmac.doc in 4.3BSD-Reno [1], whose file header gives it as version 5.9, dated 24 July 1990 (a modified version of this same file appears in the earliest release of GNU groff I could find, version 1.02 from 2 June 1991 [2]). And taking a look at the mdoc language reveals that it is indeed very much a semantic markup, even more so than most markups that otherwise receive the moniker.

And even the unmaintained (and relatively featureless) version of man(1) that ships with my Slackware 14.2 installation supports it by default, via the magic of groff -mandoc:

mandoc — Use this file in case you don't know whether the man macros or the mdoc package should be used. Multiple man pages (in either format) can be handled.

(that's from groff_tmac(5); meanwhile man.conf(5) says that -mandoc is used by default).

A look at the source (in /usr/share/groff/1.22.3/tmac/andoc.tmac on my system) reveals some troff macro trickery to load either the man package or the mdoc package based on which macros the manpage is trying to use, and then reload the manpage with the appropriate package.

4.3BSD-Reno has an equivalent, too (in /share/tmac/tmac.andoc), whose header gives it as version 5.4, dated 28 July 1990—it strikes me as considerably simpler, but the basic idea is the same. Ye olde groff's was similarly simple, so I'm sure there are good reasons for the complexity that's since been introduced.

The point of all this being: man(1) has supported semantic markup by default since before Linux or any of the modern BSDs existed. On BSD it's been the preferred markup for manpages for ages, afaict, but it's never really caught on in the Linux world, despite having been supported—perhaps because it's always been more popular to write manpages in something like POD or LinuxDoc or DocBook or AsciiDoc or Markdown or some other markup and programmatically convert them to roff(7) input, and those formats don't offer the semantic richness or detail for the domain of manpages that mdoc(7) does, so converting to man(7) makes more sense in that case.

[1]: https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/sh...

[2]: http://git.savannah.gnu.org/cgit/groff.git/commit/macros?id=...

Thanks for this detail.

What about: man foo | grep bar

Then you only get the line with "bar" in it. (append -C 1 at the end to get 1 line before and 1 after the term you grepped for).

And of course you can pimp your terminal experience by using fish (https://fishshell.com/) as it ships with autosuggestions and other really nice features. (Beware that it will not provide 100% POSIX compliance but if that's an issue you can use ZSH or pimp your bash as well).

Then there is other kind of man pages like TLDR (https://github.com/tldr-pages/tldr) which is curated by community and quite awesome ;-)

> What about: man foo | grep bar

I prefer to search from within the pager to see the option description in context:

    man httpd
    /-n

Then 'n' for the next hit or 'N' for the previous, like vi. This is for 'less' in general, not just man.

As far as missing command flags, this explains what to do: https://github.com/idank/explainshell/issues/1

Reminds me of:

- http://worrydream.com/KillMath/

- https://regexr.com/

- https://simple.wikipedia.org/wiki/List_of_mathematical_symbo...

- https://rpi.edu/dept/math/ms_graduate/resources/SayingMath.p...

Explains Hell

Reminds me of 'expert sex change,' haha.

https://news.ycombinator.com/item?id=6834791

Curious, how long is it until it's okay to post a duplicate?

I dont know the exact time but it wont let you if it has not been long enough. And it is tradition for someone to post links to previous discussion.

Unless I'm going crazy, the guidelines used to say 1 year.

That's a frequently asked question!

https://news.ycombinator.com/newsfaq.html

Thank you.

> If a story has had significant attention in the last year or so, we kill reposts as duplicates. If not, a small number of reposts is ok.

I was embarrassed it's in there and expected a definitive rule. Now I'm not feeling that bad ;)

Yup and https://news.ycombinator.com/item?id=13989215, from 2017.

If you really want to know how many time it has been posted, HN links to "from" tab when you click the site in the parentheses instead of the title: https://news.ycombinator.com/from?site=explainshell.com

Welp, I still don't know what :(){ :|:& };: exactly does, but it sure borked my WSL. Error: 0x80070040 after forking too many processes.

I know comment moderation sucks, but it would be great to have some kind of wiki/comment system/human generated notes on popular commands.

You define a function named :, which calls iself and goes in the background. Then you call : at the end and start the neverending chain of :-calls till your memory bleeds.

Not really: the function `:` calls itself and _pipes_ into itself.

The difference is - from what I can deduce - that if it were to only call itself, there would be up to 2 `:` processes running at a time, while the bash call stack would grow indefinitely. Using all your RAM but not an actual fork bomb.

Adding the pipe makes the number of `:` processes grow exponentially, and very quickly you reach the limit of 16384 active processes (PIDs, actually) on a Linux box.

Not quite wiki (you have to create your own notes) but you may find this utility helpful: https://github.com/sinclairtarget/um

It's a classic "fork bomb": https://en.m.wikipedia.org/wiki/Fork_bomb

You have gazed upon the smileyface of doom.

Also, that does sound great.

Its also known as a fork bomb! I have one tattooed on my arm.

Interesting that WSL does not take the entire host to doom.

Oh it did. I have 32 cores, but still managed to have so many threads running that Task Manager itself went Not Reaponding.

It defines a function : that launches two copies of itself in the background. Then it calls that function.

    bomb() { bomb | bomb & }; bomb

Inspired by this site, I made a handy shell script[0] for use from cli - good enough to lookup documentation for options from man/help pages. Doesn't cover all the features offered by explainshell, there are issues with some corner cases and tested only on Ubuntu

[0]https://github.com/learnbyexample/command_help

What I like most about this kind of posts. Is that users will share other alternatives and gems. Not disspointed

This is great, but the man page for pipes is probably not helpful to the kinds of people who benefit from this tool.

Can’t view the page on iPhone 6 and safari. Doesn’t let you zoom out to see the whole page at once.

I'm surprised that some sites just don't load on a 5 year old environment while providing nothing more valuable than sites from 15 years ago. Frameworks just need to do better.

Which 15-year-old site is this one equivalent to?

I suspect that GP is referring to layout and formatting, not content.

https://explainshell.com/explain?cmd=rsync+--progress+-avr+-...

This is really well done, what a neat resource.

This is convenient but I still stand by the statement I made here:

https://news.ycombinator.com/item?id=16085604

>Bash has a huge number of little shortcuts that are difficult to learn. [snip] it is difficult to Google for its meaning

Everything you could ever ask for is in the manual and also in the man page.

RTFM: https://www.gnu.org/software/bash/manual/bash.html

If you need a tutorial or a guide then try this one: http://mywiki.wooledge.org/FullBashGuide

I love this so much. Its perfect tool for developers, i don't know how i didn't encounter this sooner, it exists for more then 5 years.

There's also https://www.shellcheck.net/

A command line version would be great.

https://tldr.sh/

The only thing one should gather from these threads is that mos people on this site are completely incapable of using the shell and are too lazy to learn it.

Or, alternately, most people on this site are interested in learning how to use the shell, and are therefore interested in tools like explainshell, which make such learning easier.

Why is the first example a fork bomb?!?

Because it's a good example of confusing shell code?!?

Nicely done

Reply on news.ycombinator.com