Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

The 'man' utility that comes with a Debian distro is not as comprehensive as ss64.com, and in environment like cygwin, it is even more so. Is there a software or a script that will make my 'man' more like ss64 pages? ss64.com contains command line reference for many different environments including Windows CMD and Mac OS X, and bash. One example I have is the man page for read

Edit: From lifehacker.com, I found the following function:

man () { /usr/bin/man $@ || (help $@ 2> /dev/null && help $@ | less) }   

help utility gives me the page I am looking for - but it does not bypass the underwhelming man page for read.

share|improve this question
5  
Could you please include some information on what ss64.com is? –  N.N. Mar 23 '13 at 8:13
    
If you are connected to the 'Net, a bit of scripting with lynx or w3m will give you access to ss64.com and whatever other site you use. –  Deer Hunter Mar 23 '13 at 9:49
add comment

2 Answers

up vote 4 down vote accepted

Having a man page for read (in section 1 of the manual) that says anything else than "There is no read command, but your shell might have a read builtin command, see your shell manual for details" is misleading, because read is a shell builtin and the behaviour and supported options vary from shell to shell.

Some systems (generally not Linux ones) however do have a read command (in /bin, /usr/bin or elsewhere) as POSIX requires (but the Linux Standard Base (LSB) specification lifts that requirement), and on those systems, the man page will describe the behaviour of that read command, and will be misleading because it's generally not that read that you invoke when you call read at a shell prompt or in a shell script or in system(), popen()... but the shell builtin one.

That http://ss64.com site describes the bash builtin read command (though it doesn't say which version of bash, and for instance, it's different from the read builtin in the version of bash on this machine, which itself is different from that read from the bash of another (older) machine I have access to) in a bash section. In that regard, it's not misleading, but where it's very misleading is where it puts all sorts of other non-bash related commands in that same section and sort of implies that bash (one of many shells available on Linux and other Unices, shells being one of many ways to run commands) is necessary to run those commands or that those commands have anything to do with it.

Now, when you do man read, if there's no read command in section 1 (user commands) of the manual, it will search in other sections. For instance, if you have installed the manpages-dev package (on Debian), you'll get the man page of the read system call (in section 2). If not, but you have installed the TCL documentation package, you'll get the man page for the read TCL function in section 3tcl.

You can ask explicitly for the read user command with man 1 read (man -s 1 read on some systems). If your manual had a 1bash section, it would bring it up before the one in section 1zsh, so you'd need to write it man 1zsh read to get the zsh variant. You can get all the man pages with man -a read, you can find out what packages they come from on Debian with: dpkg -S $(man -wa read). For instance, on this system, I have:

$ dpkg -S $(man -wa read)
9base: /usr/share/man/man1/plan9-read.1.gz
tcl8.5-doc: /usr/share/man/man3/read.3tcl.gz
manpages-dev: /usr/share/man/man2/read.2.gz

With zsh, pressing Alt-H at the prompt brings the manual (via the man command) for the command you're currently typing. The default zsh installation on Debian improves it to make use of the run-help function (see info -f zsh --index-search=run-help), so you get help for the builtins as well.

With the fish shell, there's a help builtin function that tries to bring the most sensible documentation for a given command or fish concept (from man or the fish documentation).

If for some reason, you're forced to using bash (grin) or can't be bothered to change from the default, bash also has a help builtin command that brings help on bash builtins (however note that help read is like help '*read*', that is it brings the manual for all the builtins whose name contains read, use help '[r]ead' for instance, if you only want the read manual).

bash's help only works for bash builtins. If you want to extend it to include search in the manual in sections 1 (user commands) and 6 (games) and 8 (administrative commands), you could redefine it as:

help() {
  builtin help "$@" 2> /dev/null ||
    MANSECT=1:8:6 man "$@"
}
share|improve this answer
add comment

As Stephane hints a potential pitfall of favouring online man pages is that they document older or newer versions of software than what you have. For this reason alone I think it is a very bad practice to start replacing them with ones you prefer, because at some future point there may be some subtlety concerning versions which is important -- and that could be greatly complicated if you have replaced the official docs with informative but inadvertently incorrect docs.

I have not used ss64.com, but it does look like a decent reference for certain things; I presume it is actually intended to target cygwin users as the "bash" category is really a mash-up of bash built-ins and common unix commands. Since the later technically have nothing to do with bash, this makes the site's content potentially misleading, but it would make sense from a cygwin perspective.

I do agree the GNU man pages on linux (I think those ship with cygwin too) are sometimes not as good as others -- eg, the POSIX pages are generally more in depth than the stuff in section 3, and since linux conforms to posix, I take them as valid. But I still would not replace my system pages with them -- what's the point?

All these things are effectively complementary; your system pages are what they are. Nowadays most people have a continuous high speed internet connection, and the amount of time it takes to actually read a piece of documentation completely dwarfs the time it takes to access over a network. However, I do sometimes mirror sites I find so useful that having them right at hand would be nice:

wget -r -np -k -p http://www.site.com/dir/page.html

The address is the top level index of the documentation, so eg. "ss64.com/bash/" would probably work. The switches are in described in man wget. So you download the site to a local directory, bookmark it in your browser or create an index of such, and done.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.