[src/trunk]: src/usr.bin/awk Do extensive facelift:

[jdolecek <jdolecek%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b9929db49c50
branches:  trunk
changeset: 503075:b9929db49c50
user:      jdolecek <jdolecek%NetBSD.org@localhost>
date:      Tue Jan 30 21:05:12 2001 +0000

description:
Do extensive facelift:
* divide text into subsections according to function
* group I/O, math functions together (similarily to how gawk manpage
  is structured) and provide easily parsable
  list, so that it's much easier to find information about individual
  functions
* sort function and variable list by alphabet

diffstat:

 usr.bin/awk/awk.1 |  388 +++++++++++++++++++++++++++++------------------------
 1 files changed, 213 insertions(+), 175 deletions(-)

diffs (truncated from 476 to 300 lines):

diff -r 2ec75ebb792d -r b9929db49c50 usr.bin/awk/awk.1
--- a/usr.bin/awk/awk.1 Tue Jan 30 19:45:09 2001 +0000
+++ b/usr.bin/awk/awk.1 Tue Jan 30 21:05:12 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: awk.1,v 1.1 2001/01/30 18:26:30 jdolecek Exp $
+.\"    $NetBSD: awk.1,v 1.2 2001/01/30 21:05:12 jdolecek Exp $
 .\"
 .\" Copyright (C) Lucent Technologies 1997
 .\" All Rights Reserved
@@ -98,60 +98,6 @@
 Pattern-action statements are separated by newlines or semicolons.
 .Pp
 An action is a sequence of statements.
-A statement can be one of the following:
-.Pp
-.Bl -hang -offset indent -width "" -compact
-.It Xo
-.Ic if \&( Ar expression Ic \&) Ar statement
-.Bq Ic else Ar statement
-.Xc
-.It Ic while( Ar expression Ic \&) Ar statement
-.It Xo
-.Ic for( Ar expression Ic \&; Ar expression Ic \&;
-.Ar expression Ic \&)
-.Ar statement
-.Xc
-.It Xo
-.Ic for( Va var Ic in Ar array
-.Ic \&)
-.Ar statement
-.Xc
-.It Xo
-.Ic do Ar statement
-.Ic while( Ar expression Ic \&)
-.Xc
-.It Ic break
-.It Ic continue
-.It Ic { Ar [ statement ... ] Ic }
-.It Ar expression
-# commonly
-.Ic var =
-.Ar expression
-.It Xo
-.Ic print
-.Bq Ar expression-list
-.Bq Ic > Ar expression
-.Xc
-.It Xo 
-.Ic printf
-.Ar format
-.Bq Ic , Ar expression-list
-.Bq Ic > Ar expression
-.Xc
-.It Ic return Bq Ar expression
-.It Ic next
-# skip remaining patterns on this input line
-.It Ic nextfile
-# skip rest of this file, open next, start at top
-.It Ic delete Va array Bq Ar expression
-# delete an array element
-.It Ic delete Va array
-# delete all elements of array
-.It Ic exit Bq Ar expression
-# exit immediately; status is
-.Ar expression
-.El
-.Pp
 Statements are terminated by
 semicolons, newlines or right braces.
 An empty
@@ -181,76 +127,194 @@
 separated by the value of
 .Va SUBSEP .
 .Pp
+.Ss Control Statements
+The control statements are as follows:
+.Pp
+.Bl -hang -offset indent -width "" -compact
+.It Xo
+.Ic if \&( Ar expression Ic \&) Ar statement
+.Bq Ic else Ar statement
+.Xc
+.It Ic while( Ar expression Ic \&) Ar statement
+.It Xo
+.Ic for( Ar expression Ic \&; Ar expression Ic \&;
+.Ar expression Ic \&)
+.Ar statement
+.Xc
+.It Xo
+.Ic for( Va var Ic in Ar array
+.Ic \&)
+.Ar statement
+.Xc
+.It Xo
+.Ic do Ar statement
+.Ic while( Ar expression Ic \&)
+.Xc
+.It Ic break
+.It Ic continue
+.It Ic delete Va array Bq Ar expression
+.It Ic delete Va array
+.It Ic exit Bq Ar expression
+.Ar expression
+.It Ic return Bq Ar expression
+.It Ic { Ar [ statement ... ] Ic }
+.El
+.Pp
+.Ss I/O Statements
+The input/ouput statements are as follows:
+.Pp
+.Bl -tag -width indent
+.It Fn close expr
+Closes the file or pipe
+.Ar expr .
+.It Fn fflush expr
+Flushes any buffered output for the file or pipe
+.Ar expr .
+.It Ic getline Bq Va var
+Set
+.Va var
+(or
+.Va $0 if
+.Va var
+is not specified)
+to the next input record from the current input file.
+.Ic getline
+returns 1 for a successful input,
+0 for end of file, and \-1 for an error.
+.It Xo
+.Ic getline
+.Bq Va var
+.Ic <
+.Ar file
+.Xc
+Set
+.Va var
+(or
+.Va $0 if
+.Va var
+is not specified)
+to the next input record from the specified file
+.Ar file .
+.It Ar expr Ic \&| getline
+Pipes the output of
+.Ar expr
+into
+.Ic getline ;
+each call of
+.Ic getline
+returns the next line of output from
+.Ar expr .
+.It Ic next
+Skip remaining patterns on this input line.
+.It Ic nextfile
+Skip rest of this file, open next, start at top.
+.It Xo
+.Ic print
+.Bq Ar expr-list
+.Bq Ic > Ar file
+.Xc
 The
 .Ic print
-statement prints its arguments on the standard output
-(or on a file if
+statement prints its arguments on the standard output (or to a file
+if
 .Ic > file
-or
-.Ic >> file
-is present or on a pipe if
-.Ar | cmd
-is present), separated by the current output field separator,
-and terminated by the output record separator.
+or to a pipe if
+.Ic | Ar expr
+is present),
+separated by the current output field separator
+.Va OFS ,
+and terminated by the
+output record separator
+.Va ORS .
+Both
 .Ar file
 and
-.Ar cmd
-may be literal names or parenthesized expressions;
-identical string values in different statements denote
-the same open file.
-The
+.Ar expr
+may be literal names or parenthesized expressions; identical string values in
+different statements denote the same open file.
+.It Xo
 .Ic printf
-statement formats its expression list according to the format
-(see
-.Xr printf 3 ) .
-The built-in function
-.Fn close expr
-closes the file or pipe
+.Ar format
+.Bq Ic , Ar expr-list
+.Bq Ic > Ar file
+.Xc
+Format and print its expression list according to
+.Ar format .
+See
+.Xr printf 3
+for list of supported formats and their meaning.
+.El
+.Ss Mathematical and Numeric Functions
+AWK has the following mathematical and numerical functions built-in:
+.Pp
+.Bl -tag -width indent
+.It Fn atan2 x y
+Returns the arctangent of
+.Ar x Ic / Ar y
+in radians. See also
+.Xr atan2 3 .
+.It Fn cos expr
+Computes the cosine of
+.Ar expr ,
+measured in radians. See also
+.Xr cos 3 .
+.It Fn exp expr
+Computes the exponential value of the given argument
 .Ar expr .
-The built-in function
-.Fn fflush expr
-flushes any buffered output for the file or pipe
+See also
+.Xr exp 3 .
+.It Fn int expr
+Truncates
+.Ar expr
+to integer.
+.It Fn log expr
+Computes the value of the natural logarithm of argument
 .Ar expr .
+See also
+.Xr log 3 .
+.It Fn rand
+Returns random number between 0 and 1.
+.It Fn sin expr
+Computes the sine of
+.Ar expr ,
+measured in radians. See also
+.Xr sin 3 .
+.It Fn sqrt expr
+Computes the non-negative square root of
+.Ar expr .
+See also
+.Xr sqrt 3 .
+.It Fn srand [expr]
+Sets seed for random number generator (
+.Fn rand )
+and returns the previous seed.
+.El
 .Pp
-The mathematical functions
-.Fn exp ,
-.Fn log ,
-.Fn sqrt ,
-.Fn sin ,
-.Fn cos ,
+.Ss String Functions
+AWK has the following string functions built-in:
+.Pp
+.Bl -tag -width indent
+.It Fn gsub
+same as
+.Fn sub
+except that all occurrences of the regular expression
+are replaced;
+.Fn sub
 and
-.Fn atan2
-are built in.
-Other built-in functions:
-.Bl -tag -width indent
+.Fn gsub
+return the number of replacements.
+.It Fn index s t
+the position in
+.Ar s
+where the string
+.Ar t
+occurs, or 0 if it does not.
 .It Fn length "[string]"
 the length of its argument
 taken as a string,
 or of
 .Va $0
 if no argument.
-.It Fn rand
-random number on (0,1)
-.It Fn srand number
-sets seed for
-.Fn rand
-and returns the previous seed.