Doc fixes.

9 files changed, 396 insertions, 337 deletions

diff --git a/awklib/eg/prog/alarm.awk b/awklib/eg/prog/alarm.awk
index 52fae393..af7e8af1 100644
--- a/awklib/eg/prog/alarm.awk
+++ b/awklib/eg/prog/alarm.awk
@@ -1,9 +1,10 @@
 # alarm.awk --- set an alarm
 #
-# Requires gettimeofday library function
+# Requires gettimeofday() library function
 #
 # Arnold Robbins, arnold@skeeve.com, Public Domain
 # May 1993
+# Revised December 2010
 
 # usage: alarm time [ "message" [ count [ delay ] ] ]
 
@@ -17,19 +18,24 @@ BEGIN    \
         print usage1 > "/dev/stderr"
         print usage2 > "/dev/stderr"
         exit 1
-    } else if (ARGC == 5) {
+    }
+    switch (ARGC) {
+    case 5:
         delay = ARGV[4] + 0
+	# fall through
+    case 4:
         count = ARGV[3] + 0
+	# fall through
+    case 3:
         message = ARGV[2]
-    } else if (ARGC == 4) {
-        count = ARGV[3] + 0
-        message = ARGV[2]
-    } else if (ARGC == 3) {
-        message = ARGV[2]
-    } else if (ARGV[1] !~ /[0-9]?[0-9]:[0-9][0-9]/) {
-        print usage1 > "/dev/stderr"
-        print usage2 > "/dev/stderr"
-        exit 1
+	break
+    default:
+        if (ARGV[1] !~ /[[:digit:]]?[[:digit:]]:[[:digit:]][[:digit:]]/) {
+            print usage1 > "/dev/stderr"
+            print usage2 > "/dev/stderr"
+            exit 1
+	}
+	break
     }
 
     # set defaults for once we reach the desired time
diff --git a/awklib/eg/prog/cut.awk b/awklib/eg/prog/cut.awk
index d9866b82..482ccd6e 100644
--- a/awklib/eg/prog/cut.awk
+++ b/awklib/eg/prog/cut.awk
@@ -35,7 +35,7 @@ BEGIN    \
         } else if (c == "d") {
             if (length(Optarg) > 1) {
                 printf("Using first character of %s" \
-                " for delimiter\n", Optarg) > "/dev/stderr"
+                       " for delimiter\n", Optarg) > "/dev/stderr"
                 Optarg = substr(Optarg, 1, 1)
             }
             FS = Optarg
@@ -48,6 +48,7 @@ BEGIN    \
             usage()
     }
 
+    # Clear out options
     for (i = 1; i < Optind; i++)
         ARGV[i] = ""
     if (by_fields && by_chars)
diff --git a/awklib/eg/prog/egrep.awk b/awklib/eg/prog/egrep.awk
index b34241f8..56d199c8 100644
--- a/awklib/eg/prog/egrep.awk
+++ b/awklib/eg/prog/egrep.awk
@@ -54,11 +54,12 @@ function beginfile(junk)
 }
 function endfile(file)
 {
-    if (! no_print && count_only)
+    if (! no_print && count_only) {
         if (do_filenames)
             print file ":" fcount
         else
             print fcount
+    }
 
     total += fcount
 }
diff --git a/awklib/eg/prog/split.awk b/awklib/eg/prog/split.awk
index 723d7a6a..c907530b 100644
--- a/awklib/eg/prog/split.awk
+++ b/awklib/eg/prog/split.awk
@@ -1,6 +1,6 @@
 # split.awk --- do split in awk
 #
-# Requires ord and chr library functions
+# Requires ord() and chr() library functions
 #
 # Arnold Robbins, arnold@skeeve.com, Public Domain
 # May 1993
