[issues] reading man pages [was conversation monopolization]

[Jenny Brown (was Gable)]

> and please dont send me to man pages.  ive read man pages. i think they
> were written by and for men.  i cant even begin to make sense out of
> them!

They're addressing a rather complex topic... attempting to write
down every detail of every program, in every possible variation.
That includes things like, if you use option a, you must also
use option b, unless you're providing c and d, then b isn't needed.

So, they start to use <> [] | {} to denote the various combinations,
but those things don't mean a dang thing unless you have a legend.
They do have standards (very much so) and if someone takes the time
to tell you what those standards are, they will mean so much more.

I'll include info I wrote here; anyone making faq's, etc, is completely
free to use it.  I'm making it an attachment, since it's html; hopefully
people will be able to ignore it more easily if they aren't interested,
this way, and I won't produce a mail body full of html.

Jenny

Title: Unix Man Pages

Unix: Man Pages Manual Pages No manual entry found error Looking up help for a command The meaning of usage lines Manual Pages Also known as... deciper this: /usr/bin/grep [ -bchilnsvw ] limited-regular-expression [ filename... ] /usr/xpg4/bin/grep [ -E | -F ] [ -c | -l | -q ] [ -bhinsvwx ] -e pattern_list [ -f pattern_file ] ... [ file... ] Manual pages (in this context) are help files about unix commands. They are typically written by the creators of the command or program. They detail all of its features and options. They explain what each feature does, how it works, and often how it might be used. They tend to be very technical information, not a beginning introduction. This page focuses on interpretting the basics from the man page, so that you can skim and get the most useful information quickly. The way you get a manual page for a command is to type: man command where the word command is replaced by the actual command you're trying to look up. You can man grep, man ls, man cd, etc. This will fill your screen with information about the command. Use the space bar to page through to the end. You might have to type q at the very end to quit and go back to your prompt. No manual entry found error Try out manual pages by typing the following command; help for this command should be available on every system. man ls (that's LS in lowercase) You will either get information about the command ls for listing files, or you will get an error as described below. If you get actual help information, great! If not... If you get "Command not found", try typing /usr/bin/man instead of man, and try again. If the system cannot properly locate the help file for that command, it will say No manual entry found. In this case, you need to set your MANPATH environment variable. An example value that will probably be useful is: /usr/openwin/man:/usr/local/man:/usr/man:/usr/share/man Try either of the following commands, depending on your shell, to set your man path to this value. setenv MANPATH /usr/openwin/man:/usr/local/man:/usr/man:/usr/share/man MANPATH=/usr/openwin/man:/usr/local/man:/usr/man:/usr/share/man export MANPATH If this solves your problem, add those lines to your .login, or .tcshrc, or .bash_profile file in your home directory. Refer to the section Using the Command Line for more details. If this doesn't solve your problem, it's possible that help for a particular command is simply not available on that system. You may not have the command spelled correctly, or you may be thinking of a concept instead of a command. To find help on possibly related commands, do a keyword search instead: man -k keyword This will list all the manual pages that might be related to that keyword. You can glance through the list of words it gives you and pick out what might be appropriate, then run man against that. Looking up help for a command Assuming your MANPATH is set up correctly now, and man itself is in your PATH (so you don't have to type out /usr/bin/man every time), you will see manual pages appear on commands you look up. These pages have several common sections. The first section is usage syntax. This will be discussed in greater detail below, but essentially, it tells you what parameters are necessary for the command. The meaning of the most common sections is listed here. NAME What the command is, and a one liner or so of what it's for SYNOPSIS Usage and syntax details, parameter flags, required arguments DESCRIPTION Full length explanation of the command's purpose and limitations OPTIONS A list of configurable behavior, alternate behaviors, command line flags EXAMPLES List of examples for using the command for practical things ENVIRONMENT What environment variables affect the default behavior of the command EXIT STATUS Meaning of success and failure codes and error codes FILES Any files on the unix file system that relate to this command, usually configuration defaults SEE ALSO Other related commands that could be useful NOTES Special behavior notes, bug list, and oddities The sections that are probably the most useful to you when skimming are the name (basic purpose), the synopsis with usage syntax, and the options and examples. Look first for the default behavior of the command, or try typing the command by itself at the command line, with no parameters, to see what arguments it requires. Then investigate the examples and the options. You may rerun man several times so you can look at sections out of order. In some man page readers, pressing b for back will scroll upward through it, so you don't have to just go through in order. The meaning of usage lines When you read the SYNOPSIS section, you will see a lot of meaningful punctuation. This defines which parameters are required, which are optional, and which are exclusive. /usr/bin/grep [ -bchilnsvw ] limited-regular-expression [ filename... ] /usr/xpg4/bin/grep [ -E | -F ] [ -c | -l | -q ] [ -bhinsvwx ] -e pattern_list [ -f pattern_file ] ... [ file... ] In this case, there are two different versions of grep available on the system. /usr/bin/grep is the default, and is probably the one in your PATH. The other (xpg4 version) is intended for use by people who are more familiar with other operating system versions of it. While it will serve a good example for syntax, you will in all likelihood be using the first, not the second, during daily work. The first thing you see is the path to the command. This shows the full path of where it is most likely installed on the system. This may not be accurate on your system if your administrator has moved things. In any case, you generally don't need to type out the full path, only the command itself. The following items in the line are a combination of command line flags (-b -c -h etc) and normal arguments, such as in this case a pattern to look for and a file to look in. [ ] enclose lists of optional items to be considered as a group, like mathematical parenthesis. They may be nested more than one level deep. For instance, [ -f pattern_file ] means that if you use -f you need to tell it the pattern file to look in. A | B | C means either a, or b, or c, but not more than one at a time. -bhinxvwx means any combination of those optional flags. Something outside of [ ] means a required argument, for instance a regular expression pattern to look for. A set of ... means any number of the last argument, for instance file ... means file1 file2 file3 file4 as many as you want. So, proper usage for the first version of grep is something like: grep -i the myFile.txt This would performa a case insensitive (-i) search for the (the, THE, The, tHe, tHE, etc) in the file named myFile.txt. Manual pages can be very useful for gaining more understanding of the system. They are best scanned until you understand the basics of a command well. Then when you want more detail, you can read the entire thing.