[Techtalk] New to the list...new to linux

[Kai MacTane]

At 9/29/01 05:59 PM , Akkana wrote:

>At first, when you start using apropos and man, you will feel
>overwhelmed and you'll get the impression that none of the manual
>pages make any sense.  That's normal. :-)  Don't panic: after a
>while you'll start getting the hang of the way they're organized,
>and then you'll find that you can usually figure out what you need
>using the online help.

And, to add to this, one of the reasons why you'll feel that they make no 
sense is because they're leaving out one or two pieces of information that 
they assume you already have: the general structure of a Unix command line. 
This is something that drove me bats when I was first learning; I recall 
that people kept telling me, "The man pages have all the info you need," 
and yet they made no sense to me.

This is because the man pages are *not* designed primarily to be a primer 
for those who have no knowledge of the system! They're designed more to 
allow someone who *already* understands Unix to use a command that's 
unfamiliar to them, or to remind someone who's already familiar with a 
command what all of the obscure little options are.

Crucial knowledge that's left out: the basic structure of any command line is:

    command   switches    other parameters

Switches in Unix are (almost) always prefixed with a dash (or hyphen, or 
-). They come in two major types, Boolean and non-Boolean; and in two major 
formats: long and short.

Boolean switches are simple on-off types. You either use the switch (such 
as -a or -R on the cp command), in which case it's turned on, or you leave 
it out entirely, in which case it's turned off (unless it's a default of 
the program). The non-Boolean ones take actual arguments, like the "du -X 
filename" switch. (du shows disk usage by file in a given directory; the -X 
filename switch tells du to eXclude all files listed in the file given by 
filename.)

Short switches are the kinds you've seen so far, a single dash and a single 
letter. They can be concatenated however you like, as in ls -la (or ls 
-al), or cp -ipRv (or -iRvp, or whatever). Long switches use two dashes, 
then a full word. A few examples of these are ls --block-size=16384, ls 
--color=tty, and df --sync. As you can see, long options can be Boolean or 
non-Boolean, and as the following examples show, you can mix long options 
with each other, and with short options:

    ls -lF --color=tty
    ls --color=tty --block-size=2048
    df -H --sync

Finally, you have the "other" (non-switch) arguments. These are things like 
the directory to display (for ls, or du), the file to copy and the place to 
put it (for cp or mv), the remote host to go to (for telnet, ssh, ping, 
traceroute, and the like), or whatnot. Some commands absolutely require 
such arguments, while others will happily work fine with no arguments at 
all. (date, for example, if invoked with no arguments, will simply give you 
the current date and time; df will display the amount of free disk space on 
all mounted volumes, and du will recursively tell you the total file size 
of each subdirectory of your current directory, finishing with the total 
file size of the current directory. (This can be quite a bit of output if 
your directory has lots of subdirectories. I recommend against trying du 
with no arguments in /, unless you're very patient, very curious, or know 
that pressing Ctrl-C will abort it.))

When you look at they SYNOPSIS line in a man page, it will begin with the 
command name, then list a variety of arguments. Some of them will be in 
[square brackets]; this is a fairly universal Unix convention for "this is 
optional". Things that aren't in brackets are *not* optional; this is why 
the cp man page synopsis says "cp [OPTIONS]... SOURCE DEST". The options 
are (as their name suggests) optional; SOURCE and DEST are not.

Since synopses can only be one line long, they use a lot of abbreviations. 
Then the DESCRIPTION section will explain all the abbreviations. (Some 
pages, like cp, will have multiple SYNOPSIS lines, showing multiple ways of 
invoking the command. The second line, "cp [OPTIONS]... SOURCE... DEST", 
differs from the first only in the presence of a "..." after "SOURCE". This 
shows that you can put *multiple* sources in; they will _all_ be copied to 
the same destination, DEST.)

I hope that helps you understand man pages a little more; I know I had 
screaming fits with them when I was getting started. (And now I'm a Linux 
and Solaris sysadmin; have been for a few years. There *is* hope! <g> )

                                                 --Kai MacTane
----------------------------------------------------------------------
"Three o'clock in the morning/It's quiet and there's no-one around,
  Just the bang and the clatter/As an angel runs to ground,
  Just the bang and the clatter/As an angel hits the ground."
                                                 --U2,
                                                  "Stay (Faraway, So
                                                   Close)"