
Explain shell - royalharsh95
https://explainshell.com/
======
BossingAround
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..?

~~~
emj
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](http://www.bashoneliners.com)
[https://www.commandlinefu.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.

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

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

[https://news.ycombinator.com/item?id=15776153](https://news.ycombinator.com/item?id=15776153)

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

~~~
nerdponx
Bad wording on my part -- man doesn't _support_ semantic markup by default.

~~~
groovy2shoes
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...](https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-
Reno/share/tmac)

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

~~~
nerdponx
Thanks for this detail.

------
mitchtbaum
Reminds me of:

\- [http://worrydream.com/KillMath/](http://worrydream.com/KillMath/)

\- [https://regexr.com/](https://regexr.com/)

\-
[https://simple.wikipedia.org/wiki/List_of_mathematical_symbo...](https://simple.wikipedia.org/wiki/List_of_mathematical_symbols)

\-
[https://rpi.edu/dept/math/ms_graduate/resources/SayingMath.p...](https://rpi.edu/dept/math/ms_graduate/resources/SayingMath.pdf)

------
emit_time
Explains Hell

~~~
cogburnd02
Reminds me of 'expert sex change,' haha.

------
_they
[https://news.ycombinator.com/item?id=6834791](https://news.ycombinator.com/item?id=6834791)

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

~~~
dang
That's a frequently asked question!

[https://news.ycombinator.com/newsfaq.html](https://news.ycombinator.com/newsfaq.html)

~~~
rezahandzalah
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 ;)

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

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

~~~
1_player
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.

------
asicsp
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](https://github.com/learnbyexample/command_help)

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

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

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

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

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

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

------
noir_lord
[https://explainshell.com/explain?cmd=rsync+--progress+-avr+-...](https://explainshell.com/explain?cmd=rsync+--progress+-avr+-e+%27ssh+-p47999%27+)

This is really well done, what a neat resource.

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

[https://news.ycombinator.com/item?id=16085604](https://news.ycombinator.com/item?id=16085604)

~~~
lolikoisuru
>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](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](http://mywiki.wooledge.org/FullBashGuide)

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

------
platz
There's also [https://www.shellcheck.net/](https://www.shellcheck.net/)

------
colordrops
A command line version would be great.

~~~
alexktz
[https://tldr.sh/](https://tldr.sh/)

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

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

------
gatewaynode
Why is the first example a fork bomb?!?

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

------
bernardv
Nicely done

