On Fri, 2005-12-30 at 05:21, Gene Heskett wrote:
Often the man pages have examples of the way the author expected the program to be used. However, there's still a good chance that isn't exactly what you want to do with it.
I submit to you all the manpages for bash.
Paragraph after paragraph of explanation of this option and that option in a quite verbose manner, and not a single actual example of a command line, and the results it should return.
Bash is kind of unusual because it is normally the 'calling' program, not the one being executed on a command line - or if you do execute it intentionally as a command the purpose is to start some other program in a subshell. What you need to know about bash is what it does to your command lines (splitting on IFS, expanding variables and wildcard filenames, redirection i/o etc.) before starting any other program. What those other programs do or return is their own business but they probably are the real reason you are issuing a shell command.
That makes writing even a 10 line bash script into an extended reading and re-reading session with heavy use of the manpages builtin grep because its so poorly organized that the complete answer may be in 3 or more places scattered through it.
That 10 line bash script might execute 20 different external commands, none of which the bash author anticipated. That's why the system is powerful - whenever anyone adds a new tool you are able to combine it's operations with all the others but it also makes it impossible to document all the possibilities.