The most brutal man page

In The Linux Command Line, the author describes the bash man page* as “the most brutal man page of them all.”

Many man pages are hard to read, but I think that the grand prize for difficulty has to go to the man page for bash. As I was doing my research for this book, I gave it a careful review to ensure that I was covering most of its topics. When printed, it’s over 80 pages long and extremely dense, and its structure makes absolutely no sense to a new user.

On the other hand, it is very accurate and concise, as well as being extremely complete. So check it out if you dare, and look forward to the day when you can read it and it all makes sense.

* If you’re not familiar with Unix lingo, “man” stands for “manual”. Man pages are online documentation.

Related post: Review of The Linux Command Line

16 thoughts on “The most brutal man page

  1. Does it really make no sense? I don’t know, it looks like it’s OK… but I don’t know what information to look for ;) I think I’ll take the “check out if you dare”, well, as a dare.

    BUGS
    It's too big and too slow.
    got me, though :)

  2. I usually use the info documentation instead. I find it is very poorly organized. Here are the main sections.

    * Introduction:: An introduction to the shell.

    * Definitions:: Some definitions used in the rest of this manual.

    * Basic Shell Features:: The shell “building blocks”.

    * Shell Builtin Commands:: Commands that are a part of the shell.

    * Shell Variables:: Variables used or set by Bash.

    * Bash Features:: Features found only in Bash.

    * Job Control:: What job control is and how Bash allows you
    to use it.

    * Command Line Editing:: Chapter describing the command line
    editing features.

    * Using History Interactively:: Command History Expansion

    * Installing Bash:: How to build and install Bash on your system.

    * Reporting Bugs:: How to report bugs in Bash.

    * Major Differences From The Bourne Shell:: A terse list of the differences
    between Bash and historical
    versions of /bin/sh.

    * GNU Free Documentation License:: Copying and sharing this documentation.

    * Indexes:: Various indexes for this manual.

    Where do you find the command-line options? They’re under “Bash Features.” How about the meaning of ${PARAMETER:%%WORD}? That’s under “Basic Shell features::Shell Expansions::Shell Parameter Expansion.” This dichotomy makes little sense to someone who isn’t already very familiar with both bash and its differences with the Bourne shell.

  3. Ibrahim M. Ghazal

    And this isn’t even the full manual. The actual manual is an info document, which is even bigger:

    $ man bash | wc -l
    5459
    $ info bash | wc -l
    9716

    But at least it’s much better structured than the man page, and can be read in a browser.

  4. E E: The author explains in the introduction:

    This book is very Linux-centric. Many other books try to broaden their appeal by including other platforms, such as generic Unix and Mac OS X. In doing so, they “water down” their content to feature only general topics. This book, on the other hand, covers only contemporary Linux distributions. Ninety five percent of the content is useful for users of other Unix-like systems, but this book is highly targeted at the modern Linux command line user.

    Emphasis in the original.

  5. In terms of length, the zsh manpage has both bash and gcc beat by a long shot:

    % man bash | wc -l
    5351

    % man gcc | wc -l
    14820

    % man zshall | wc -l
    26193

  6. Oh well. “Thy shalt not read that man-page as an introduction text or tutorial”. That would be an ill-framed expectation. A man-page is all about reference. That’s where it shines. Allways at your (command-line) hand. Combine that with a sophisticated search in your favourite pager (say ‘less’) and you can efficiently (and effectively) figure out that obscure option or syntax that you once used or have seen being used but have forgotten ever since. For a newbie introduction get a book or bootstrap your emacs and give ‘info’ a try.

  7. And thus why in most cases “RTFM” is rather less then helpful. In fact it is usually the inverse of helpful as I usually then just give up and use a different program.

    However if you want to see really bad documentation try getting help on *anything* in emacs. The terms are all emacs specific with little expatiation (For example: Window means something different in emacs then in x11 or windows). Most of the ‘how do I do this’ questions are answered by code snippits with no explanation of how to use them, or even a link to a page on how to use them, and even asking for help on the #emacs IRC channel gives you a huge slection of people who will tell you ‘Don’t do that, use this emacs feature which does a similar thing, but not the thing you asked about’ or a code snippit, followed by no help about how to use it (usually being told to rtfm if you ask) or no help at all.

    I love emacs, I love how easy it is to move to C-foo keyboard shortcuts after working in windows for so many years, I like how I can discover new features through the GUI and how its editing system makes sense. I however only use it as a text editor, and not my only text editor, also using TeXStudio and notepad++, since it is too hard to customize or get it to do anything it doesn’t do by default.

    Frankly, I see why VIM is so much more popular despite not being as powerful or intuitive: Lots of other programs have easy to activate vim keybindings, whereas emacs people do everything in emacs. When you try and do foo in emacs it is hard to do foo, and you can’t get help.

    I know documentation sucks to write, but common. You wrote an amazing text editor, let me learn how to use it.

  8. For comparison, read the excellent man page for the Korn shell, written by David Korn (i.e., not the man page for the pdksh clone of the Korn shell, which may be installed on your system as ksh with its own documentation). Here is the ksh man page:

    http://www2.research.att.com/sw/download/man/man1/ksh.html

    Original man pages from Bell Labs seem to be of a uniformly high standard, followed by original BSD man pages; FSF/GNU documentation tends to provide all of the required information, but in a completely indigestible form.

    I once read that when HP produced a new calculator, rather than have their engineers write the documentation, they would hire a technical writer who would be trained by their engineers in the use of the calculator, and then said writer would produce the documentation, which would be of a very high standard because the author, like the user, had to start with a blank slate, whereas the engineers would start with a huge pile of assumptions about the knowledge and experience of the reader. Seems like a good approach.

  9. IBM’s iOS, formerly OS/400, formerly OS/38 runs rings around Unix in this department. Such a shame it looks like it will never be open-sourced. Apart from These systems, beOS, and the doomed OS/2 there has not been a serious attempt at an object-oriented operating system, and properly thought out mnemonics for commands, eg. on these systems there are chg- prefixed commands for changing an object, dlt- for delete, wrk- for working with a list. Each command will behave differently depending on the object type, each screen has context-sensitive help. You are never confronted with a blank screen (each command has reference to others, or an index of commands, also searchable by verb, and functional department.) Do I sound like I miss it? I bloody do. Intensely at times….

  10. In defense of the bash manual, it’s supposed to be a concise and complete reference for all features, not a tutorial. It’s not supposed to teach me how to use extglobs or conditional expressions. It’s supposed to help me quickly look up the exact syntax for “match all files that don’t have ‘4rsq’ in their name” or “test whether a file is a symlink” when I haven’t used those features for over a year.

  11. perverse incentives at work
    Experts get paid for their knowledge
    Therefore, they tend to value knowledge that is hard to aquire
    Therefore, they tend to (mistakenly) value knowledge that is hard to get because it is explained poorly
    I think the clearest example is musical instruemnts: why on earth are they so hard to play ? It makes no sense whatsoever
    sorry, rambling a bit.
    If the man page is hard to understand, why don’t we say, this is an embarassment ? Because “we” get paid for our ability to absorb compelx knowledge, so we tend to think that if knowledge is hard to get, it is valuable, rather then thinking that if knowledge is hard to get, it means someone should make it easier to get, or remove the problem (this is what made s jobs great; he saw problems that tech people viewed as “positives” [i know all the command line commands…] and he changed things so the problem went away

  12. Hah! The first man page I thought of after reading the post title was the bash page. That thing is a monster. I’ve learned to tame it by gratuitous use of / (keyword search).

    Definitely not for learning bash. I keep a link to the Advanced Bash-Scripting Guide nearby for learning how to do stuff with bash.

  13. It’s all open source, so you can contribute updates to any man pages should you feel you can clarify some point!

Comments are closed.