@@ -14,7 +14,7 @@ BEGIN {
         usage()
 
     i = 1
-    if (ARGV[i] ~ /^-[0-9]+$/) {
+    if (ARGV[i] ~ /^-[[:digit:]]+$/) {
         count = -ARGV[i]
         ARGV[i] = ""
         i++
diff --git a/awklib/eg/prog/tee.awk b/awklib/eg/prog/tee.awk
index 82e80865..639b9f80 100644
--- a/awklib/eg/prog/tee.awk
+++ b/awklib/eg/prog/tee.awk
@@ -1,5 +1,8 @@
 # tee.awk --- tee in awk
 #
+# Copy standard input to all named output files.
+# Append content if -a option is supplied.
+#
 # Arnold Robbins, arnold@skeeve.com, Public Domain
 # May 1993
 # Revised December 1995
diff --git a/awklib/eg/prog/uniq.awk b/awklib/eg/prog/uniq.awk
index 0b2afa88..07d9b9e8 100644
--- a/awklib/eg/prog/uniq.awk
+++ b/awklib/eg/prog/uniq.awk
@@ -1,6 +1,6 @@
 # uniq.awk --- do uniq in awk
 #
-# Requires getopt and join library functions
+# Requires getopt() and join() library functions
 #
 # Arnold Robbins, arnold@skeeve.com, Public Domain
 # May 1993
@@ -14,7 +14,7 @@ function usage(    e)
 
 # -c    count lines. overrides -d and -u
 # -d    only repeated lines
-# -u    only non-repeated lines
+# -u    only nonrepeated lines
 # -n    skip n fields
 # +n    skip n characters, skip fields first
 
@@ -116,4 +116,5 @@ END {
     else if ((repeated_only && count > 1) ||
             (non_repeated_only && count == 1))
         print last > outputfile
+    close(outputfile)
 }
diff --git a/awklib/eg/prog/wc.awk b/awklib/eg/prog/wc.awk
index d51b9ff2..95940ae4 100644
--- a/awklib/eg/prog/wc.awk
+++ b/awklib/eg/prog/wc.awk
@@ -10,10 +10,10 @@
 #
 # Default is to count lines, words, characters
 #
-# Requires getopt and file transition library functions
+# Requires getopt() and file transition library functions
 
 BEGIN {
-    # let getopt print a message about
+    # let getopt() print a message about
     # invalid options. we ignore them
     while ((c = getopt(ARGC, ARGV, "lwc")) != -1) {
         if (c == "l")
diff --git a/doc/gawk.info b/doc/gawk.info
index 3c648bf4..78385ba5 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -15560,7 +15560,7 @@ language contributes to learning that language.  This major node
 continues that theme, presenting a potpourri of `awk' programs for your
 reading enjoyment.
 
-   Many of these programs use the library functions presented in *note
+   Many of these programs use library functions presented in *note
 Library Functions::.
 
 * Menu:
@@ -15598,11 +15598,11 @@ File: gawk.info,  Node: Clones,  Next: Miscellaneous Programs,  Prev: Running Ex
 13.2 Reinventing Wheels for Fun and Profit
 ==========================================
 
-This minor node presents a number of POSIX utilities that are
-implemented in `awk'.  Reinventing these programs in `awk' is often
-enjoyable, because the algorithms can be very clearly expressed, and
-the code is usually very concise and simple.  This is true because
-`awk' does so much for you.
+This minor node presents a number of POSIX utilities implemented in
+`awk'.  Reinventing these programs in `awk' is often enjoyable, because
+the algorithms can be very clearly expressed, and the code is usually
+very concise and simple.  This is true because `awk' does so much for
+you.
 
    It should be noted that these programs are not necessarily intended
 to replace the installed versions on your system.  Instead, their
@@ -15651,7 +15651,7 @@ pipeline generates a sorted, unique list of the logged-on users:
      Use LIST as the list of fields to cut out.
 
 `-d DELIM'
-     Use DELIM as the field-separator character instead of the tab
+     Use DELIM as the field-separator character instead of the TAB
      character.
 
 `-s'
@@ -15662,10 +15662,12 @@ function (*note Getopt Function::) and the `join()' library function
 (*note Join Function::).
 
    The program begins with a comment describing the options, the library
-functions needed, and a `usage' function that prints out a usage
-message and exits.  `usage' is called if invalid arguments are supplied:
+functions needed, and a `usage()' function that prints out a usage
+message and exits.  `usage()' is called if invalid arguments are
+supplied:
 
      # cut.awk --- implement cut in awk
+
      # Options:
      #    -f list     Cut fields
      #    -d c        Field delimiter character
@@ -15689,12 +15691,12 @@ on the screen.
 
    Next comes a `BEGIN' rule that parses the command-line options.  It
 sets `FS' to a single TAB character, because that is `cut''s default
-field separator.  The output field separator is also set to be the same
-as the input field separator.  Then `getopt()' is used to step through
-the command-line options.  Exactly one of the variables `by_fields' or
-`by_chars' is set to true, to indicate that processing should be done
-by fields or by characters, respectively.  When cutting by characters,
-the output field separator is set to the null string:
+field separator. The rule then sets the output field separator to be the
+same as the input field separator.  A loop using `getopt()' steps
+through the command-line options.  Exactly one of the variables
+`by_fields' or `by_chars' is set to true, to indicate that processing
+should be done by fields or by characters, respectively.  When cutting
+by characters, the output field separator is set to the null string:
 
      BEGIN    \
      {
@@ -15711,7 +15713,7 @@ the output field separator is set to the null string:
              } else if (c == "d") {
                  if (length(Optarg) > 1) {
                      printf("Using first character of %s" \
-                     " for delimiter\n", Optarg) > "/dev/stderr"
+                            " for delimiter\n", Optarg) > "/dev/stderr"
                      Optarg = substr(Optarg, 1, 1)
                  }
                  FS = Optarg
@@ -15724,22 +15726,23 @@ the output field separator is set to the null string:
                  usage()
          }
 
+         # Clear out options
          for (i = 1; i < Optind; i++)
              ARGV[i] = ""
 
-   Special care is taken when the field delimiter is a space.  Using a
-single space (`" "') for the value of `FS' is incorrect--`awk' would
-separate fields with runs of spaces, tabs, and/or newlines, and we want
-them to be separated with individual spaces.  Also remember that after
-`getopt()' is through (as described in *note Getopt Function::), we
-have to clear out all the elements of `ARGV' from 1 to `Optind', so
-that `awk' does not try to process the command-line options as file
-names.
+   The code must take special care when the field delimiter is a space.
+Using a single space (`" "') for the value of `FS' is incorrect--`awk'
+would separate fields with runs of spaces, TABs, and/or newlines, and
+we want them to be separated with individual spaces.  Also remember
+that after `getopt()' is through (as described in *note Getopt
+Function::), we have to clear out all the elements of `ARGV' from 1 to
+`Optind', so that `awk' does not try to process the command-line options
+as file names.
 
    After dealing with the command-line options, the program verifies
 that the options make sense.  Only one or the other of `-c' and `-f'
 should be used, and both require a field list.  Then the program calls
-either `set_fieldlist' or `set_charlist' to pull apart the list of
+either `set_fieldlist()' or `set_charlist()' to pull apart the list of
 fields or characters:
 
          if (by_fields && by_chars)
@@ -15759,13 +15762,14 @@ fields or characters:
              set_charlist()
      }
 
-   `set_fieldlist'  is used to split the field list apart at the commas
-and into an array.  Then, for each element of the array, it looks to
-see if it is actually a range, and if so, splits it apart. The range is
-verified to make sure the first number is smaller than the second.
-Each number in the list is added to the `flist' array, which simply
-lists the fields that will be printed.  Normal field splitting is used.
-The program lets `awk' handle the job of doing the field splitting:
+   `set_fieldlist()' splits the field list apart at the commas into an
+array.  Then, for each element of the array, it looks to see if the
+element is actually a range, and if so, splits it apart.  The function
+checks the range to make sure that the first number is smaller than the
+second.  Each number in the list is added to the `flist' array, which
+simply lists the fields that will be printed.  Normal field splitting
+is used.  The program lets `awk' handle the job of doing the field
+splitting:
 
      function set_fieldlist(        n, m, i, j, k, f, g)
      {
@@ -15787,10 +15791,10 @@ The program lets `awk' handle the job of doing the field splitting:
          nfields = j - 1
      }
 
-   The `set_charlist' function is more complicated than `set_fieldlist'.
-The idea here is to use `gawk''s `FIELDWIDTHS' variable (*note Constant
-Size::), which describes constant-width input.  When using a character
-list, that is exactly what we have.
+   The `set_charlist()' function is more complicated than
+`set_fieldlist()'.  The idea here is to use `gawk''s `FIELDWIDTHS'
+variable (*note Constant Size::), which describes constant-width input.
+When using a character list, that is exactly what we have.
 
    Setting up `FIELDWIDTHS' is more complicated than simply listing the
 fields that need to be printed.  We have to keep track of the fields to
@@ -15884,7 +15888,7 @@ File: gawk.info,  Node: Egrep Program,  Next: Id Program,  Prev: Cut Program,  U
 
 The `egrep' utility searches files for patterns.  It uses regular
 expressions that are almost identical to those available in `awk'
-(*note Regexp::).  It is used in the following manner:
+(*note Regexp::).  You invoke it as follows:
 
      egrep [ OPTIONS ] 'PATTERN' FILES ...
 
@@ -15931,6 +15935,7 @@ that processes the command-line arguments with `getopt()'.  The `-i'
 `IGNORECASE' built-in variable (*note Built-in Variables::):
 
      # egrep.awk --- simulate egrep in awk
+     #
      # Options:
      #    -c    count of lines
      #    -s    silent - use exit value
@@ -15996,9 +16001,9 @@ since it is not necessary with `gawk':
      #        $0 = tolower($0)
      #}
 
-   The `beginfile' function is called by the rule in `ftrans.awk' when
-each new file is processed.  In this case, it is very simple; all it
-does is initialize a variable `fcount' to zero. `fcount' tracks how
+   The `beginfile()' function is called by the rule in `ftrans.awk'
+when each new file is processed.  In this case, it is very simple; all
+it does is initialize a variable `fcount' to zero. `fcount' tracks how
 many lines in the current file matched the pattern (naming the
 parameter `junk' shows we know that `beginfile' is called with a
 parameter, but that we're not interested in its value):
@@ -16008,22 +16013,23 @@ parameter, but that we're not interested in its value):
          fcount = 0
      }
 
-   The `endfile' function is called after each file has been processed.
-It affects the output only when the user wants a count of the number of
-lines that matched.  `no_print' is true only if the exit status is
-desired.  `count_only' is true if line counts are desired.  `egrep'
-therefore only prints line counts if printing and counting are enabled.
-The output format must be adjusted depending upon the number of files to
-process.  Finally, `fcount' is added to `total', so that we know the
-total number of lines that matched the pattern:
+   The `endfile()' function is called after each file has been
+processed.  It affects the output only when the user wants a count of
+the number of lines that matched.  `no_print' is true only if the exit
+status is desired.  `count_only' is true if line counts are desired.
+`egrep' therefore only prints line counts if printing and counting are
+enabled.  The output format must be adjusted depending upon the number
+of files to process.  Finally, `fcount' is added to `total', so that we
+know the total number of lines that matched the pattern:
 
      function endfile(file)
      {
-         if (! no_print && count_only)
+         if (! no_print && count_only) {
              if (do_filenames)
                  print file ":" fcount
              else
                  print fcount
+         }
 
          total += fcount
      }
@@ -16080,7 +16086,7 @@ there are no matches, the exit status is one; otherwise it is zero:
          exit 0
      }
 
-   The `usage' function prints a usage message in case of invalid
+   The `usage()' function prints a usage message in case of invalid
 options, and then exits:
 
      function usage(    e)
@@ -16119,7 +16125,7 @@ different from the real ones.  If possible, `id' also supplies the
 corresponding user and group names.  The output might look like this:
 
      $ id
-     -| uid=2076(arnold) gid=10(staff) groups=10(staff),4(tty)
+     -| uid=500(arnold) gid=500(arnold) groups=6(disk),7(lp),19(floppy)
 
    This information is part of what is provided by `gawk''s `PROCINFO'
 array (*note Built-in Variables::).  However, the `id' utility provides
@@ -16220,7 +16226,7 @@ File: gawk.info,  Node: Split Program,  Next: Tee Program,  Prev: Id Program,  U
 -----------------------------------------
 
 The `split' program splits large text files into smaller pieces.  Usage
-is as follows:
+is as follows:(1)
 
      split [-COUNT] file [ PREFIX ]
 
@@ -16245,7 +16251,7 @@ output file names:
 
      # split.awk --- do split in awk
      #
-     # Requires ord and chr library functions
+     # Requires ord() and chr() library functions
      # usage: split [-num] [file] [outname]
 
      BEGIN {
@@ -16255,7 +16261,7 @@ output file names:
              usage()
 
          i = 1
-         if (ARGV[i] ~ /^-[0-9]+$/) {
+         if (ARGV[i] ~ /^-[[:digit:]]+$/) {
              count = -ARGV[i]
              ARGV[i] = ""
              i++
@@ -16300,7 +16306,7 @@ moves to the next letter in the alphabet and `s2' starts over again at
          print > out
      }
 
-The `usage' function simply prints an error message and exits:
+The `usage()' function simply prints an error message and exits:
 
      function usage(   e)
      {
@@ -16316,6 +16322,11 @@ close the last file instead of doing it in an `END' rule.  It also
 assumes that letters are contiguous in the character set, which isn't
 true for EBCDIC systems.
 
+   ---------- Footnotes ----------
+
+   (1) This is the traditional usage. The POSIX usage is different, but
+not relevant for what the program aims to demonstrate.
+
 
 File: gawk.info,  Node: Tee Program,  Next: Uniq Program,  Prev: Split Program,  Up: Clones
 
@@ -16342,8 +16353,11 @@ less than two, then no file names were supplied and `tee' prints a
 usage message and exits.  Finally, `awk' is forced to read the standard
 input by setting `ARGV[1]' to `"-"' and `ARGC' to two:
 
-   *FIXME: NEXT ED:* Add more leading commentary in this program 
      # tee.awk --- tee in awk
+     #
+     # Copy standard input to all named output files.
+     # Append content if -a option is supplied.
+     #
      BEGIN    \
      {
          for (i = 1; i < ARGC; i++)
@@ -16363,10 +16377,10 @@ input by setting `ARGV[1]' to `"-"' and `ARGC' to two:
          ARGC = 2
      }
 
-   The single rule does all the work.  Since there is no pattern, it is
-executed for each line of input.  The body of the rule simply prints the
-line into each file on the command line, and then to the standard
-output:
+   The following single rule does all the work.  Since there is no
+pattern, it is executed for each line of input.  The body of the rule
+simply prints the line into each file on the command line, and then to
+the standard output:
 
      {
          # moving the if outside the loop makes it run faster
@@ -16449,12 +16463,12 @@ provided.
    `uniq' uses the `getopt()' library function (*note Getopt Function::)
 and the `join()' library function (*note Join Function::).
 
-   The program begins with a `usage' function and then a brief outline
-of the options and their meanings in a comment.  The `BEGIN' rule deals
-with the command-line arguments and options. It uses a trick to get
-`getopt()' to handle options of the form `-25', treating such an option
-as the option letter `2' with an argument of `5'. If indeed two or more
-digits are supplied (`Optarg' looks like a number), `Optarg' is
+   The program begins with a `usage()' function and then a brief
+outline of the options and their meanings in comments.  The `BEGIN'
+rule deals with the command-line arguments and options. It uses a trick
+to get `getopt()' to handle options of the form `-25', treating such an
+option as the option letter `2' with an argument of `5'. If indeed two
+or more digits are supplied (`Optarg' looks like a number), `Optarg' is
 concatenated with the option digit and then the result is added to zero
 to make it into a number.  If there is only one digit in the option,
 then `Optarg' is not needed. In this case, `Optind' must be decremented
@@ -16468,7 +16482,8 @@ standard output, `/dev/stdout':
 
      # uniq.awk --- do uniq in awk
      #
-     # Requires getopt and join library functions
+     # Requires getopt() and join() library functions
+     #
      function usage(    e)
      {
          e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]"
@@ -16478,7 +16493,7 @@ standard output, `/dev/stdout':
 
      # -c    count lines. overrides -d and -u
      # -d    only repeated lines
-     # -u    only non-repeated lines
+     # -u    only nonrepeated lines
      # -n    skip n fields
      # +n    skip n characters, skip fields first
 
@@ -16524,10 +16539,10 @@ standard output, `/dev/stdout':
          }
      }
 
-   The following function, `are_equal', compares the current line,
+   The following function, `are_equal()', compares the current line,
 `$0', to the previous line, `last'.  It handles skipping fields and
 characters.  If no field count and no character count are specified,
-`are_equal' simply returns one or zero depending upon the result of a
+`are_equal()' simply returns one or zero depending upon the result of a
 simple string comparison of `last' and `$0'.  Otherwise, things get more
 complicated.  If fields have to be skipped, each line is broken into an
 array using `split()' (*note String Functions::); the desired fields
@@ -16536,7 +16551,7 @@ stored in `clast' and `cline'.  If no fields are skipped, `clast' and
 `cline' are set to `last' and `$0', respectively.  Finally, if
 characters are skipped, `substr()' is used to strip off the leading
 `charcount' characters in `clast' and `cline'.  The two strings are
-then compared and `are_equal' returns the result:
+then compared and `are_equal()' returns the result:
 
      function are_equal(    n, m, clast, cline, alast, aline)
      {
@@ -16566,7 +16581,7 @@ to `$0', so that subsequent lines of text have something to be compared
 to.
 
    The second rule does the work. The variable `equal' is one or zero,
-depending upon the results of `are_equal''s comparison. If `uniq' is
+depending upon the results of `are_equal()''s comparison. If `uniq' is
 counting repeated lines, and the lines are equal, then it increments
 the `count' variable.  Otherwise, it prints the line and resets `count',
 since the two lines are not equal.
@@ -16616,6 +16631,7 @@ line of input data:
          else if ((repeated_only && count > 1) ||
                  (non_repeated_only && count == 1))
              print last > outputfile
+         close(outputfile)
      }
 
 
@@ -16651,8 +16667,9 @@ a lot of the work for us; it splits lines into words (i.e., fields) and
 counts them, it counts lines (i.e., records), and it can easily tell us
 how long a line is.
 
-   This uses the `getopt()' library function (*note Getopt Function::)
-and the file-transition functions (*note Filetrans Function::).
+   This program uses the `getopt()' library function (*note Getopt
+Function::) and the file-transition functions (*note Filetrans
+Function::).
 
    This version has one notable difference from traditional versions of
 `wc': it always prints the counts in the order lines, words, and
@@ -16672,10 +16689,10 @@ line:
      #
      # Default is to count lines, words, characters
      #
-     # Requires getopt and file transition library functions
+     # Requires getopt() and file transition library functions
 
      BEGIN {
-         # let getopt print a message about
+         # let getopt() print a message about
          # invalid options. we ignore them
          while ((c = getopt(ARGC, ARGV, "lwc")) != -1) {
              if (c == "l")
@@ -16695,7 +16712,7 @@ line:
          print_total = (ARGC - i > 2)
      }
 
-   The `beginfile' function is simple; it just resets the counts of
+   The `beginfile()' function is simple; it just resets the counts of
 lines, words, and characters to zero, and saves the current file name in
 `fname':
 
@@ -16705,10 +16722,10 @@ lines, words, and characters to zero, and saves the current file name in
          fname = FILENAME
      }
 
-   The `endfile' function adds the current file's numbers to the running
-totals of lines, words, and characters.(1)  It then prints out those
-numbers for the file that was just read. It relies on `beginfile' to
-reset the numbers for the following data file:
+   The `endfile()' function adds the current file's numbers to the
+running totals of lines, words, and characters.(1)  It then prints out
+those numbers for the file that was just read. It relies on
+`beginfile()' to reset the numbers for the following data file:
 
      function endfile(file)
      {
@@ -16755,9 +16772,9 @@ this line:
 
    ---------- Footnotes ----------
 
-   (1) `wc' can't just use the value of `FNR' in `endfile'. If you
+   (1) `wc' can't just use the value of `FNR' in `endfile()'. If you
 examine the code in *note Filetrans Function::, you will see that `FNR'
-has already been reset by the time `endfile' is called.
+has already been reset by the time `endfile()' is called.
 
 
 File: gawk.info,  Node: Miscellaneous Programs,  Prev: Clones,  Up: Sample Programs
@@ -16857,12 +16874,14 @@ to print.  If the user supplied a message without the ASCII BEL
 character (known as the "alert" character, `"\a"'), then it is added to
 the message.  (On many systems, printing the ASCII BEL generates an
 audible alert. Thus when the alarm goes off, the system calls attention
-to itself in case the user is not looking at the computer or terminal.)
-Here is the program:
+to itself in case the user is not looking at the computer.)  Just for a
+change, this program uses a `switch' statement (*note Switch
+Statement::), but the processing could be done with a series of
+`if'-`else' statements instead.  Here is the program:
 
      # alarm.awk --- set an alarm
      #
-     # Requires gettimeofday library function
+     # Requires gettimeofday() library function
      # usage: alarm time [ "message" [ count [ delay ] ] ]
 
      BEGIN    \
@@ -16875,19 +16894,24 @@ Here is the program:
              print usage1 > "/dev/stderr"
              print usage2 > "/dev/stderr"
              exit 1
-         } else if (ARGC == 5) {
+         }
+         switch (ARGC) {
+         case 5:
              delay = ARGV[4] + 0
+     	# fall through
+         case 4:
              count = ARGV[3] + 0
+     	# fall through
+         case 3:
              message = ARGV[2]
-         } else if (ARGC == 4) {
-             count = ARGV[3] + 0
-             message = ARGV[2]
-         } else if (ARGC == 3) {
-             message = ARGV[2]
-         } else if (ARGV[1] !~ /[0-9]?[0-9]:[0-9][0-9]/) {
-             print usage1 > "/dev/stderr"
-             print usage2 > "/dev/stderr"
-             exit 1
+     	break
+         default:
+             if (ARGV[1] !~ /[[:digit:]]?[[:digit:]]:[[:digit:]][[:digit:]]/) {
+                 print usage1 > "/dev/stderr"
+                 print usage2 > "/dev/stderr"
+                 exit 1
+     	}
+     	break
          }
 
          # set defaults for once we reach the desired time
@@ -17077,9 +17101,9 @@ program.
 
    ---------- Footnotes ----------
 
-   (1) On some older System V systems, `tr' may require that the lists
-be written as range expressions enclosed in square brackets (`[a-z]')
-and quoted, to prevent the shell from attempting a file name expansion.
+   (1) On some older systems, `tr' may require that the lists be
+written as range expressions enclosed in square brackets (`[a-z]') and
+quoted, to prevent the shell from attempting a file name expansion.
 This is not a feature.
 
    (2) This program was written before `gawk' acquired the ability to
@@ -17607,12 +17631,12 @@ correct.  However, if the file did not end in text that matches `RS',
 `printf' (*note Printf::).
 
    The `BEGIN' rule handles the setup, checking for the right number of
-arguments and calling `usage' if there is a problem. Then it sets `RS'
-and `ORS' from the command-line arguments and sets `ARGV[1]' and
+arguments and calling `usage()' if there is a problem. Then it sets
+`RS' and `ORS' from the command-line arguments and sets `ARGV[1]' and
 `ARGV[2]' to the null string, so that they are not treated as file names
 (*note ARGC and ARGV::).
 
-   The `usage' function prints an error message and exits.  Finally,
+   The `usage()' function prints an error message and exits.  Finally,
 the single rule handles the printing scheme outlined above, using
 `print' or `printf' as appropriate, depending upon the value of `RT'.
 
@@ -18254,8 +18278,8 @@ we wrote:
 problem like this is to put a breakpoint in the program so that we can
 watch it at work and catch what it is doing wrong.  A reasonable spot
 for a breakpoint in `uniq.awk' is at the beginning of the function
-`are_equal', which compares the current line with the previous one. To
-set the breakpoint, use the `b' (breakpoint) command:
+`are_equal()', which compares the current line with the previous one.
+To set the breakpoint, use the `b' (breakpoint) command:
 
      dgawk> b are_equal
      -| Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64
@@ -18280,15 +18304,15 @@ current stack frames:
      -| #0  are_equal(n, m, clast, cline, alast, aline) at `awklib/eg/prog/uniq.awk':69
      -| #1  in main() at `awklib/eg/prog/uniq.awk':89
 
-   This tells us that `are_equal' was called by the main program at
+   This tells us that `are_equal()' was called by the main program at
 line 89 of `uniq.awk'.  (This is not a big surprise, since this is the
-only call to `are_equal' in the program, but in more complex programs,
-knowing who called a function and with what parameters can be the key
-to finding the source of the problem.)
+only call to `are_equal()' in the program, but in more complex
+programs, knowing who called a function and with what parameters can be
+the key to finding the source of the problem.)
 
-   Now that we're in `are_equal', we can start looking at the values of
-some variables.  Let's say we type `p n' (`p' is short for "print").
-We would expect to see the value of `n', a parameter to `are_equal'.
+   Now that we're in `are_equal()', we can start looking at the values
+of some variables.  Let's say we type `p n' (`p' is short for "print").
+We would expect to see the value of `n', a parameter to `are_equal()'.
 Actually, `dgawk' gives us:
 
      dgawk> p n
@@ -18308,9 +18332,9 @@ our test input above.  Let's look at `NR':
      dgawk> p NR
      -| NR = number (2)
 
-So we can see that `are_equal' was only called for the second record of
-the file.  Of course, this is because our program contained a rule for
-`NR == 1':
+So we can see that `are_equal()' was only called for the second record
+of the file.  Of course, this is because our program contained a rule
+for `NR == 1':
 
      NR == 1 {
          last = $0
@@ -18323,10 +18347,10 @@ the file.  Of course, this is because our program contained a rule for
      -| last = string ("awk is a wonderful program!")
 
    Everything we have done so far has verified that the program has
-worked as planned, up to and including the call to `are_equal', so the
-problem must be inside this function.  To investigate further, we have
-to begin "stepping through" the lines of `are_equal'.  We start by
-typing `n' (for "next"):
+worked as planned, up to and including the call to `are_equal()', so
+the problem must be inside this function.  To investigate further, we
+have to begin "stepping through" the lines of `are_equal()'.  We start
+by typing `n' (for "next"):
 
      dgawk> n
      -| 67          if (fcount > 0) {
@@ -24458,7 +24482,7 @@ Index
 * Menu:
 
 * ! (exclamation point), !  operator:    Boolean Ops.         (line  67)
-* ! (exclamation point), ! operator <1>: Egrep Program.       (line 160)
+* ! (exclamation point), ! operator <1>: Egrep Program.       (line 162)
 * ! (exclamation point), ! operator:     Precedence.          (line  52)
 * ! (exclamation point), != operator <1>: Precedence.         (line  65)
 * ! (exclamation point), != operator:    Comparison Operators.
@@ -24472,7 +24496,7 @@ Index
 * ! (exclamation point), !~ operator <5>: Computed Regexps.   (line   6)
 * ! (exclamation point), !~ operator <6>: Case-sensitivity.   (line  26)
 * ! (exclamation point), !~ operator:    Regexp Usage.        (line  19)
-* ! operator <1>:                        Egrep Program.       (line 168)
+* ! operator <1>:                        Egrep Program.       (line 170)
 * ! operator:                            Ranges.              (line  48)
 * " (double quote) <1>:                  Quoting.             (line  37)
 * " (double quote):                      Read Terminal.       (line  25)
@@ -24689,7 +24713,7 @@ Index
                                                               (line  38)
 * \ (backslash), as field separators:    Command Line Field Separator.
                                                               (line  27)
-* \ (backslash), continuing lines and <1>: Egrep Program.     (line 218)
+* \ (backslash), continuing lines and <1>: Egrep Program.     (line 220)
 * \ (backslash), continuing lines and:   Statements/Lines.    (line  19)
 * \ (backslash), continuing lines and, comments and: Statements/Lines.
                                                               (line  75)
@@ -24755,7 +24779,7 @@ Index
 * Aho, Alfred <1>:                       Contributors.        (line  12)
 * Aho, Alfred:                           History.             (line  17)
 * alarm clock example program:           Alarm Program.       (line   9)
-* alarm.awk program:                     Alarm Program.       (line  27)
+* alarm.awk program:                     Alarm Program.       (line  29)
 * algorithms:                            Basic High Level.    (line  68)
 * Alpha (DEC):                           Manual History.      (line  28)
 * amazing awk assembler (aaa):           Glossary.            (line  12)
@@ -24944,7 +24968,7 @@ Index
                                                               (line  38)
 * backslash (\), as field separators:    Command Line Field Separator.
                                                               (line  27)
-* backslash (\), continuing lines and <1>: Egrep Program.     (line 218)
+* backslash (\), continuing lines and <1>: Egrep Program.     (line 220)
 * backslash (\), continuing lines and:   Statements/Lines.    (line  19)
 * backslash (\), continuing lines and, comments and: Statements/Lines.
                                                               (line  75)
@@ -24980,7 +25004,7 @@ Index
 * BEGIN pattern, pgawk program:          Profiling.           (line  65)
 * BEGIN pattern, print statement and:    I/O And BEGIN/END.   (line  16)
 * BEGIN pattern, pwcat program:          Passwd Functions.    (line 144)
-* BEGIN pattern, running awk programs and: Cut Program.       (line  66)
+* BEGIN pattern, running awk programs and: Cut Program.       (line  68)
 * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n.    (line  59)
 * BEGINFILE pattern, Boolean patterns and: Expression Patterns.
                                                               (line  73)
@@ -25185,7 +25209,7 @@ Index
 * custom.h file:                         Configuration Philosophy.
                                                               (line  29)
 * cut utility:                           Cut Program.         (line   6)
-* cut.awk program:                       Cut Program.         (line  44)
+* cut.awk program:                       Cut Program.         (line  45)
 * d debugger command (alias for break):  Breakpoint Control.  (line  57)
 * d.c., See dark corner:                 Conventions.         (line  37)
 * dark corner <1>:                       Glossary.            (line 187)
@@ -25474,7 +25498,7 @@ Index
 * END pattern:                           BEGIN/END.           (line   6)
 * END pattern, assert() user-defined function and: Assert Function.
                                                               (line  75)
-* END pattern, backslash continuation and: Egrep Program.     (line 218)
+* END pattern, backslash continuation and: Egrep Program.     (line 220)
 * END pattern, Boolean patterns and:     Expression Patterns. (line  73)
 * END pattern, exit statement and:       Exit Statement.      (line  12)
 * END pattern, next/nextfile statements and <1>: Next Statement.
@@ -25516,7 +25540,7 @@ Index
 * evaluation order, concatenation:       Concatenation.       (line  42)
 * evaluation order, functions:           Calling Built-in.    (line  30)
 * examining fields:                      Fields.              (line   6)
-* exclamation point (!), ! operator <1>: Egrep Program.       (line 160)
+* exclamation point (!), ! operator <1>: Egrep Program.       (line 162)
 * exclamation point (!), ! operator <2>: Precedence.          (line  52)
 * exclamation point (!), ! operator:     Boolean Ops.         (line  67)
 * exclamation point (!), != operator <1>: Precedence.         (line  65)
@@ -25585,7 +25609,7 @@ Index
                                                               (line   6)
 * field separators, regular expressions as: Field Separators. (line  50)
 * field separators, See Also OFS:        Changing Fields.     (line  64)
-* field separators, spaces as:           Cut Program.         (line 106)
+* field separators, spaces as:           Cut Program.         (line 109)
 * fields <1>:                            Basic High Level.    (line  73)
 * fields <2>:                            Fields.              (line   6)
 * fields:                                Reading Files.       (line  14)
@@ -25707,7 +25731,7 @@ Index
                                                               (line  20)
 * FS variable, as TAB character:         Options.             (line 218)
 * FS variable, changing value of:        Field Separators.    (line  34)
-* FS variable, running awk programs and: Cut Program.         (line  66)
+* FS variable, running awk programs and: Cut Program.         (line  68)
 * FS variable, setting from command line: Command Line Field Separator.
                                                               (line   6)
 * FS, containing ^:                      Regexp Field Splitting.
@@ -26765,7 +26789,7 @@ Index
                                                               (line   6)
 * single-precision floating-point:       Basic Data Typing.   (line  33)
 * Skywalker, Luke:                       Undocumented.        (line   6)
-* sleep utility:                         Alarm Program.       (line 102)
+* sleep utility:                         Alarm Program.       (line 109)
 * Solaris, POSIX compliant awk:          Other Versions.      (line 101)
 * sort function, arrays, sorting:        Array Sorting.       (line   6)
 * sort utility:                          Word Sorting.        (line  56)
@@ -27044,7 +27068,7 @@ Index
 * watch debugger command:                Viewing And Changing Data.
                                                               (line  67)
 * wc utility:                            Wc Program.          (line   6)
-* wc.awk program:                        Wc Program.          (line  45)
+* wc.awk program:                        Wc Program.          (line  46)
 * Weinberger, Peter <1>:                 Contributors.        (line  12)
 * Weinberger, Peter:                     History.             (line  17)
 * while statement <1>:                   While Statement.     (line   6)
@@ -27392,119 +27416,120 @@ Node: Passwd Functions618133
 Ref: Passwd Functions-Footnote-1627121
 Node: Group Functions627209
 Node: Sample Programs635289
-Node: Running Examples635958
-Node: Clones636686
-Node: Cut Program637818
-Node: Egrep Program647585
-Ref: Egrep Program-Footnote-1655339
-Node: Id Program655449
-Node: Split Program659056
-Node: Tee Program662524
-Node: Uniq Program665267
-Node: Wc Program672644
-Ref: Wc Program-Footnote-1676890
-Node: Miscellaneous Programs677086
-Node: Dupword Program678206
-Node: Alarm Program680237
-Node: Translate Program684781
-Ref: Translate Program-Footnote-1689160
-Ref: Translate Program-Footnote-2689397
-Node: Labels Program689531
-Ref: Labels Program-Footnote-1692822
-Node: Word Sorting692906
-Node: History Sorting697253
-Node: Extract Program699091
-Node: Simple Sed706454
-Node: Igawk Program709511
-Ref: Igawk Program-Footnote-1724246
-Ref: Igawk Program-Footnote-2724447
-Node: Signature Program724585
-Node: Debugger725665
-Node: Debugging726541
-Node: Debugging Concepts726855
-Node: Debugging Terms728708
-Node: Awk Debugging731256
-Node: Sample dgawk session732148
-Node: dgawk invocation732640
-Node: Finding The Bug733824
-Node: List of Debugger Commands740339
-Node: Breakpoint Control741654
-Node: Dgawk Execution Control744864
-Node: Viewing And Changing Data748213
-Node: Dgawk Stack751509
-Node: Dgawk Info752970
-Node: Miscellaneous Dgawk Commands756908
-Node: Readline Support762624
-Node: Dgawk Limitations763440
-Node: Language History765612
-Node: V7/SVR3.1766989
-Node: SVR4769284
-Node: POSIX770729
-Node: BTL772441
-Node: POSIX/GNU774131
-Node: Contributors783878
-Node: Installation787487
-Node: Gawk Distribution788458
-Node: Getting788942
-Node: Extracting789768
-Node: Distribution contents791156
-Node: Unix Installation796229
-Node: Quick Installation796820
-Node: Additional Configuration Options798522
-Node: Configuration Philosophy800285
-Node: Non-Unix Installation802649
-Node: PC Installation803114
-Node: PC Binary Installation804420
-Node: PC Compiling806263
-Node: PC Dynamic810768
-Node: PC Using813131
-Node: Cygwin817679
-Node: MSYS818663
-Node: VMS Installation819169
-Node: VMS Compilation819773
-Node: VMS Installation Details821350
-Node: VMS Running822980
-Node: VMS POSIX824577
-Node: VMS Old Gawk825875
-Node: Unsupported826344
-Node: Atari Installation826806
-Node: Atari Compiling828093
-Node: Atari Using829982
-Node: BeOS Installation832829
-Node: Tandem Installation833974
-Node: Bugs835653
-Node: Other Versions839485
-Node: Notes844707
-Node: Compatibility Mode845399
-Node: Additions846182
-Node: Adding Code846932
-Node: New Ports852984
-Node: Dynamic Extensions857116
-Node: Internals858497
-Node: Plugin License868902
-Node: Sample Library869536
-Node: Internal File Description870200
-Node: Internal File Ops873895
-Ref: Internal File Ops-Footnote-1878771
-Node: Using Internal File Ops878919
-Node: Future Extensions880944
-Node: Basic Concepts884981
-Node: Basic High Level885738
-Ref: Basic High Level-Footnote-1889857
-Node: Basic Data Typing890051
-Node: Floating Point Issues894488
-Node: String Conversion Precision895571
-Ref: String Conversion Precision-Footnote-1897265
-Node: Unexpected Results897374
-Node: POSIX Floating Point Problems899200
-Ref: POSIX Floating Point Problems-Footnote-1902899
-Node: Glossary902937
-Node: Copying926720
-Node: GNU Free Documentation License964277
-Node: next-edition989421
-Node: unresolved989773
-Node: revision990273
-Node: consistency990696
-Node: Index994049
+Node: Running Examples635954
+Node: Clones636682
+Node: Cut Program637805
+Node: Egrep Program647646
+Ref: Egrep Program-Footnote-1655417
+Node: Id Program655527
+Node: Split Program659143
+Ref: Split Program-Footnote-1662662
+Node: Tee Program662790
+Node: Uniq Program665593
+Node: Wc Program673016
+Ref: Wc Program-Footnote-1677280
+Node: Miscellaneous Programs677480
+Node: Dupword Program678600
+Node: Alarm Program680631
+Node: Translate Program685353
+Ref: Translate Program-Footnote-1689732
+Ref: Translate Program-Footnote-2689960
+Node: Labels Program690094
+Ref: Labels Program-Footnote-1693385
+Node: Word Sorting693469
+Node: History Sorting697816
+Node: Extract Program699654
+Node: Simple Sed707017
+Node: Igawk Program710078
+Ref: Igawk Program-Footnote-1724813
+Ref: Igawk Program-Footnote-2725014
+Node: Signature Program725152
+Node: Debugger726232
+Node: Debugging727108
+Node: Debugging Concepts727422
+Node: Debugging Terms729275
+Node: Awk Debugging731823
+Node: Sample dgawk session732715
+Node: dgawk invocation733207
+Node: Finding The Bug734391
+Node: List of Debugger Commands740922
+Node: Breakpoint Control742237
+Node: Dgawk Execution Control745447
+Node: Viewing And Changing Data748796
+Node: Dgawk Stack752092
+Node: Dgawk Info753553
+Node: Miscellaneous Dgawk Commands757491
+Node: Readline Support763207
+Node: Dgawk Limitations764023
+Node: Language History766195
+Node: V7/SVR3.1767572
+Node: SVR4769867
+Node: POSIX771312
+Node: BTL773024
+Node: POSIX/GNU774714
+Node: Contributors784461
+Node: Installation788070
+Node: Gawk Distribution789041
+Node: Getting789525
+Node: Extracting790351
+Node: Distribution contents791739
+Node: Unix Installation796812
+Node: Quick Installation797403
+Node: Additional Configuration Options799105
+Node: Configuration Philosophy800868
+Node: Non-Unix Installation803232
+Node: PC Installation803697
+Node: PC Binary Installation805003
+Node: PC Compiling806846
+Node: PC Dynamic811351
+Node: PC Using813714
+Node: Cygwin818262
+Node: MSYS819246
+Node: VMS Installation819752
+Node: VMS Compilation820356
+Node: VMS Installation Details821933
+Node: VMS Running823563
+Node: VMS POSIX825160
+Node: VMS Old Gawk826458
+Node: Unsupported826927
+Node: Atari Installation827389
+Node: Atari Compiling828676
+Node: Atari Using830565
+Node: BeOS Installation833412
+Node: Tandem Installation834557
+Node: Bugs836236
+Node: Other Versions840068
+Node: Notes845290
+Node: Compatibility Mode845982
+Node: Additions846765
+Node: Adding Code847515
+Node: New Ports853567
+Node: Dynamic Extensions857699
+Node: Internals859080
+Node: Plugin License869485
+Node: Sample Library870119
+Node: Internal File Description870783
+Node: Internal File Ops874478
+Ref: Internal File Ops-Footnote-1879354
+Node: Using Internal File Ops879502
+Node: Future Extensions881527
+Node: Basic Concepts885564
+Node: Basic High Level886321
+Ref: Basic High Level-Footnote-1890440
+Node: Basic Data Typing890634
+Node: Floating Point Issues895071
+Node: String Conversion Precision896154
+Ref: String Conversion Precision-Footnote-1897848
+Node: Unexpected Results897957
+Node: POSIX Floating Point Problems899783
+Ref: POSIX Floating Point Problems-Footnote-1903482
+Node: Glossary903520
+Node: Copying927303
+Node: GNU Free Documentation License964860
+Node: next-edition990004
+Node: unresolved990356
+Node: revision990856
+Node: consistency991279
+Node: Index994632
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index dbda87d5..aea4bf9f 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -21129,7 +21129,7 @@ problems.  Many of the programs are short, which emphasizes @command{awk}'s
 ability to do a lot in just a few lines of code.
 @end ifnotinfo
 
-Many of these programs use the library functions presented in
+Many of these programs use library functions presented in
 @ref{Library Functions}.
 
 @menu
@@ -21171,7 +21171,7 @@ cut.awk -- -c1-8 myfiles > results
 @c STARTOFRANGE posimawk
 @cindex POSIX, programs@comma{} implementing in @command{awk}
 
-This @value{SECTION} presents a number of POSIX utilities that are implemented in
+This @value{SECTION} presents a number of POSIX utilities implemented in
 @command{awk}.  Reinventing these programs in @command{awk} is often enjoyable,
 because the algorithms can be very clearly expressed, and the code is usually
 very concise and simple.  This is true because @command{awk} does so much for you.
@@ -21231,7 +21231,7 @@ dashes.  The list @samp{1-8,15,22-35} specifies characters 1 through
 Use @var{list} as the list of fields to cut out.
 
 @item -d @var{delim}
-Use @var{delim} as the field-separator character instead of the tab
+Use @var{delim} as the field-separator character instead of the TAB
 character.
 
 @item -s
@@ -21244,8 +21244,8 @@ and the @code{join()} library function
 (@pxref{Join Function}).
 
 The program begins with a comment describing the options, the library
-functions needed, and a @code{usage} function that prints out a usage
-message and exits.  @code{usage} is called if invalid arguments are
+functions needed, and a @code{usage()} function that prints out a usage
+message and exits.  @code{usage()} is called if invalid arguments are
 supplied:
 
 @cindex @code{cut.awk} program
@@ -21258,10 +21258,10 @@ supplied:
 #
 # Arnold Robbins, arnold@@skeeve.com, Public Domain
 # May 1993
-
 @c endfile
 @end ignore
 @c file eg/prog/cut.awk
+
 # Options:
 #    -f list     Cut fields
 #    -d c        Field delimiter character
@@ -21298,8 +21298,8 @@ screen.
 @cindex @code{FS} variable, running @command{awk} programs and
 Next comes a @code{BEGIN} rule that parses the command-line options.
 It sets @code{FS} to a single TAB character, because that is @command{cut}'s
-default field separator.  The output field separator is also set to be the
-same as the input field separator.  Then @code{getopt()} is used to step
+default field separator. The rule then sets the output field separator to be the
+same as the input field separator.  A loop using @code{getopt()} steps
 through the command-line options.  Exactly one of the variables
 @code{by_fields} or @code{by_chars} is set to true, to indicate that
 processing should be done by fields or by characters, respectively.
@@ -21323,7 +21323,7 @@ BEGIN    \
         @} else if (c == "d") @{
             if (length(Optarg) > 1) @{
                 printf("Using first character of %s" \
-                " for delimiter\n", Optarg) > "/dev/stderr"
+                       " for delimiter\n", Optarg) > "/dev/stderr"
                 Optarg = substr(Optarg, 1, 1)
             @}
             FS = Optarg
@@ -21336,16 +21336,18 @@ BEGIN    \
             usage()
     @}
 
+    # Clear out options
     for (i = 1; i < Optind; i++)
         ARGV[i] = ""
 @c endfile
 @end example
 
 @cindex field separators, spaces as
-Special care is taken when the field delimiter is a space.  Using
+The code must take
+special care when the field delimiter is a space.  Using
 a single space (@code{@w{" "}}) for the value of @code{FS} is
 incorrect---@command{awk} would separate fields with runs of spaces,
-tabs, and/or newlines, and we want them to be separated with individual
+TABs, and/or newlines, and we want them to be separated with individual
 spaces.  Also remember that after @code{getopt()} is through
 (as described in @ref{Getopt Function}),
 we have to
@@ -21356,7 +21358,7 @@ as @value{FN}s.
 After dealing with the command-line options, the program verifies that the
 options make sense.  Only one or the other of @option{-c} and @option{-f}
 should be used, and both require a field list.  Then the program calls
-either @code{set_fieldlist} or @code{set_charlist} to pull apart the
+either @code{set_fieldlist()} or @code{set_charlist()} to pull apart the
 list of fields or characters:
 
 @example
@@ -21380,10 +21382,11 @@ list of fields or characters:
 @c endfile
 @end example
 
-@code{set_fieldlist}  is used to split the field list apart at the commas
-and into an array.  Then, for each element of the array, it looks to
-see if it is actually a range, and if so, splits it apart. The range
-is verified to make sure the first number is smaller than the second.
+@code{set_fieldlist()} splits the field list apart at the commas
+into an array.  Then, for each element of the array, it looks to
+see if the element is actually a range, and if so, splits it apart.
+The function checks the range
+to make sure that the first number is smaller than the second.
 Each number in the list is added to the @code{flist} array, which
 simply lists the fields that will be printed.  Normal field splitting
 is used.  The program lets @command{awk} handle the job of doing the
@@ -21415,7 +21418,8 @@ function set_fieldlist(        n, m, i, j, k, f, g)
 @c endfile
 @end example
 
-The @code{set_charlist} function is more complicated than @code{set_fieldlist}.
+The @code{set_charlist()} function is more complicated than
+@code{set_fieldlist()}.
 The idea here is to use @command{gawk}'s @code{FIELDWIDTHS} variable
 (@pxref{Constant Size}),
 which describes constant-width input.  When using a character list, that is
@@ -21537,7 +21541,7 @@ of picking the input line apart by characters.
 The @command{egrep} utility searches files for patterns.  It uses regular
 expressions that are almost identical to those available in @command{awk}
 (@pxref{Regexp}).
-It is used in the following manner:
+You invoke it as follows:
 
 @example
 egrep @r{[} @var{options} @r{]} '@var{pattern}' @var{files} @dots{}
@@ -21592,10 +21596,10 @@ that processes the command-line arguments with @code{getopt()}.  The @option{-i}
 @example
 @c file eg/prog/egrep.awk
 # egrep.awk --- simulate egrep in awk
+#
 @c endfile
 @ignore
 @c file eg/prog/egrep.awk
-#
 # Arnold Robbins, arnold@@skeeve.com, Public Domain
 # May 1993
 
@@ -21682,7 +21686,7 @@ commented out since it is not necessary with @command{gawk}:
 @c endfile
 @end example
 
-The @code{beginfile} function is called by the rule in @file{ftrans.awk}
+The @code{beginfile()} function is called by the rule in @file{ftrans.awk}
 when each new file is processed.  In this case, it is very simple; all it
 does is initialize a variable @code{fcount} to zero. @code{fcount} tracks
 how many lines in the current file matched the pattern
@@ -21698,7 +21702,7 @@ function beginfile(junk)
 @c endfile
 @end example
 
-The @code{endfile} function is called after each file has been processed.
+The @code{endfile()} function is called after each file has been processed.
 It affects the output only when the user wants a count of the number of lines that
 matched.  @code{no_print} is true only if the exit status is desired.
 @code{count_only} is true if line counts are desired.  @command{egrep}
@@ -21711,11 +21715,12 @@ know the total number of lines that matched the pattern:
 @c file eg/prog/egrep.awk
 function endfile(file)
 @{
-    if (! no_print && count_only)
+    if (! no_print && count_only) @{
         if (do_filenames)
             print file ":" fcount
         else
             print fcount
+    @}
 
     total += fcount
 @}
@@ -21786,7 +21791,7 @@ END    \
 @c endfile
 @end example
 
-The @code{usage} function prints a usage message in case of invalid options,
+The @code{usage()} function prints a usage message in case of invalid options,
 and then exits:
 
 @example
@@ -21832,8 +21837,8 @@ different from the real ones.  If possible, @command{id} also supplies the
 corresponding user and group names.  The output might look like this:
 
 @example
-$ id
-@print{} uid=2076(arnold) gid=10(staff) groups=10(staff),4(tty)
+$ @kbd{id}
+@print{} uid=500(arnold) gid=500(arnold) groups=6(disk),7(lp),19(floppy)
 @end example
 
 This information is part of what is provided by @command{gawk}'s
@@ -21967,7 +21972,9 @@ arguments and perform in the same way.
 @cindex files, splitting
 @cindex @code{split} utility
 The @command{split} program splits large text files into smaller pieces.
-Usage is as follows:
+Usage is as follows:@footnote{This is the traditional usage. The
+POSIX usage is different, but not relevant for what the program
+aims to demonstrate.}
 
 @example
 split @r{[}-@var{count}@r{]} file @r{[} @var{prefix} @r{]}
@@ -21998,7 +22005,7 @@ is used as the prefix for the output @value{FN}s:
 @c file eg/prog/split.awk
 # split.awk --- do split in awk
 #
-# Requires ord and chr library functions
+# Requires ord() and chr() library functions
 @c endfile
 @ignore
 @c file eg/prog/split.awk
@@ -22018,7 +22025,7 @@ BEGIN @{
         usage()
 
     i = 1
-    if (ARGV[i] ~ /^-[0-9]+$/) @{
+    if (ARGV[i] ~ /^-[[:digit:]]+$/) @{
         count = -ARGV[i]
         ARGV[i] = ""
         i++
@@ -22075,7 +22082,7 @@ moves to the next letter in the alphabet and @code{s2} starts over again at
 @c Exercise: do this with just awk builtin functions, index("abc..."), substr, etc.
 
 @noindent
-The @code{usage} function simply prints an error message and exits:
+The @code{usage()} function simply prints an error message and exits:
 
 @example
 @c file eg/prog/split.awk
@@ -22102,6 +22109,8 @@ This program is a bit sloppy; it relies on @command{awk} to automatically close
 instead of doing it in an @code{END} rule.
 It also assumes that letters are contiguous in the character set,
 which isn't true for EBCDIC systems.
+
+@c Exercise: Fix these problems.
 @c BFD...
 @c ENDOFRANGE filspl
 
@@ -22136,15 +22145,17 @@ If the first argument is @option{-a}, then the flag variable
 Finally, @command{awk} is forced to read the standard input by setting
 @code{ARGV[1]} to @code{"-"} and @code{ARGC} to two:
 
-@strong{FIXME: NEXT ED:} Add more leading commentary in this program
 @cindex @code{tee.awk} program
 @example
 @c file eg/prog/tee.awk
 # tee.awk --- tee in awk
+#
+# Copy standard input to all named output files.
+# Append content if -a option is supplied.
+#
 @c endfile
 @ignore
 @c file eg/prog/tee.awk
-#
 # Arnold Robbins, arnold@@skeeve.com, Public Domain
 # May 1993
 # Revised December 1995
@@ -22173,7 +22184,7 @@ BEGIN    \
 @c endfile
 @end example
 
-The single rule does all the work.  Since there is no pattern, it is
+The following single rule does all the work.  Since there is no pattern, it is
 executed for each line of input.  The body of the rule simply prints the
 line into each file on the command line, and then to the standard output:
 
@@ -22280,8 +22291,8 @@ Normally @command{uniq} behaves as if both the @option{-d} and
 and the @code{join()} library function
 (@pxref{Join Function}).
 
-The program begins with a @code{usage} function and then a brief outline of
-the options and their meanings in a comment.
+The program begins with a @code{usage()} function and then a brief outline of
+the options and their meanings in comments.
 The @code{BEGIN} rule deals with the command-line arguments and options. It
 uses a trick to get @code{getopt()} to handle options of the form @samp{-25},
 treating such an option as the option letter @samp{2} with an argument of
@@ -22304,12 +22315,12 @@ standard output, @file{/dev/stdout}:
 @group
 # uniq.awk --- do uniq in awk
 #
-# Requires getopt and join library functions
+# Requires getopt() and join() library functions
+#
 @end group
 @c endfile
 @ignore
 @c file eg/prog/uniq.awk
-#
 # Arnold Robbins, arnold@@skeeve.com, Public Domain
 # May 1993
 
@@ -22325,7 +22336,7 @@ function usage(    e)
 
 # -c    count lines. overrides -d and -u
 # -d    only repeated lines
-# -u    only non-repeated lines
+# -u    only nonrepeated lines
 # -n    skip n fields
 # +n    skip n characters, skip fields first
 
@@ -22373,10 +22384,10 @@ BEGIN   \
 @c endfile
 @end example
 
-The following function, @code{are_equal}, compares the current line,
+The following function, @code{are_equal()}, compares the current line,
 @code{$0}, to the
 previous line, @code{last}.  It handles skipping fields and characters.
-If no field count and no character count are specified, @code{are_equal}
+If no field count and no character count are specified, @code{are_equal()}
 simply returns one or zero depending upon the result of a simple string
 comparison of @code{last} and @code{$0}.  Otherwise, things get more
 complicated.
@@ -22389,7 +22400,7 @@ If no fields are skipped, @code{clast} and @code{cline} are set to
 @code{last} and @code{$0}, respectively.
 Finally, if characters are skipped, @code{substr()} is used to strip off the
 leading @code{charcount} characters in @code{clast} and @code{cline}.  The
-two strings are then compared and @code{are_equal} returns the result:
+two strings are then compared and @code{are_equal()} returns the result:
 
 @example
 @c file eg/prog/uniq.awk
@@ -22422,7 +22433,7 @@ executed only for the very first line of data.  It sets @code{last} equal to
 @code{$0}, so that subsequent lines of text have something to be compared to.
 
 The second rule does the work. The variable @code{equal} is one or zero,
-depending upon the results of @code{are_equal}'s comparison. If @command{uniq}
+depending upon the results of @code{are_equal()}'s comparison. If @command{uniq}
 is counting repeated lines, and the lines are equal, then it increments the @code{count} variable.
 Otherwise, it prints the line and resets @code{count},
 since the two lines are not equal.
@@ -22475,6 +22486,7 @@ END @{
     else if ((repeated_only && count > 1) ||
             (non_repeated_only && count == 1))
         print last > outputfile
+    close(outputfile)
 @}
 @c endfile
 @end example
@@ -22525,7 +22537,7 @@ since @command{awk} does a lot of the work for us; it splits lines into
 words (i.e., fields) and counts them, it counts lines (i.e., records),
 and it can easily tell us how long a line is.
 
-This uses the @code{getopt()} library function
+This program uses the @code{getopt()} library function
 (@pxref{Getopt Function})
 and the file-transition functions
 (@pxref{Filetrans Function}).
@@ -22561,10 +22573,10 @@ command line:
 #
 # Default is to count lines, words, characters
 #
-# Requires getopt and file transition library functions
+# Requires getopt() and file transition library functions
 
 BEGIN @{
-    # let getopt print a message about
+    # let getopt() print a message about
     # invalid options. we ignore them
     while ((c = getopt(ARGC, ARGV, "lwc")) != -1) @{
         if (c == "l")
@@ -22586,7 +22598,7 @@ BEGIN @{
 @c endfile
 @end example
 
-The @code{beginfile} function is simple; it just resets the counts of lines,
+The @code{beginfile()} function is simple; it just resets the counts of lines,
 words, and characters to zero, and saves the current @value{FN} in
 @code{fname}:
 
@@ -22600,17 +22612,18 @@ function beginfile(file)
 @c endfile
 @end example
 
-The @code{endfile} function adds the current file's numbers to the running
+The @code{endfile()} function adds the current file's numbers to the running
 totals of lines, words, and characters.@footnote{@command{wc} can't just use the value of
-@code{FNR} in @code{endfile}. If you examine
+@code{FNR} in @code{endfile()}. If you examine
 the code in
 @ref{Filetrans Function},
 you will see that
 @code{FNR} has already been reset by the time
-@code{endfile} is called.}  It then prints out those numbers
-for the file that was just read. It relies on @code{beginfile} to reset the
+@code{endfile()} is called.}  It then prints out those numbers
+for the file that was just read. It relies on @code{beginfile()} to reset the
 numbers for the following @value{DF}:
-@c ONE DAY: make the above footnote an exercise, instead of giving away the answer.
+@c FIXME: ONE DAY: make the above footnote an exercise,
+@c instead of giving away the answer.
 
 @example
 @c file eg/prog/wc.awk
@@ -22792,7 +22805,10 @@ print.  If the user supplied a message without the ASCII BEL
 character (known as the ``alert'' character, @code{"\a"}), then it is added to
 the message.  (On many systems, printing the ASCII BEL generates an
 audible alert. Thus when the alarm goes off, the system calls attention
-to itself in case the user is not looking at the computer or terminal.)
+to itself in case the user is not looking at the computer.)
+Just for a change, this program uses a @code{switch} statement
+(@pxref{Switch Statement}), but the processing could be done with a series of
+@code{if}-@code{else} statements instead.
 Here is the program:
 
 @cindex @code{alarm.awk} program
@@ -22800,13 +22816,14 @@ Here is the program:
 @c file eg/prog/alarm.awk
 # alarm.awk --- set an alarm
 #
-# Requires gettimeofday library function
+# Requires gettimeofday() library function
 @c endfile
 @ignore
 @c file eg/prog/alarm.awk
 #
 # Arnold Robbins, arnold@@skeeve.com, Public Domain
 # May 1993
+# Revised December 2010
 
 @c endfile
 @end ignore
@@ -22823,19 +22840,24 @@ BEGIN    \
         print usage1 > "/dev/stderr"
         print usage2 > "/dev/stderr"
         exit 1
-    @} else if (ARGC == 5) @{
+    @}
+    switch (ARGC) @{
+    case 5:
         delay = ARGV[4] + 0
+	# fall through
+    case 4:
         count = ARGV[3] + 0
+	# fall through
+    case 3:
         message = ARGV[2]
-    @} else if (ARGC == 4) @{
-        count = ARGV[3] + 0
-        message = ARGV[2]
-    @} else if (ARGC == 3) @{
-        message = ARGV[2]
-    @} else if (ARGV[1] !~ /[0-9]?[0-9]:[0-9][0-9]/) @{
-        print usage1 > "/dev/stderr"
-        print usage2 > "/dev/stderr"
-        exit 1
+	break
+    default:
+        if (ARGV[1] !~ /[[:digit:]]?[[:digit:]]:[[:digit:]][[:digit:]]/) @{
+            print usage1 > "/dev/stderr"
+            print usage2 > "/dev/stderr"
+            exit 1
+	@}
+	break
     @}
 
     # set defaults for once we reach the desired time
@@ -22936,7 +22958,7 @@ often used to map uppercase letters into lowercase for further processing:
 @end example
 
 @command{tr} requires two lists of characters.@footnote{On some older
-System V systems,
+systems,
 @ifset ORA
 including Solaris,
 @end ifset
@@ -23760,13 +23782,13 @@ is set to the null string.  In this case, we can print @code{$0} using
 (@pxref{Printf}).
 
 The @code{BEGIN} rule handles the setup, checking for the right number
-of arguments and calling @code{usage} if there is a problem. Then it sets
+of arguments and calling @code{usage()} if there is a problem. Then it sets
 @code{RS} and @code{ORS} from the command-line arguments and sets
 @code{ARGV[1]} and @code{ARGV[2]} to the null string, so that they are
 not treated as @value{FN}s
 (@pxref{ARGC and ARGV}).
 
-The @code{usage} function prints an error message and exits.
+The @code{usage()} function prints an error message and exits.
 Finally, the single rule handles the printing scheme outlined above,
 using @code{print} or @code{printf} as appropriate, depending upon the
 value of @code{RT}.
@@ -24527,7 +24549,7 @@ The first thing we usually want to do when trying to investigate a
 problem like this is to put a breakpoint in the program so that we can
 watch it at work and catch what it is doing wrong.  A reasonable spot for
 a breakpoint in @file{uniq.awk} is at the beginning of the function
-@code{are_equal}, which compares the current line with the previous one. To set
+@code{are_equal()}, which compares the current line with the previous one. To set
 the breakpoint, use the @code{b} (breakpoint) command:
 
 @example
@@ -24559,16 +24581,16 @@ dgawk> @kbd{bt}
 @print{} #1  in main() at `awklib/eg/prog/uniq.awk':89
 @end example
 
-This tells us that @code{are_equal} was called by the main program at
+This tells us that @code{are_equal()} was called by the main program at
 line 89 of @file{uniq.awk}.  (This is not a big surprise, since this
-is the only call to @code{are_equal} in the program, but in more complex
+is the only call to @code{are_equal()} in the program, but in more complex
 programs, knowing who called a function and with what parameters can be
 the key to finding the source of the problem.)
 
-Now that we're in @code{are_equal}, we can start looking at the values
+Now that we're in @code{are_equal()}, we can start looking at the values
 of some variables.  Let's say we type @samp{p n}
 (@code{p} is short for ``print'').  We would expect to see the value of
-@code{n}, a parameter to @code{are_equal}.  Actually, @command{dgawk}
+@code{n}, a parameter to @code{are_equal()}.  Actually, @command{dgawk}
 gives us:
 
 @example
@@ -24597,7 +24619,7 @@ dgawk> @kbd{p NR}
 @end example
 
 @noindent
-So we can see that @code{are_equal} was only called for the second record
+So we can see that @code{are_equal()} was only called for the second record
 of the file.  Of course, this is because our program contained a rule for
 @samp{NR == 1}:
 
@@ -24616,9 +24638,9 @@ dgawk> @kbd{p last}
 @end example
 
 Everything we have done so far has verified that the program has worked as
-planned, up to and including the call to @code{are_equal}, so the problem must
+planned, up to and including the call to @code{are_equal()}, so the problem must
 be inside this function.  To investigate further, we have to begin
-``stepping through'' the lines of @code{are_equal}.  We start by typing
+``stepping through'' the lines of @code{are_equal()}.  We start by typing
 @code{n} (for ``next''):
 
 @example