[src/trunk]: src/usr.bin/awk Conversion of nawk manpage to mdoc format. Put h...

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

details:   https://anonhg.NetBSD.org/src/rev/a171a496bc58
branches:  trunk
changeset: 503068:a171a496bc58
user:      jdolecek <jdolecek%NetBSD.org@localhost>
date:      Tue Jan 30 18:26:30 2001 +0000

description:
Conversion of nawk manpage to mdoc format. Put here rather than
to dist/nawk/, since it's not likely mdoc formatted manpage would become
part of nawk distrubution.
Hopefully mdoc macros are used mostly correctly here.

diffstat:

 usr.bin/awk/awk.1 |  507 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 507 insertions(+), 0 deletions(-)

diffs (truncated from 511 to 300 lines):

diff -r c4579701bf30 -r a171a496bc58 usr.bin/awk/awk.1
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/usr.bin/awk/awk.1 Tue Jan 30 18:26:30 2001 +0000
@@ -0,0 +1,507 @@
+.\"    $NetBSD: awk.1,v 1.1 2001/01/30 18:26:30 jdolecek Exp $
+.\"
+.\" Copyright (C) Lucent Technologies 1997
+.\" All Rights Reserved
+.\" 
+.\" Permission to use, copy, modify, and distribute this software and
+.\" its documentation for any purpose and without fee is hereby
+.\" granted, provided that the above copyright notice appear in all
+.\" copies and that both that the copyright notice and this
+.\" permission notice and warranty disclaimer appear in supporting
+.\" documentation, and that the name Lucent Technologies or any of
+.\" its entities not be used in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior
+.\" permission.
+.\" 
+.\" LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
+.\" IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
+.\" SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
+.\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+.\" THIS SOFTWARE.
+.\"
+.Dd January 3, 1998
+.Dt AWK 1
+.Os
+.Sh NAME
+.Nm awk
+.Nd pattern-directed scanning and processing language
+.Sh SYNOPSIS
+.Nm
+.Op Fl F Ar fs
+.Op Fl v Ar var=value
+.Op Ar prog | Fl f Ar progname
+.Ar
+.Sh DESCRIPTION
+.Nm
+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
+.Fl f Ar progfile .
+With each pattern
+there can be an associated action that will be performed
+when a line of a
+.I file
+matches the pattern.
+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
+.Ar -
+means the standard input.
+Any
+.Ar file
+of the form
+.Ar var=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
+.Ar fs.
+.Pp
+An input line is normally made up of fields separated by white space,
+or by regular expression
+.Va FS .
+The fields are denoted
+.Va $1 ,
+.Va $2 ,
+\&..., while
+.Va $0
+refers to the entire line.
+If
+.Va FS
+is null, the input line is split into one field per character.
+.Pp
+A pattern-action statement has the form
+.sp
+.Dl pattern \&{ action \&}
+.sp
+A missing \&{ action \&}
+means print the line;
+a missing pattern always matches.
+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
+.Ar expression-list
+stands for
+.Va $0 .
+String constants are quoted \&\f(CW"\ "\fR,
+with the usual C escapes recognized within.
+Expressions take on string or numeric values as appropriate,
+and are built using the operators
+.Ic + \- * / % ^
+(exponentiation), and concatenation (indicated by white space).
+The operators
+.Ic ! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?:
+are also available in expressions.
+Variables may be scalars, array elements
+(denoted
+.Va x[i] )
+or fields.
+Variables are initialized to the null string.
+Array subscripts may be any string,
+not necessarily numeric;
+this allows for a form of associative memory.
+Multiple subscripts such as
+.Va [i,j,k]
+are permitted; the constituents are concatenated,
+separated by the value of
+.Va SUBSEP .
+.Pp
+The
+.Ic print
+statement prints its arguments on the standard output
+(or on 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.
+.Ar file
+and
+.Ar cmd
+may be literal names or parenthesized expressions;
+identical string values in different statements denote
+the same open file.
+The
+.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 expr .
+The built-in function
+.Fn fflush expr
+flushes any buffered output for the file or pipe
+.Ar expr .
+.Pp
+The mathematical functions
+.Fn exp ,
+.Fn log ,
+.Fn sqrt ,
+.Fn sin ,
+.Fn cos ,
+and
+.Fn atan2
+are built in.
+Other built-in functions:
+.Bl -tag -width indent
+.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.
+.It Fn int
+truncates to an integer value
+.It Fn substr s m n
+the
+.Ar n -character
+substring of
+.Ar s
+that begins at position
+.Ar m
+counted from 1.
+.It Fn index s t
+the position in
+.Ar s
+where the string
+.Ar t
+occurs, or 0 if it does not.
+.It Fn match s r
+the position in
+.Ar s
+where the regular expression
+.Ar r
+occurs, or 0 if it does not.
+The variables
+.Va RSTART
+and
+.Va RLENGTH
+are set to the position and length of the matched string.
+.It Fn split s a "[fs]"
+splits the string
+.Ar s
+into array elements
+.Va a[1] ,
+.Va a[2] ,
+\&...,
+.Va a[n] ,
+and returns
+.Va n .
+The separation is done with the regular expression
+.Ar fs
+or with the field separator
+.Va FS
+if
+.Ar fs
+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
+.Ar t
+for the first occurrence of the regular expression
+.Ar r
+in the string
+.Ar s .
+If
+.Ar s
+is not given,
+.Va $0
+is used.
+.It Fn gsub