- update SYNOPSIS

- standard options list
- document -V and -d[n]
- -mr and -mf no longer supported
- some formatting issues
- descriptions of examples before examples and indent examples
- update SEE ALSO

ok millert@

1 files changed, 111 insertions, 89 deletions

diff --git a/usr.bin/awk/awk.1 b/usr.bin/awk/awk.1
index 7942af028c7..7e4866a6e77 100644
--- a/usr.bin/awk/awk.1
+++ b/usr.bin/awk/awk.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: awk.1,v 1.15 2003/11/24 10:58:08 jmc Exp $
+.\"	$OpenBSD: awk.1,v 1.16 2003/12/12 19:50:55 jmc Exp $
 .\" EX/EE is a Bd
 .\"
 .\" Copyright (C) Lucent Technologies 1997
@@ -31,12 +31,13 @@
 .Nd pattern-directed scanning and processing language
 .Sh SYNOPSIS
 .Nm awk
-.Op Fl F Ar fs
-.Op Fl v Ar var=value
 .Op Fl safe
-.Op Fl mr Ar n
-.Op Fl mf Ar n
-.Op Ar prog | Fl f Ar progfile
+.Op Fl V
+.Op Fl d Ns Op Ar n
+.Op Fl F Ar fs
+.Oo Fl v Ar var Ns =
+.Ns Ar value Oc
+.Ar prog | Fl f Ar progfile
 .Ar
 .Nm nawk
 .Ar ...
@@ -46,11 +47,9 @@ scans each input
 .Ar file
 for lines that match any of a set of patterns specified literally in
 .Ar prog
-or in one or more files
-specified as
+or in one or more files specified as
 .Fl f Ar progfile .
-With each pattern
-there can be an associated action that will be performed
+With each pattern there can be an associated action that will be performed
 when a line of a
 .Ar file
 matches the pattern.
@@ -58,35 +57,38 @@ Each line is matched against the
 pattern portion of every pattern-action statement;
 the associated action is performed for each matched pattern.
 The file name
-.Sq Pa \-
+.Sq -
 means the standard input.
 Any
 .Ar file
 of the form
-.Ar var=value
+.Ar var Ns = Ns Ar value
 is treated as an assignment, not a filename,
 and is executed at the time it would have been opened if it were a filename.
-The option
-.Fl v
-followed by
-.Ar var=value
-is an assignment to be done before
-.Ar prog
-is executed;
-any number of
-.Fl v
-options may be present.
-The
-.Fl F Ar fs
-option defines the input field separator to be the regular expression
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl d Ns Op Ar n
+Debug mode.
+Set debug level to
+.Ar n ,
+or 1 if
+.Ar n
+is not specified.
+A value greater than 1 causes
+.Nm
+to dump core on fatal errors.
+.It Fl F Ar fs
+Define the input field separator to be the regular expression
 .Ar fs .
-The
-.Fl safe
-option disables file output
-.Po
-.Ic print Ic > ,
-.Ic print Ic >> ,
-.Pc
+.It Fl f Ar filename
+Read program code from the specified file
+.Ar filename
+instead of from the command line.
+.It Fl safe
+Disable file output
+.Pf ( Ic print > ,
+.Ic print >> ) ,
 process creation
 .Po
 .Ar cmd Ic \&| getline ,
@@ -95,10 +97,28 @@ process creation
 and access to the environment
 .Pq Va ENVIRON .
 This
-is a first (and not very reliable) approximation to a
+is a first
+.Pq and not very reliable
+approximation to a
 .Dq safe
 version of
-.Nm awk .
+.Nm .
+.It Fl V
+Print the version number of
+.Nm
+to standard output and exit.
+.It Fl v Ar var Ns = Ns Ar value
+Assign
+.Ar value
+to variable
+.Ar var
+before
+.Ar prog
+is executed;
+any number of
+.Fl v
+options may be present.
+.El
 .Pp
 An input line is normally made up of fields separated by whitespace,
 or by regular expression
@@ -112,14 +132,6 @@ If
 .Va FS
 is null, the input line is split into one field per character.
 .Pp
-To compensate for inadequate implementation of storage management,
-the
-.Fl mr
-option can be used to set the maximum size of the input record,
-and the
-.Fl mf
-option to set the maximum number of fields.
-.Pp
 A pattern-action statement has the form
 .Pp
 .D1 Ar pattern Ic \&{ Ar action Ic \&}
@@ -194,7 +206,8 @@ and are built using the operators
 .Ic + \- * / % ^
 (exponentiation), and concatenation (indicated by whitespace).
 The operators
-.Ic \&! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?:
+.Ic \&! ++ \-\- += \-= *= /= %= ^=
+.Ic > >= < <= == != ?:
 are also available in expressions.
 Variables may be scalars, array elements
 (denoted
@@ -253,21 +266,21 @@ are built in.
 Other built-in functions:
 .Bl -tag -width Fn
 .It Fn length
-the length of its argument
+The length of its argument
 taken as a string,
 or of
 .Va $0
 if no argument.
 .It Fn rand
-random number on (0,1)
+Random number on (0,1).
 .It Fn srand
-sets seed for
+Sets seed for
 .Fn rand
 and returns the previous seed.
 .It Fn int
-truncates to an integer value.
+Truncates to an integer value.
 .It Fn substr s m n
-the
+The
 .Fa n Ns No -character
 substring of
 .Fa s
@@ -275,13 +288,13 @@ that begins at position
 .Fa m
 counted from 1.
 .It Fn index s t
-the position in
+The position in
 .Fa s
 where the string
 .Fa t
 occurs, or 0 if it does not.
 .It Fn match s r
-the position in
+The position in
 .Fa s
 where the regular expression
 .Fa r
@@ -292,7 +305,7 @@ and
 .Va RLENGTH
 are set to the position and length of the matched string.
 .It Fn split s a fs
-splits the string
+Splits the string
 .Fa s
 into array elements
 .Va a[1] , a[2] , ... , a[n]
@@ -308,7 +321,7 @@ is not given.
 An empty string as field separator splits the string
 into one array element per character.
 .It Fn sub r t s
-substitutes
+Substitutes
 .Fa t
 for the first occurrence of the regular expression
 .Fa r
@@ -320,7 +333,7 @@ is not given,
 .Va $0
 is used.
 .It Fn gsub r t s
-same as
+Same as
 .Fn sub
 except that all occurrences of the regular expression
 are replaced;
@@ -329,23 +342,23 @@ and
 .Fn gsub
 return the number of replacements.
 .It Fn sprintf fmt expr ...
-the string resulting from formatting
+The string resulting from formatting
 .Fa expr , ...
 according to the
 .Xr printf 3
 format
 .Fa fmt .
 .It Fn system cmd
-executes
+Executes
 .Fa cmd
 and returns its exit status.
 .It Fn tolower str
-returns a copy of
+Returns a copy of
 .Fa str
 with all upper-case characters translated to their
 corresponding lower-case equivalents.
 .It Fn toupper str
-returns a copy of
+Returns a copy of
 .Fa str
 with all lower-case characters translated to their
 corresponding upper-case equivalents.
@@ -445,41 +458,41 @@ do not combine with other patterns.
 .Pp
 Variable names with special meanings:
 .Pp
-.Bl -tag -width Va -compact
+.Bl -tag -width "FILENAME" -compact
+.It Va ARGC
+Argument count, assignable.
+.It Va ARGV
+Argument array, assignable;
+non-null members are taken as filenames.
 .It Va CONVFMT
-conversion format used when converting numbers
+Conversion format used when converting numbers
 (default
-.Qq Li %.6g )
+.Qq Li %.6g ) .
+.It Va ENVIRON
+Array of environment variables; subscripts are names.
+.It Va FILENAME
+The name of the current input file.
+.It Va FNR
+Ordinal number of the current record in the current file.
 .It Va FS
-regular expression used to separate fields; also settable
+Regular expression used to separate fields; also settable
 by option
 .Fl F Ar fs .
 .It Va NF
-number of fields in the current record
+Number of fields in the current record.
 .It Va NR
-ordinal number of the current record
-.It Va FNR
-ordinal number of the current record in the current file
-.It Va FILENAME
-the name of the current input file
-.It Va RS
-input record separator (default newline)
+Ordinal number of the current record.
+.It Va OFMT
+Output format for numbers (default
+.Qq Li %.6g ) .
 .It Va OFS
-output field separator (default blank)
+Output field separator (default blank).
 .It Va ORS
-output record separator (default newline)
-.It Va OFMT
-output format for numbers (default
-.Qq Li %.6g )
+Output record separator (default newline).
+.It Va RS
+Input record separator (default newline).
 .It Va SUBSEP
-separates multiple subscripts (default 034)
-.It Va ARGC
-argument count, assignable
-.It Va ARGV
-argument array, assignable;
-non-null members are taken as filenames
-.It Va ENVIRON
-array of environment variables; subscripts are names.
+Separates multiple subscripts (default 034).
 .El
 .Pp
 Functions may be defined (at the position of a pattern-action statement)
@@ -487,30 +500,37 @@ thusly:
 .Pp
 .Dl function foo(a, b, c) { ...; return x }
 .Pp
-Parameters are passed by value if scalar and by reference if array name;
+Parameters are passed by value if scalar, and by reference if array name;
 functions may be called recursively.
 Parameters are local to the function; all other variables are global.
 Thus local variables may be created by providing excess parameters in
 the function definition.
 .Sh EXAMPLES
+Print lines longer than 72 characters:
+.Pp
 .Dl length($0) > 72
-Print lines longer than 72 characters.
+.Pp
+Print first two fields in opposite order:
 .Pp
 .Dl { print $2, $1 }
-Print first two fields in opposite order.
+.Pp
+Same, with input fields separated by comma and/or blanks and tabs:
 .Bd -literal -offset indent
 BEGIN { FS = ",[ \et]*|[ \et]+" }
       { print $2, $1 }
 .Ed
-Same, with input fields separated by comma and/or blanks and tabs.
+.Pp
+Add up first column, print sum and average:
 .Bd -literal -offset indent
 { s += $1 }
 END { print "sum is", s, " average is", s/NR }
 .Ed
-Add up first column, print sum and average.
+.Pp
+Print all lines between start/stop pairs:
 .Pp
 .Dl /start/, /stop/
-Print all lines between start/stop pairs.
+.Pp
+Simulate echo(1):
 .Bd -literal -offset indent
 BEGIN { # Simulate echo(1)
         for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i]
@@ -518,8 +538,10 @@ BEGIN { # Simulate echo(1)
         exit }
 .Ed
 .Sh SEE ALSO
+.Xr egrep 1 ,
 .Xr lex 1 ,
-.Xr sed 1
+.Xr sed 1 ,
+.Xr printf 3
 .Rs
 .%A A. V. Aho
 .%A B. W. Kernighan