3

I always thought of writing a bash utility called realman which would explain commands like in the man pages but instead of laying out the commands in alphabetical order by the options the command has, it would simply just give examples the average user would need.

Some commands do give examples but as the man pages are constructed by different people there is no central control on what a man page should look like readability wise.

Take a description of man as an example

NAME
       man - an interface to the on-line reference manuals

SYNOPSIS
       man  [-C  file]  [-d]  [-D] [--warnings[=warnings]] [-R encoding] [-L locale] [-m system[,...]] [-M path] [-S list] [-e extension] [-i|-I] [--regex|--wildcard]
       [--names-only] [-a] [-u] [--no-subpages] [-P pager] [-r prompt] [-7] [-E  encoding]  [--no-hyphenation]  [--no-justification]  [-p  string]  [-t]  [-T[device]]
       [-H[browser]] [-X[dpi]] [-Z] [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [-w|-W] [-S list] [-i|-I] [--regex] [section] term ...
       man -f [whatis options] page ...
       man  -l  [-C  file]  [-d]  [-D]  [--warnings[=warnings]]  [-R  encoding]  [-L  locale]  [-P pager] [-r prompt] [-7] [-E encoding] [-p string] [-t] [-T[device]]
       [-H[browser]] [-X[dpi]] [-Z] file ...
       man -w|-W [-C file] [-d] [-D] page ...
       man -c [-C file] [-d] [-D] page ...
       man [-hV]

It's totally overkill. My man page would read...

Its a program gives you more details of a command.
eg. "man bash" would explain more about the command "bash"

Having to read through all the options of a command to find that one option that most users would use is not very constructive.

So my question is simple, is there a "realman" type program available in Ubuntu via the command line that is more user oriented as opposted to system administrator oriented?

3
  • The keywords are stated in mans manpage: ...on-line reference manual.... Manpages are not meant to be a tutorial, but a reference of all capabilities. Yes, it can be quite overwhelming (man gcc anyone?), but it is an invaluable comprehensive ressource that is easily accessible, no matter if you're connected to the internet or not. I agree however that many manpages lack useful examples (the manpage of find is an exception that comes to my mind).
    – phoibos
    Mar 21, 2013 at 23:54
  • 3
    Oh and if you write a realman utility, I propose you call it layman - real men (and women of course) use man :D
    – phoibos
    Mar 21, 2013 at 23:59
  • @phoibos nice thought, I like!
    – Meer Borg
    Mar 22, 2013 at 0:03

1 Answer 1

7

What you're asking for might not be well-defined. Not every command has "that one option most users would use."

However, you said that for man you'd want to see something like:

Its a program gives you more details of a command.

For information like that about commands, use whatis. This summarizes man pages.

ek@Kip:~$ whatis man
man (7)              - macros to format man pages
man (1)              - an interface to the on-line reference manuals
ek@Kip:~$ whatis whatis
whatis (1)           - display manual page descriptions
ek@Kip:~$ whatis ls
ls (1)               - list directory contents
LS (6)               - display animations aimed to correct users who accident...
ek@Kip:~$ whatis ping
ping (8)             - send ICMP ECHO_REQUEST to network hosts

This still doesn't give you any information about command-line options for the commands (but then again, neither does "It's a program that gives you more details of a command").

If you want an intermediate amount of information, the best course might be for you to look up the command on the Internet. You can search the web for it, or even Wikipedia. Many of the most well known and commonly used commands have Wikipedia articles. For example, see the articles on ls, man (about manpages in general, but includes man syntax advice), grep, and fsck.

You can browse the web from the command-line, if you wish, by using a web browser that supports command-line mode (such as links2 Install links2), or a command-line only browser (like lynx Install lynx).

Finally, please note that many command-line utilities in Ubuntu come from the GNU project, which provides excellent documentation. Often it's longer and more detailed than the manual pages, but you might find it better organized. And usually there are descriptive headings that help you find specific information, in my experience much more easily than in many manpages.

GNU manuals can be found here. (Remember not all utilities are GNU utilities.) Many of the most commonly used commands don't appear by name but are part of GNU coreutils. GNU manuals can be viewed online and also may be downloaded in various file formats, some of which are well-suited to viewing on the command-line.

2
  • Interesting points, I think I might examine my "realman" idea by pulling text from Wikipedia. Yes I know I can get stuff online but sometimes I'm stuck with a ssh connection and instead of having to wade through 3 pages on man options a simple example would get me on the road.
    – Meer Borg
    Mar 22, 2013 at 0:02
  • Thanks! whatis is super useful, I'll look into giving myself command line access to GNU docs.
    – Aditya M P
    Oct 25, 2013 at 10:57

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .