Lots of variables affect a man page; how is the program structured? how will the man page be structured? how detailed will the man page be? Not always easy to read, and not always terribly helpful, a man page is nevertheless your first stop when you're trying to figure out an app.So, let's examine the typical structural elements of a man page so that we might be able to read them a little bit easier.section: NAMEThe first portion is the NAME of the program, which you will already know, having typed in man <name>...but what you may not know is the exact function of the program. Ideally, the NAME field will provide a helpful description of what the command does. Examples:
NAME strings - find the printable strings in a object, or other binary, file
NAME netstat -- show network status
NAME SSL - OpenSSL SSL/TLS library
Those all seem pretty clear, right? Look again! The last one, for SSL, is one idiosyncrasy of man pages: some man pages are not about applications. Some man pages are for libraries, which are important for some people to know, but it may not be what you are looking for. For instance, if you'd been told by your boss to set up an SSL key and request for a server, you might sit down and logically type man SSL just to see where to begin. Trouble is, this is a library that helps the SSL process work -- not the program you need to use to generate the key. The program you are really looking for is openSSL but to the untrained eye, this man page would be as good as any for information about SSL, and you'd end up being quite consfused.So how would you know this was not the right man page? Well, the word "library" from now on will tip you off, right? But also notice that at the very top of the man page, the ssl has a (3) after it. This indicates that it's from section 3 of man pages, and section 3 happens to be reserved for Subroutines.... so you'd know that SSL was not the primary command you're looking for.What you would then do is scroll all the way down the man page (if your terminal recognizes vim commands, use control-F, or simply type a capital-G) and you'll see a SEE ALSO section. This lists a man page you should read called openSSL(1).....and, you guessed it, the (1) denotes a General Command.... So you'd hit Q to quit the man page, and type in man openssl to read all about openssl....for all the good it will do you.section: SYNOPSISLet's continue with the openSSL example, because it's a fine example of a very complex program with good documentation that is nevertheless practically useless to someone who doesn't know what SSL is or how to use it...The SYNOPSIS section is where the man page tells you the order in which you are supposed to string together various commands and options. openSSL, for instance, is the big umbrella command under which a number of different and significant other commands reside. This is why in its synopsis it shows this:
SYNOPSIS openssl command [ command_opts ] [ command_args ] openssl [ list-standard-commands | list-message-digest-commands | list-cipher- commands ] openssl no-XXX [ arbitrary options ]
To which I say.....WTF????OK, so what it's telling us here is that to use this application, you first enter the name of the program -- simple: opensslthen you enter the "command" which can be found lower in the man page listed under the "command" heading:
STANDARD COMMANDS asn1parse Parse an ASN.1 sequence. ca Certificate Authority (CA) Management. ciphers Cipher Suite Description Determination. dsa DSA Data Management. gendsa Generation of DSA Parameters. genrsa Generation of RSA Parameters.
I abbreviated that for sake of space; there are a lot of commands available under the openSSL application. Which one do you use for what you think you are trying to do? This is where many man pages fail; they are not always (or often?) written for someone completely new to the command. In many ways, you must know what you need to have happen and even know how to do it, you just need some clarification on the exact sytax or spelling of the command. This means that when someone says "RTFM" what they really mean is "Read a Few Books on the Subject and Then Google for It and Post in Some Forums and then Give Up and take a College Level Course".But let's assume you're familiar enough with, say, the theory of SSL and maybe you've listened to my openGPG tutorial and are therefore familiar with the idea of keys and things like that. So we'll wade through this openSSL stuff.So, the way I like to think of most commands is kind of in a DOM tree format, or if you were an English major like myself, in a traditional Outline format. A little something like this:
CLI Program Name Command 1 Option 1_1 Arguments Options 2_1 Arguments Command 2 Option 2_1 Arguments
so in the openSSL example:
openssl # =CLI program genrsa # =command 1 -rand # =command 2 ../fu.pdf # =option 2_1 :.../bar.txt # =option 2_2
How do you know what commands to string together and how they want their options to be given? Well that's the RTFM part of the equation, and this man page isn't going to let you in on that secret. Some do. Let's look at the tar man page, which I think is a really well written man page (thank you, FSF):
EXAMPLES tar -cf archive.tar foo bar # Create archive.tar from files foo and bar. tar -tvf archive.tar # List all files in archive.tar verbosely. tar -xf archive.tar # Extract all files from archive.tar.
Wow, examples!? What a concept. How much clearer could a man page be? Another cool thing about many FSF man pages are that they offer additional manual information as a textinfo file:
SEE ALSO The full documentation for tar is maintained as a Texinfo manual. If the info and tar programs are properly installed at your site, the com‐ mand info tar should give you access to the complete manual.
Suddenly the term "RTFM" is starting to mean something.But some man pages aren't as pleasantly assembled, and such is the case of openSSL. Fortunately, there is a trick to issuing CLI programs a little bit at a time, which will render feedback from the program, giving you hints toward what it needs next.For instance if we enter:
openssl genrsa -rand
then we get this response:
usage: genrsa [args] [numbits] -des encrypt the generated key with DES in cbc mode -des3 encrypt the generated key with DES in ede cbc mode (168 bit key) -aes128, -aes192, -aes256 encrypt PEM output with cbc aes -camellia128, -camellia192, -camellia256 encrypt PEM output with cbc camellia -out file output the key to 'file -passout arg output file pass phrase source -f4 use F4 (0x10001) for the E value -3 use 3 for the E value -engine e use engine e, possibly a hardware device. -rand file:file:... load the file (or the files in the directory) into the random number generator
this is a lot of information, some of it is important, some of it isn't. It does tell us, if we're familiar enough with encryption, that we have the option to encrypt the key with -des3 (168 bit key). Well, more bits are better than fewer bits, right? so we'll throw that in the mix.Also, it tells us HOW the -rand switch wants to be formatted as well as what it does. It says right at the end of the above code block that -rand wants the filenames separated by colons; and that the purpose of this switch is to load files into the random number generator. Again, if we're familiar enough with encryption to understand that computer can't really be Random, we can see that openSSL attempts to use unexpected files from you, an irrational and spontaneous human, as the basis for generating a number. So we can throw that into the mix too:
openssl genrsa -des3 -rand fu.txt:bar.pdf:fubar.txt
And this would generate a key, ask for you to enter a passphrase, and deliver the key to standard output; ie, it would dump the key out onto your screen.Again, if you know about openSSL or just the whole key thing in general -- enough to know that you need to preserve thsi key, you might copy and paste this key into a text file and dump it somewhere useful. But if you to do that, you'd probably surmise that this is more efficient:
openssl genrsa -des3 -rand fu.txt:bar.pdf:fubar.txt > /usr/local/apache/conf/ssl.key/klaatuwebserver.key
And you'd be done, in theory! You've successfully decrypted a man page.Well, almost.I can't find anywhere in the openSSL man page how to set the key to be 1024 rather than the default 512 bits long. This is, for me, where Google and Research come into play. If you read up enough on openSSL -- especially if you're purchasing a certificate from Verisign or Entrust or NigerianCertsIncorporated or some trustworthy place like that, you'll probably come across helpful information on their site, and you'd eventually learn that you can add a bit length switch in the command like so (note the addition of 1024 just before the redirection):
openssl genrsa -des3 -rand fu.txt:bar.pdf:fubar.txt 1024 > /usr/local/apache/conf/ssl.key/klaatuwebserver.key
And THAT would be a pretty well constructed, complete openSSL command. Took us long enough to get there, I know. I think a few examples would be a great addition to the openSSL man page, an many man pages but maybe its just me.section: WHAT HAVE WE LEARNED??So, we've learned a few important things:1. some man pages are just inadequate, sometime because you don't know enough to be trying to do something as advanced as you are trying and need to study some more, and other times because its badly writtena. you can email the author of the man page a revision of the man page if it is really bad and you can do better; s/he might not take you up on the offer, but then again, s/he might!2. man pages do tell you the structure of a command. you may not know what you need to put in, but once you do know, you will know in what order the CLI program wants it all in.3. man pages tell you what options are available for a CLI program4. sometimes it's easier to read a man page as a normal text document in a traditional word processing app. To get a man page into .txt form, just do this:
man mplayer > mplayerManPages.txt
5. Taking a command a little bit at a time will hint you along to completion.6. research and studying are your friends.section: CONCLUSIONThis stuff can get complex. Better stay on Windoze or Mac. Avoid this Linux and Unix and BDS stuff at all costs. But if you must do *nix, enjoy the addiction!