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

> $ apropos -s 3 Va=optind -a Va=optarg > 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...

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

[nerdponx]

Thanks for this detail.

[myroon5]

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

[VvR-Ox]

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

[sjmulder]

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