6 ms·
Many comments seem to be shell- and bash-related. Perhaps the thread exposes how difficult to read the bash manpage is. On my system, the bash 4.1 manpage is 41
by p9idf 15y ago
Many comments seem to be shell- and bash-related. Perhaps the thread exposes how difficult to read the bash manpage is. On my system, the bash 4.1 manpage is 41026 words long, or about 80 pages. Manpages are most useful to me when they are short and to-the-point so I can find what I am looking for before I lose interest in skimming through an 80 page book.
- pyre 15y agoHow would you make the bash manpage short and to the point, considering the complexity that it implements?
- p9idf 15y agoBy reducing the needless complexity that it implements. The purpose of a Unix shell is to interpret a simple language wrapping syscalls so the user can easily give instructions to the kernel. There are several such shells whose source code is smaller than the bash manpage. 13 pages of the 80 page manual are devoted to readline and programmable completion. Readline and programmable completion could be removed from the shell, and their functional equivalents moved to a more logical place in the terminal emulator. Plan 9 does this, and it works well, and people seem to like it and the flexibility it gives. 24 pages are devoted to builtin commands, many of which are unnecessary duplicates of regular commands, and several unnecessary altogether. 3 pages are about weird parameter expansions, all of which can be done more intuitively with sed, except for the array one, which can be done with awk. And there are many smaller things as well, like biffing or arithmetic evaluation, which can be done with dc or whatever. You could try moving history out of the shell and into the terminal emulator as well.
- dexen 15y ago$ man bash | wc -l 5351 $ 9 man rc | wc -l 496 You may want to check out the `rc' shell from Plan 9 (carried over from latest UNICes). Simple, elegant. Available for linux via http://swtch.com/plan9port/ http://swtch.com/plan9port/ Manpage at http://swtch.com/plan9port/man/man1/rc.html http://swtch.com/plan9port/man/man1/rc.html
- throwaway64 15y agoi believe the p9 in his name is short for "plan 9" :)
- pyre 15y agoResponding that bash itself is too complex is skirting the question. The original post made it sound like the bash manpage was needlessly complex within the constraints of bash's current complexity.
- icebraining 15y agoWhile it doesn't fix the issue, zsh's man page is divided into different sections, which at least alleviates it.
- pilif 15y agoAnd zsh has the user-friendly users guide: http://zsh.sourceforge.net/Guide/ http://zsh.sourceforge.net/Guide/ This is how I learned unix shell back around 2000ish. Aside of giving an excellent insight into zsh, it also gives many good hints and notes about unix shells in general.
- gnosis 15y agoThe first two or three chapters of that guide are pretty good, but then it gets bogged down in obscure minutia to such a degree that you start to feel almost like you're just reading the zsh man pages again. The guide is in some serious need of a good editor to make it more concise and better organized. It also needs many more simple, practical examples. Unfortunately, it hasn't been updated since 2002, which also makes it a bit obsolete, since zsh development has been very active since then and zsh is now on to a new major version. Overall, the guide is a nice try, but zsh needs more and better documentation if its not going to overwhelm all but the most dedicated users.
- bostonvaulter2 15y agoI wish there was an easy way to get info about builtin commands. So things like man bash-disown would work (similar to git).
- umbramei 15y agoThe 'help' command is exactly what you're looking for -- e.g., 'help disown' will describe the 'disown' command. Definitely beats searching the entire bash man page for the command you want (which is what I did for far too long, until I found out about 'help').
- bostonvaulter2 15y agoYeah, but it often isn't as long as a real man page. Plus for some reason zsh doesn't have it!
- super_mario 15y agoThere's always google you know :D. The point is to know what to look for: $ help "*" will print out all shell built ins (list help for them). And if the short description is not enough, go google for each.
- huskyr 15y agoI'm baffled all the time by the lack of clear examples on many manpages.
- malone 15y agoSame here, most man pages seem pretty good at documenting all the available options, but are pretty useless at explaining how the tool should actually be used. I'd like to see someone dump all the common man pages into a public wiki so people could flesh out the usage examples and suggest alternative tools.
- morsch 15y agoYep, a short list of useful one-liners would go a long way. Often, your use-case will be a straight specialisation of one of the examples, and if not, chances are you can cobble together something from several examples. I'd like to have a auxiliary help command for this, e.g. example ffmpeg in addition to man ffmpeg (another 18k words manpage). Edit: This works rather well: function cmdfu() { curl "http://www.commandlinefu.com/commands/matching/$@/$(echo -n $@ | openssl base64)/plaintext" --silent | sed "s/\(^#.*\)/\x1b[32m\1\x1b[0m/g" } From http://www.commandlinefu.com/commands/view/3086/search-commandlinefu.com-from-the-command-line-using-the-api#comment http://www.commandlinefu.com/commands/view/3086/search-comma..., it uses the commandlinefu API: http://www.commandlinefu.com/site/api http://www.commandlinefu.com/site/api
- JonWood 15y agoAnother alternative is <a href="http://cheat.errtheblog.com/>Cheat</a> http://cheat.errtheblog.com/>Cheat</a>, which is essentially a CLI accessible wiki of usage examples. It was originally focused on Ruby (and still is to an extent), but it gives decent results a lot of the time.
- slug 15y agoyes, bring back the VAX/VMS help system with the helpful examples at the end, was awesome last time I used it.
- dredmorbius 15y ago
- slug 15y ago'info bash' is much better than 'man bash', give it a try.
- p9idf 15y agoOn my system, the info documentation for bash 3.1, not including indices, is 53610 words, or 105 pages. The content is identical to that in the manpage. In addition, you have to read it in a clunky, unintuitive, and un-Unixy browser. Far from short and to-the-point, I nearly lost interest just trying to figure out how to coax info to send its output to stdout so I could pipe the 105 page book to wc. The info documentation is not in any way I can measure better than the manpage. Both the info documentation (and I use that term loosely) and the manpage are more noise than signal.
- dredmorbius 15y agoInfo pages are written as a single document, but displayed by the 'info' or 'pinfo' readers in multiple pages. You can simply view the original file (it has minimal markup) in a pager for a single-file view. I generally write an "info" script or function to replace the info viewer with something more useful. I share your dislike of the info format.
- 1337p337 15y agoOr, for another alternative, w3mman, which is bundled with the w3m browser. Tabbed manpage browsing in the terminal with URLs converted into links and "foo(1)" converted into a link to the man page for "foo". Don't leave home without it.
- dredmorbius 15y agoman bash | pr | less ... gives you paginated manpages. I get about 96 pages for bash 4.1.5. man -Tps bash > /tmp/bash.ps && gv /tmp/bash.ps ... gives you the manpage pretty-printed as postscript output (assumes you've got the gv ghostview viewer installed). Or you can use a PDF converter (e.g.: ps2pdf) and read with your preferred PDF viewer. This version runs about 70 pages for the same manual.
- Tichy 15y agoOn my MacBook the manpages scroll hellishly slow and there are no "Page Down" keys (maybe there is some key combo? I don't know). I end up googling for the manpages on the web instead most of the time...