Index: head/share/doc/usd/06.bc/bc
===================================================================
--- head/share/doc/usd/06.bc/bc (revision 282217)
+++ head/share/doc/usd/06.bc/bc (revision 282218)
@@ -1,1241 +1,1242 @@
.\" $FreeBSD$
.\" $OpenBSD: bc,v 1.9 2004/07/09 10:23:05 jmc Exp $
.\"
.\" Copyright (C) Caldera International Inc. 2001-2002.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code and documentation must retain the above
.\" copyright notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed or owned by Caldera
.\" International, Inc.
.\" 4. Neither the name of Caldera International, Inc. nor the names of other
.\" contributors may be used to endorse or promote products derived from
.\" this software without specific prior written permission.
.\"
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" @(#)bc 6.2 (Berkeley) 4/17/91
.\"
.if n \{\
.po 5n
.ll 70n
.\}
.EH 'USD:6-%''BC \- An Arbitrary Precision Desk-Calculator Language'
.OH 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6-%'
.\".RP
+.ND
.TL
BC \- An Arbitrary Precision Desk-Calculator Language
.AU
Lorinda Cherry
.AU
Robert Morris
.AI
.\" .MH
.AB
BC is a language and a compiler for doing arbitrary precision arithmetic
on the PDP-11 under the
.UX
time-sharing
system. The output of the compiler is interpreted and executed by
a collection of routines which can input, output, and do
arithmetic on indefinitely large integers and on scaled fixed-point
numbers.
.PP
These routines are themselves based on a dynamic storage allocator.
Overflow does not occur until all available core storage
is exhausted.
.PP
The language has a complete control structure as well as immediate-mode
operation. Functions can be defined and saved for later execution.
.PP
Two five hundred-digit numbers can be multiplied to give a
thousand digit result in about ten seconds.
.PP
A small collection of library functions is also available,
including sin, cos, arctan, log, exponential, and Bessel functions of
integer order.
.PP
Some of the uses of this compiler are
.IP \-
to do computation with large integers,
.IP \-
to do computation accurate to many decimal places,
.IP \-
conversion of numbers from one base to another base.
.AE
.PP
.SH
Introduction
.PP
BC is a language and a compiler for doing arbitrary precision
arithmetic on the
.UX
time-sharing system [1].
The compiler was written to make conveniently available a
collection of routines (called DC [5]) which are capable of doing
arithmetic on integers of arbitrary size. The compiler
is by no means intended to provide a complete programming
language.
It is a minimal language facility.
.PP
There is a scaling provision that permits the
use of decimal point notation.
Provision is made for input and output in bases other than
decimal. Numbers can be converted from decimal to octal by
simply setting the output base to equal 8.
.PP
The actual limit on the number of digits that can
be handled depends on the amount of storage available on the machine.
Manipulation of numbers with many hundreds of digits
is possible even on the smallest versions of
.UX .
.PP
The syntax of BC has been deliberately selected to agree
substantially with the C language [2]. Those who
are familiar with C will find few surprises in this language.
.SH
Simple Computations with Integers
.PP
The simplest kind of statement is an arithmetic expression
on a line by itself.
For instance, if you type in the line:
.DS
.ft B
142857 + 285714
.ft P
.DE
the program responds immediately with the line
.DS
.ft B
428571
.ft P
.DE
The operators \-, *, /, %, and ^ can also be used; they
indicate subtraction, multiplication, division, remaindering, and
exponentiation, respectively. Division of integers produces an
integer result truncated toward zero.
Division by zero produces an error
comment.
.PP
Any term in an expression may be prefixed by a minus sign to
indicate that it is to be negated (the `unary' minus sign).
The expression
.DS
.ft B
7+\-3
.ft P
.DE
is interpreted to mean that \-3 is to be added to 7.
.PP
More complex expressions with several operators and with
parentheses are interpreted just as in
Fortran, with ^ having the greatest binding
power, then * and % and /, and finally + and \-.
Contents of parentheses are evaluated before material
outside the parentheses.
Exponentiations are
performed from right to left and the other operators
from left to right.
The two expressions
.DS
.ft B
a^b^c and a^(b^c)
.ft P
.DE
are equivalent, as are the two expressions
.DS
.ft B
a*b*c and (a*b)*c
.ft P
.DE
BC shares with Fortran and C the undesirable convention that
.DS
\fBa/b*c\fP is equivalent to \fB(a/b)*c\fP
.ft P
.DE
.PP
Internal storage registers to hold numbers have single lower-case
letter names. The value of an expression can be assigned to
a register in the usual way. The statement
.DS
.ft B
x = x + 3
.ft P
.DE
has the effect of increasing by three the value of the contents of the
register named x.
When, as in this case, the outermost operator is an =, the
assignment is performed but the result is not printed.
Only 26 of these named storage registers are available.
.PP
There is a built-in square root function whose
result is truncated to an integer (but see scaling below).
The lines
.DS
.ft B
x = sqrt(191)
x
.ft P
.DE
produce the printed result
.DS
.ft B
13
.ft P
.DE
.SH
Bases
.PP
There are special internal quantities, called `ibase' and `obase'.
The contents of `ibase', initially set to 10,
determines the base used for interpreting numbers read in.
For example, the lines
.DS
.ft B
ibase = 8
11
.ft P
.DE
will produce the output line
.DS
.ft B
9
.ft P
.DE
and you are all set up to do octal to decimal conversions.
Beware, however of trying to change the input base back
to decimal by typing
.DS
.ft B
ibase = 10
.ft P
.DE
Because the number 10 is interpreted as octal, this statement will
have no effect.
For those who deal in hexadecimal notation,
the characters A\-F are permitted in numbers
(no matter what base is in effect)
and are
interpreted as digits having values 10\-15 respectively.
The statement
.DS
.ft B
ibase = A
.ft P
.DE
will change you back to decimal input base no matter what the
current input base is.
Negative and large positive input bases are
permitted but useless.
No mechanism has been provided for the input of arbitrary
numbers in bases less than 1 and greater than 16.
.PP
The contents of `obase', initially set to 10, are used as the base for output
numbers. The lines
.DS
.ft B
obase = 16
1000
.ft P
.DE
will produce the output line
.DS
.ft B
3E8
.ft P
.DE
which is to be interpreted as a 3-digit hexadecimal number.
Very large output bases are permitted, and they are sometimes useful.
For example, large numbers can be output in groups of five digits
by setting `obase' to 100000.
Strange (i.e. 1, 0, or negative) output bases are
handled appropriately.
.PP
Very large numbers are split across lines with 70 characters per line.
Lines which are continued end with \\.
Decimal output conversion is practically instantaneous, but output
of very large numbers (i.e., more than 100 digits) with other bases
is rather slow.
Non-decimal output conversion of
a one hundred digit number takes about
three seconds.
.PP
It is best to remember that `ibase' and `obase' have no effect
whatever on the course of internal computation or
on the evaluation of expressions, but only affect input and
output conversion, respectively.
.SH
Scaling
.PP
A third special internal quantity called `scale' is
used to determine the scale of calculated
quantities.
Numbers may have
up to a specific number of decimal digits after the decimal point.
This fractional part is retained in further computations.
We refer to the number of digits after the decimal point of
a number as its scale.
The current implementation allows scales to be as large as can be
represented by a 32-bit unsigned number minus one.
This is a non-portable extension.
The original implementation allowed for a maximum scale of 99.
.PP
When two scaled numbers are combined by
means of one of the arithmetic operations, the result
has a scale determined by the following rules. For
addition and subtraction, the scale of the result is the larger
of the scales of the two operands. In this case,
there is never any truncation of the result.
For multiplications, the scale of the result is never
less than the maximum of the two scales of the operands,
never more than the sum of the scales of the operands
and, subject to those two restrictions,
the scale of the result is set equal to the contents of the internal
quantity `scale'.
The scale of a quotient is the contents of the internal
quantity `scale'. The scale of a remainder is
the sum of the scales of the quotient and the divisor.
The result of an exponentiation is scaled as if
the implied multiplications were performed.
An exponent must be an integer.
The scale of a square root is set to the maximum of the scale
of the argument and the contents of `scale'.
.PP
All of the internal operations are actually carried out in terms
of integers, with digits being discarded when necessary.
In every case where digits are discarded, truncation and
not rounding is performed.
.PP
The contents of
`scale' must be no greater than
4294967294 and no less than 0. It is initially set to 0.
.PP
The internal quantities `scale', `ibase', and `obase' can be
used in expressions just like other variables.
The line
.DS
.ft B
scale = scale + 1
.ft P
.DE
increases the value of `scale' by one, and the line
.DS
.ft B
scale
.ft P
.DE
causes the current value of `scale' to be printed.
.PP
The value of `scale' retains its meaning as a
number of decimal digits to be retained in internal
computation even when `ibase' or `obase' are not equal to 10.
The internal computations (which are still conducted in decimal,
regardless of the bases) are performed to the specified number
of decimal digits, never hexadecimal or octal or any
other kind of digits.
.SH
Functions
.PP
The name of a function is a single lower-case letter.
Function names are permitted to collide with simple
variable names.
Twenty-six different defined functions are permitted
in addition to the twenty-six variable names.
The line
.DS
.ft B
define a(x){
.ft P
.DE
begins the definition of a function with one argument.
This line must be followed by one or more statements,
which make up the body of the function, ending
with a right brace }.
Return of control from a function occurs when a return
statement is executed or when the end of the function is reached.
The return statement can take either
of the two forms
.DS
.ft B
return
return(x)
.ft P
.DE
In the first case, the value of the function is 0, and in
the second, the value of the expression in parentheses.
.PP
Variables used in the function can be declared as automatic
by a statement of the form
.DS
.ft B
auto x,y,z
.ft P
.DE
There can be only one `auto' statement in a function and it must
be the first statement in the definition.
These automatic variables are allocated space and initialized
to zero on entry to the function and thrown away on return. The
values of any variables with the same names outside the function
are not disturbed.
Functions may be called recursively and the automatic variables
at each level of call are protected.
The parameters named in a function definition are treated in
the same way as the automatic variables of that function
with the single exception that they are given a value
on entry to the function.
An example of a function definition is
.DS
.ft B
define a(x,y){
auto z
z = x*y
return(z)
}
.ft P
.DE
The value of this function, when called, will be the
product of its
two arguments.
.PP
A function is called by the appearance of its name
followed by a string of arguments enclosed in
parentheses and separated by commas.
The result
is unpredictable if the wrong number of arguments is used.
.PP
Functions with no arguments are defined and called using
parentheses with nothing between them: b().
.PP
If the function
.ft I
a
.ft
above has been defined, then the line
.DS
.ft B
a(7,3.14)
.ft P
.DE
would cause the result 21.98 to be printed and the line
.DS
.ft B
x = a(a(3,4),5)
.ft P
.DE
would cause the value of x to become 60.
.SH
Subscripted Variables
.PP
A single lower-case letter variable name
followed by an expression in brackets is called a subscripted
variable (an array element).
The variable name is called the array name and the expression
in brackets is called the subscript.
Only one-dimensional arrays are
permitted. The names of arrays are permitted to
collide with the names of simple variables and function names.
Any fractional
part of a subscript is discarded before use.
Subscripts must be greater than or equal to zero and
less than or equal to 2047.
.PP
Subscripted variables may be freely used in expressions, in
function calls, and in return statements.
.PP
An array name may be used as an argument to a function,
or may be declared as automatic in
a function definition by the use of empty brackets:
.DS
.ft B
f(a[\|])
define f(a[\|])
auto a[\|]
.ft P
.DE
When an array name is so used, the whole contents of the array
are copied for the use of the function, and thrown away on exit
from the function.
Array names which refer to whole arrays cannot be used
in any other contexts.
.SH
Control Statements
.PP
The `if', the `while', and the `for' statements
may be used to alter the flow within programs or to cause iteration.
The range of each of them is a statement or
a compound statement consisting of a collection of
statements enclosed in braces.
They are written in the following way
.DS
.ft B
if(relation) statement
if(relation) statement else statement
while(relation) statement
for(expression1; relation; expression2) statement
.ft P
.DE
or
.DS
.ft B
if(relation) {statements}
if(relation) {statements} else {statements}
while(relation) {statements}
for(expression1; relation; expression2) {statements}
.ft P
.DE
.PP
A relation in one of the control statements is an expression of the form
.DS
.ft B
x>y
.ft P
.DE
where two expressions are related by one of the six relational
operators `<', `>', `<=', `>=', `==', or `!='.
The relation `=='
stands for `equal to' and `!=' stands for `not equal to'.
The meaning of the remaining relational operators is
clear.
.PP
BEWARE of using `=' instead of `==' in a relational. Unfortunately,
both of them are legal, so you will not get a diagnostic
message, but `=' really will not do a comparison.
.PP
The `if' statement causes execution of its range
if and only if the relation is true.
Then control passes to the next statement in sequence.
If an `else' branch is present, the statements in this branch are
executed if the relation is false.
The `else' keyword is a non-portable extension.
.PP
The `while' statement causes execution of its range
repeatedly as long as the relation
is true. The relation is tested before each execution
of its range and if the relation
is false, control passes to the next statement beyond the range
of the while.
.PP
The `for' statement begins
by executing `expression1'. Then the relation is tested
and, if true, the statements in the range of the `for' are executed.
Then `expression2' is executed. The relation is tested, and so on.
The typical use of the `for' statement is for a controlled iteration,
as in the statement
.DS
.ft B
for(i=1; i<=10; i=i+1) i
.ft P
.DE
which will print the integers from 1 to 10.
Here are some examples of the use of the control statements.
.DS
.ft B
define f(n){
auto i, x
x=1
for(i=1; i<=n; i=i+1) x=x*i
return(x)
}
.ft P
.DE
The line
.DS
.ft B
f(a)
.ft P
.DE
will print
.ft I
a
.ft
factorial if
.ft I
a
.ft
is a positive integer.
Here is the definition of a function which will
compute values of the binomial coefficient
(m and n are assumed to be positive integers).
.DS
.ft B
define b(n,m){
auto x, j
x=1
for(j=1; j<=m; j=j+1) x=x*(n\-j+1)/j
return(x)
}
.ft P
.DE
The following function computes values of the exponential function
by summing the appropriate series
without regard for possible truncation errors:
.DS
.ft B
scale = 20
define e(x){
auto a, b, c, d, n
a = 1
b = 1
c = 1
d = 0
n = 1
while(1==1){
a = a*x
b = b*n
c = c + a/b
n = n + 1
if(c==d) return(c)
d = c
}
}
.ft P
.DE
.SH
Some Details
.PP
There are some language features that every user should know
about even if he will not use them.
.PP
Normally statements are typed one to a line. It is also permissible
to type several statements on a line separated by semicolons.
.PP
If an assignment statement is parenthesized, it then has
a value and it can be used anywhere that an expression can.
For example, the line
.DS
.ft B
(x=y+17)
.ft P
.DE
not only makes the indicated assignment, but also prints the
resulting value.
.PP
Here is an example of a use of the value of an
assignment statement even when it is not parenthesized.
.DS
.ft B
x = a[i=i+1]
.ft P
.DE
causes a value to be assigned to x and also increments i
before it is used as a subscript.
.PP
The following constructs work in BC in exactly the same manner
as they do in the C language. Consult the appendix or the
C manuals [2] for their exact workings.
.DS
.ft B
.ta 2i
x=y=z is the same as x=(y=z)
x += y x = x+y
x \-= y x = x\-y
x *= y x = x*y
x /= y x = x/y
x %= y x = x%y
x ^= y x = x^y
x++ (x=x+1)\-1
x\-\- (x=x\-1)+1
++x x = x+1
\-\-x x = x\-1
.ft P
.DE
Even if you don't intend to use the constructs,
if you type one inadvertently, something correct but unexpected
may happen.
.SH
Three Important Things
.PP
1. To exit a BC program, type `quit'.
.PP
2. There is a comment convention identical to that of C and
of PL/I. Comments begin with `/*' and end with `*/'.
As a non-portable extension, comments may also start with a `#' and end with
a newline.
The newline is not part of the comment.
.PP
3. There is a library of math functions which may be obtained by
typing at command level
.DS
.ft B
bc \-l
.ft P
.DE
This command will load a set of library functions
which, at the time of writing, consists of sine (named `s'),
cosine (`c'), arctangent (`a'), natural logarithm (`l'),
exponential (`e') and Bessel functions of integer order (`j(n,x)'). Doubtless more functions will be added
in time.
The library sets the scale to 20. You can reset it to something
else if you like.
The design of these mathematical library routines
is discussed elsewhere [3].
.PP
If you type
.DS
.ft B
bc file ...
.ft P
.DE
BC will read and execute the named file or files before accepting
commands from the keyboard. In this way, you may load your
favorite programs and function definitions.
.SH
Acknowledgement
.PP
The compiler is written in YACC [4]; its original
version was written by S. C. Johnson.
.SH
References
.IP [1]
K. Thompson and D. M. Ritchie,
.ft I
UNIX Programmer's Manual,
.ft
Bell Laboratories,
1978.
.IP [2]
B. W. Kernighan and
D. M. Ritchie,
.ft I
The C Programming Language,
.ft
Prentice-Hall, 1978.
.IP [3]
R. Morris,
.ft I
A Library of Reference Standard Mathematical Subroutines,
.ft
Bell Laboratories internal memorandum, 1975.
.IP [4]
S. C. Johnson,
.ft I
YACC \(em Yet Another Compiler-Compiler.
.ft
Bell Laboratories Computing Science Technical Report #32, 1978.
.IP [5]
R. Morris and L. L. Cherry,
.ft I
DC \- An Interactive Desk Calculator.
.ft
.LP
.bp
.ft B
.DS C
Appendix
.DE
.ft
.NH
Notation
.PP
In the following pages syntactic categories are in \fIitalics\fP;
literals are in \fBbold\fP; material in brackets [\|] is optional.
.NH
Tokens
.PP
Tokens consist of keywords, identifiers, constants, operators,
and separators.
Token separators may be blanks, tabs or comments.
Newline characters or semicolons separate statements.
.NH 2
Comments
.PP
Comments are introduced by the characters /* and terminated by
*/.
As a non-portable extension, comments may also start with a # and
end with a newline.
The newline is not part of the comment.
.NH 2
Identifiers
.PP
There are three kinds of identifiers \- ordinary identifiers, array identifiers
and function identifiers.
All three types consist of single lower-case letters.
Array identifiers are followed by square brackets, possibly
enclosing an expression describing a subscript.
Arrays are singly dimensioned and may contain up to 2048
elements.
Indexing begins at zero so an array may be indexed from 0 to 2047.
Subscripts are truncated to integers.
Function identifiers are followed by parentheses, possibly enclosing arguments.
The three types of identifiers do not conflict;
a program can have a variable named \fBx\fP,
an array named \fBx\fP and a function named \fBx\fP, all of which are separate and
distinct.
.NH 2
Keywords
.PP
The following are reserved keywords:
.ft B
.ta .5i 1.0i
.nf
ibase if
obase break
scale define
sqrt auto
length return
while quit
for continue
else last
print
.fi
.ft
.NH 2
Constants
.PP
Constants consist of arbitrarily long numbers
with an optional decimal point.
The hexadecimal digits \fBA\fP\-\fBF\fP are also recognized as digits with
values 10\-15, respectively.
.NH 1
Expressions
.PP
The value of an expression is printed unless the main
operator is an assignment.
The value printed is assigned to the special variable \fBlast\fP.
A single dot may be used as a synonym for \fBlast\fP.
This is a non-portable extension.
Precedence is the same as the order
of presentation here, with highest appearing first.
Left or right associativity, where applicable, is
discussed with each operator.
.bp
.NH 2
Primitive expressions
.NH 3
Named expressions
.PP
Named expressions are
places where values are stored.
Simply stated,
named expressions are legal on the left
side of an assignment.
The value of a named expression is the value stored in the place named.
.NH 4
\fIidentifiers\fR
.PP
Simple identifiers are named expressions.
They have an initial value of zero.
.NH 4
\fIarray-name\fP\|[\|\fIexpression\fP\|]
.PP
Array elements are named expressions.
They have an initial value of zero.
.NH 4
\fBscale\fR, \fBibase\fR and \fBobase\fR
.PP
The internal registers
\fBscale\fP, \fBibase\fP and \fBobase\fP are all named expressions.
\fBscale\fP is the number of digits after the decimal point to be
retained in arithmetic operations.
\fBscale\fR has an initial value of zero.
\fBibase\fP and \fBobase\fP are the input and output number
radix respectively.
Both \fBibase\fR and \fBobase\fR have initial values of 10.
.NH 3
Function calls
.NH 4
\fIfunction-name\fB\|(\fR[\fIexpression\fR\|[\fB,\|\fIexpression\|\fR.\|.\|.\|]\|]\fB)
.PP
A function call consists of a function name followed by parentheses
containing a comma-separated list of
expressions, which are the function arguments.
A whole array passed as an argument is specified by the
array name followed by empty square brackets.
All function arguments are passed by
value.
As a result, changes made to the formal parameters have
no effect on the actual arguments.
If the function terminates by executing a return
statement, the value of the function is
the value of the expression in the parentheses of the return
statement or is zero if no expression is provided
or if there is no return statement.
.NH 4
sqrt\|(\|\fIexpression\fP\|)
.PP
The result is the square root of the expression.
The result is truncated in the least significant decimal place.
The scale of the result is
the scale of the expression or the
value of
.ft B
scale,
.ft
whichever is larger.
.NH 4
length\|(\|\fIexpression\fP\|)
.PP
The result is the total number of significant decimal digits in the expression.
The scale of the result is zero.
.NH 4
scale\|(\|\fIexpression\fP\|)
.PP
The result is the scale of the expression.
The scale of the result is zero.
.NH 3
Constants
.PP
Constants are primitive expressions.
.NH 3
Parentheses
.PP
An expression surrounded by parentheses is
a primitive expression.
The parentheses are used to alter the
normal precedence.
.NH 2
Unary operators
.PP
The unary operators
bind right to left.
.NH 3
\-\|\fIexpression\fP
.PP
The result is the negative of the expression.
.NH 3
++\|\fInamed-expression\fP
.PP
The named expression is
incremented by one.
The result is the value of the named expression after
incrementing.
.NH 3
\-\-\|\fInamed-expression\fP
.PP
The named expression is
decremented by one.
The result is the value of the named expression after
decrementing.
.NH 3
\fInamed-expression\fP\|++
.PP
The named expression is
incremented by one.
The result is the value of the named expression before
incrementing.
.NH 3
\fInamed-expression\fP\|\-\-
.PP
The named expression is
decremented by one.
The result is the value of the named expression before
decrementing.
.NH 2
Exponentiation operator
.PP
The exponentiation operator binds right to left.
.NH 3
\fIexpression\fP ^ \fIexpression\fP
.PP
The result is the first
expression raised to the power of the
second expression.
The second expression must be an integer.
If \fIa\fP
is the scale of the left expression
and \fIb\fP is the absolute value
of the right expression,
then the scale of the result is:
.PP
min\|(\|\fIa\(mub\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP\|)\|)
.NH 2
Multiplicative operators
.PP
The operators *, /, % bind left to right.
.NH 3
\fIexpression\fP * \fIexpression\fP
.PP
The result is the product
of the two expressions.
If \fIa\fP and \fIb\fP are the
scales of the two expressions,
then the scale of the result is:
.PP
min\|(\|\fIa+b\fP,\|max\|(\|\fBscale\fP,\|\fIa\fP,\|\fIb\fP\|)\|)
.NH 3
\fIexpression\fP / \fIexpression\fP
.PP
The result is the quotient of the two expressions.
The scale of the result is the value of \fBscale\fR.
.NH 3
\fIexpression\fP % \fIexpression\fP
.PP
The % operator produces the remainder of the division
of the two expressions.
More precisely,
\fIa\fP%\fIb\fP is \fIa\fP\-\fIa\fP/\fIb\fP*\fIb\fP.
.PP
The scale of the result is the sum of the scale of
the divisor and the value of
.ft B
scale
.ft
.NH 2
Additive operators
.PP
The additive operators bind left to right.
.NH 3
\fIexpression\fP + \fIexpression\fP
.PP
The result is the sum of the two expressions.
The scale of the result is
the maximum of the scales of the expressions.
.NH 3
\fIexpression\fP \- \fIexpression\fP
.PP
The result is the difference of the two expressions.
The scale of the result is the
maximum of the scales of the expressions.
.NH 2
assignment operators
.PP
The assignment operators bind right to left.
.NH 3
\fInamed-expression\fP = \fIexpression\fP
.PP
This expression results in assigning the value of the expression
on the right
to the named expression on the left.
.NH 3
\fInamed-expression\fP += \fIexpression\fP
.NH 3
\fInamed-expression\fP \-= \fIexpression\fP
.NH 3
\fInamed-expression\fP *= \fIexpression\fP
.NH 3
\fInamed-expression\fP /= \fIexpression\fP
.NH 3
\fInamed-expression\fP %= \fIexpression\fP
.NH 3
\fInamed-expression\fP ^= \fIexpression\fP
.PP
The result of the above expressions is equivalent
to ``named expression = named expression OP expression'',
where OP is the operator after the = sign.
.NH 1
Relations
.PP
Unlike all other operators, the relational operators
are only valid as the object of an \fBif\fP, \fBwhile\fP,
or inside a \fBfor\fP statement.
.NH 2
\fIexpression\fP < \fIexpression\fP
.NH 2
\fIexpression\fP > \fIexpression\fP
.NH 2
\fIexpression\fP <= \fIexpression\fP
.NH 2
\fIexpression\fP >= \fIexpression\fP
.NH 2
\fIexpression\fP == \fIexpression\fP
.NH 2
\fIexpression\fP != \fIexpression\fP
.NH 1
Storage classes
.PP
There are only two storage classes in BC, global and automatic
(local).
Only identifiers that are to be local to a function need be
declared with the \fBauto\fP command.
The arguments to a function
are local to the function.
All other identifiers are assumed to be global
and available to all functions.
All identifiers, global and local, have initial values
of zero.
Identifiers declared as \fBauto\fP are allocated on entry to the function
and released on returning from the function.
They therefore do not retain values between function calls.
\fBauto\fP arrays are specified by the array name followed by empty square brackets.
.PP
Automatic variables in BC do not work in exactly the same way
as in either C or PL/I. On entry to a function, the old values of
the names that appear as parameters and as automatic
variables are pushed onto a stack.
Until return is made from the function, reference to these
names refers only to the new values.
.NH 1
Statements
.PP
Statements must be separated by semicolon or newline.
Except where altered by control statements, execution
is sequential.
.NH 2
Expression statements
.PP
When a statement is an expression, unless
the main operator is an assignment, the value
of the expression is printed, followed by a newline character.
.NH 2
Compound statements
.PP
Statements may be grouped together and used when one statement is expected
by surrounding them with { }.
.NH 2
Quoted string statements
.PP
"any string"
.sp .5
This statement prints the string inside the quotes.
.NH 2
If statements
.sp .5
\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fR
.PP
The substatement is executed if the relation is true.
.NH 2
If-else statements
.sp .5
\fBif\|(\|\fIrelation\fB\|)\|\fIstatement\fB\|else\|\fIstatement\fR
.PP
The first substatement is executed if the relation is true, the second
substatement if the relation is false.
The \fBif-else\fR statement is a non-portable extension.
.NH 2
While statements
.sp .5
\fBwhile\|(\|\fIrelation\fB\|)\|\fIstatement\fR
.PP
The statement is executed while the relation
is true.
The test occurs before each execution of the statement.
.NH 2
For statements
.sp .5
\fBfor\|(\|\fIexpression\fB; \fIrelation\fB; \fIexpression\fB\|)\|\fIstatement\fR
.PP
The \fBfor\fR statement is the same as
.nf
.ft I
first-expression
\fBwhile\|(\fPrelation\|\fB) {\fP
statement
last-expression
}
.ft R
.fi
.PP
All three expressions may be left out.
This is a non-portable extension.
.NH 2
Break statements
.sp .5
\fBbreak\fP
.PP
\fBbreak\fP causes termination of a \fBfor\fP or \fBwhile\fP statement.
.NH 2
Continue statements
.sp .5
\fBcontinue\fP
.PP
\fBcontinue\fP causes the next iteration of a \fBfor\fP or \fBwhile\fP
statement to start, skipping the remainder of the loop.
For a \fBwhile\fP statement, execution continues with the evaluation
of the condition.
For a \fBfor\fP statement, execution continues with evaluation of
the last-expression.
The \fBcontinue\fP statement is a non-portable extension.
.NH 2
Auto statements
.sp .5
\fBauto \fIidentifier\fR\|[\|\fB,\fIidentifier\fR\|]
.PP
The \fBauto\fR statement causes the values of the identifiers to be pushed down.
The identifiers can be ordinary identifiers or array identifiers.
Array identifiers are specified by following the array name by empty square
brackets.
The auto statement must be the first statement
in a function definition.
.NH 2
Define statements
.sp .5
.nf
\fBdefine(\|\fR[\fIparameter\|\fR[\fB\|,\|\fIparameter\|.\|.\|.\|\fR]\|]\|\fB)\|{\fI
statements\|\fB}\fR
.fi
.PP
The \fBdefine\fR statement defines a function.
The parameters may
be ordinary identifiers or array names.
Array names must be followed by empty square brackets.
As a non-portable extension, the opening brace may also appear on the
next line.
.NH 2
Return statements
.sp .5
\fBreturn\fP
.sp .5
\fBreturn(\fI\|expression\|\fB)\fR
.PP
The \fBreturn\fR statement causes termination of a function,
popping of its auto variables, and
specifies the result of the function.
The first form is equivalent to \fBreturn(0)\fR.
The result of the function is the result of the expression
in parentheses.
Leaving out the expression between parentheses is equivalent to
\fBreturn(0)\fR.
As a non-portable extension, the parentheses may be left out.
.NH 2
Print
.PP
The \fBprint\fR statement takes a list of comma-separated expressions.
Each expression in the list is evaluated and the computed
value is printed and assigned to the variable `last'.
No trailing newline is printed.
The expression may also be a string enclosed in double quotes.
Within these strings the following escape sequences may be used:
\ea
for bell (alert),
`\eb'
for backspace,
`\ef'
for formfeed,
`\en'
for newline,
`\er'
for carriage return,
`\et'
`for tab,
`\eq'
for double quote and
`\e\e'
for backslash.
Any other character following a backslash will be ignored.
Strings will not be assigned to `last'.
The \fBprint\fR statement is a non-portable extension.
.NH 2
Quit
.PP
The \fBquit\fR statement stops execution of a BC program and returns
control to UNIX when it is first encountered.
Because it is not treated as an executable statement,
it cannot be used
in a function definition or in an
.ft B
if, for,
.ft
or
.ft B
while
.ft
statement.
Index: head/share/doc/usd/10.exref/exref/ex.rm
===================================================================
--- head/share/doc/usd/10.exref/exref/ex.rm (revision 282217)
+++ head/share/doc/usd/10.exref/exref/ex.rm (revision 282218)
@@ -1,2213 +1,2215 @@
.\" Copyright (c) 1980, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)ex.rm 8.5 (Berkeley) 8/18/96
+.\" $FreeBSD$
.\"
.nr LL 6.5i
.nr FL 6.5i
.EH 'USD:12-%''Ex Reference Manual'
.OH 'Ex Reference Manual''USD:12-%'
+.ND
.nr )P 0
.de ZP
.nr pd \\n()P
.nr )P 0
.if \\n(.$=0 .IP
.if \\n(.$=1 .IP "\\$1"
.if \\n(.$>=2 .IP "\\$1" "\\$2"
.nr )P \\n(pd
.rm pd
..
.de LC
.br
.sp .1i
.ne 4
.LP
.ta 4.0i
..
.bd S B 3
.\".RP
.TL
Ex Reference Manual
.br
Version 3.7
.AU
William Joy
.AU
Mark Horton
.AI
Computer Science Division
Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, Ca. 94720
.AB
.I Ex
a line oriented text editor, which supports both command and display
oriented editing.
This reference manual describes the command oriented part of
.I ex;
the display editing features of
.I ex
are described in
.I "An Introduction to Display Editing with Vi."
Other documents about the editor include the introduction
.I "Edit: A tutorial",
the
.I "Ex/edit Command Summary",
and a
.I "Vi Quick Reference"
card.
.AE
.NH 1
Starting ex
.PP
.FS
The financial support of an \s-2IBM\s0 Graduate Fellowship and the National
Science Foundation under grants MCS74-07644-A03 and MCS78-07291 is gratefully
acknowledged.
.FE
Each instance of the editor has a set of options,
which can be set to tailor it to your liking.
The command
.I edit
invokes a version of
.I ex
designed for more casual or beginning
users by changing the default settings of some of these options.
To simplify the description which follows we
assume the default settings of the options.
.PP
When invoked,
.I ex
determines the terminal type from the \s-2TERM\s0 variable in the environment.
It there is a \s-2TERMCAP\s0 variable in the environment, and the type
of the terminal described there matches the \s-2TERM\s0 variable,
then that description
is used. Also if the \s-2TERMCAP\s0 variable contains a pathname (beginning
with a \fB/\fR) then the editor will seek the description of the terminal
in that file (rather than the default /etc/termcap).
If there is a variable \s-2EXINIT\s0 in the environment, then the editor
will execute the commands in that variable,
otherwise if there is a file
.I \&.exrc
in your \s-2HOME\s0 directory
.I ex
reads commands from that file, simulating a
.I source
command.
Option setting commands placed in
\s-2EXINIT\s0 or
.I \&.exrc
will be executed before each editor session.
.PP
A command to enter
.I ex
has the following prototype:\(dg
.FS
\(dg Brackets `[' `]' surround optional parameters here.
.FE
.DS
\fBex\fP [ \fB\-\fP ] [ \fB\-v\fP ] [ \fB\-t\fP \fItag\fP ] [ \fB\-r\fP ] [ \fB\-l\fP ] [ \fB\-w\fP\fIn\fP ] [ \fB\-x\fP ] [ \fB\-R\fP ] [ \fB+\fP\fIcommand\fP ] name ...
.DE
The most common case edits a single file with no options, i.e.:
.DS
\fBex\fR name
.DE
The
.B \-
command line option
option suppresses all interactive-user feedback
and is useful in processing editor scripts in command files.
The
.B \-v
option is equivalent to using
.I vi
rather than
.I ex.
The
.B \-t
option is equivalent to an initial
.I tag
command, editing the file containing the
.I tag
and positioning the editor at its definition.
The
.B \-r
option is used in recovering after an editor or system crash,
retrieving the last saved version of the named file or,
if no file is specified,
typing a list of saved files.
The
.B \-l
option sets up for editing \s-2LISP\s0, setting the
.I showmatch
and
.I lisp
options.
The
.B \-w
option sets the default window size to
.I n,
and is useful on dialups to start in small windows.
The
.B \-x
option causes
.I ex
to prompt for a
.I key ,
which is used to encrypt and decrypt the contents of the file,
which should already be encrypted using the same key,
see
.I crypt (1).
The
.B \-R
option sets the
.I readonly
option at the start.
.I Name
arguments indicate files to be edited.
An argument of the form
\fB+\fIcommand\fR
indicates that the editor should begin by executing the specified command.
If
.I command
is omitted, then it defaults to ``$'', positioning the editor at the last
line of the first file initially. Other useful commands here are scanning
patterns of the form ``/pat'' or line numbers, e.g. ``+100'' starting
at line 100.
.NH 1
File manipulation
.NH 2
Current file
.PP
.I Ex
is normally editing the contents of a single file,
whose name is recorded in the
.I current
file name.
.I Ex
performs all editing actions in a buffer
(actually a temporary file)
into which the text of the file is initially read.
Changes made to the buffer have no effect on the file being
edited unless and until the buffer contents are written out to the
file with a
.I write
command.
After the buffer contents are written,
the previous contents of the written file are no longer accessible.
When a file is edited,
its name becomes the current file name,
and its contents are read into the buffer.
.PP
The current file is almost always considered to be
.I edited.
This means that the contents of the buffer are logically
connected with the current file name,
so that writing the current buffer contents onto that file,
even if it exists,
is a reasonable action.
If the current file is not
.I edited
then
.I ex
will not normally write on it if it already exists.*
.FS
* The
.I file
command will say ``[Not edited]'' if the current file is not considered
edited.
.FE
.NH 2
Alternate file
.PP
Each time a new value is given to the current file name,
the previous current file name is saved as the
.I alternate
file name.
Similarly if a file is mentioned but does not become the current file,
it is saved as the alternate file name.
.NH 2
Filename expansion
.PP
Filenames within the editor may be specified using the normal
shell expansion conventions.
In addition,
the character `%' in filenames is replaced by the
.I current
file name and the character
`#' by the
.I alternate
file name.\(dg
.FS
\(dg This makes it easy to deal alternately with
two files and eliminates the need for retyping the
name supplied on an
.I edit
command after a
.I "No write since last change"
diagnostic is received.
.FE
.NH 2
Multiple files and named buffers
.PP
If more than one file is given on the command line,
then the first file is edited as described above.
The remaining arguments are placed with the first file in the
.I "argument list."
The current argument list may be displayed with the
.I args
command.
The next file in the argument list may be edited with the
.I next
command.
The argument list may also be respecified by specifying
a list of names to the
.I next
command.
These names are expanded,
the resulting list of names becomes the new argument list,
and
.I ex
edits the first file on the list.
.PP
For saving blocks of text while editing, and especially when editing
more than one file,
.I ex
has a group of named buffers.
These are similar to the normal buffer, except that only a limited number
of operations are available on them.
The buffers have names
.I a
through
.I z.\(dd
.FS
\(dd It is also possible to refer to
.I A
through
.I Z;
the upper case buffers are the same as the lower but commands
append to named buffers rather than replacing
if upper case names are used.
.FE
.NH 2
Read only
.PP
It is possible to use
.I ex
in
.I "read only"
mode to look at files that you have no intention of modifying.
This mode protects you from accidently overwriting the file.
Read only mode is on when the
.I readonly
option is set.
It can be turned on with the
.B \-R
command line option,
by the
.I view
command line invocation,
or by setting the
.I readonly
option.
It can be cleared by setting
.I noreadonly .
It is possible to write, even while in read only mode, by indicating
that you really know what you are doing.
You can write to a different file, or can use the ! form of write,
even while in read only mode.
.NH 1
Exceptional Conditions
.NH 2
Errors and interrupts
.PP
When errors occur
.I ex
(optionally) rings the terminal bell and, in any case, prints an error
diagnostic. If the primary input is from a file, editor processing
will terminate. If an interrupt signal is received,
.I ex
prints ``Interrupt'' and returns to its command level. If the primary
input is a file, then
.I ex
will exit when this occurs.
.NH 2
Recovering from hangups and crashes
.PP
If a hangup signal is received and the buffer has been modified since
it was last written out, or if the system crashes, either the editor
(in the first case) or the system (after it reboots in the second) will
attempt to preserve the buffer. The next time you log in you should be
able to recover the work you were doing, losing at most a few lines of
changes from the last point before the hangup or editor crash. To
recover a file you can use the
.B \-r
option. If you were editing the file
.I resume,
then you should change
to the directory where you were when the crash occurred, giving the command
.DS
\fBex \-r\fP\fI resume\fP
.DE
After checking that the retrieved file is indeed ok, you can
.I write
it over the previous contents of that file.
.PP
You will normally get mail from the system telling you when a file has
been saved after a crash. The command
.DS
\fBex\fP \-\fBr\fP
.DE
will print a list of the files which have been saved for you.
(In the case of a hangup,
the file will not appear in the list,
although it can be recovered.)
.NH 1
Editing modes
.PP
.I Ex
has five distinct modes. The primary mode is
.I command
mode. Commands are entered in command mode when a `:' prompt is
present, and are executed each time a complete line is sent. In
.I "text input"
mode
.I ex
gathers input lines and places them in the file. The
.I append,
.I insert,
and
.I change
commands use text input mode.
No prompt is printed when you are in text input mode.
This mode is left by typing a `.' alone at the beginning of a line, and
.I command
mode resumes.
.PP
The last three modes are
.I open
and
.I visual
modes, entered by the commands of the same name, and, within open and
visual modes
.I "text insertion"
mode.
.I Open
and
.I visual
modes allow local editing operations to be performed on the text in the
file. The
.I open
command displays one line at a time on any terminal while
.I visual
works on \s-2CRT\s0 terminals with random positioning cursors, using the
screen as a (single) window for file editing changes.
These modes are described (only) in
.I "An Introduction to Display Editing with Vi."
.NH
Command structure
.PP
Most command names are English words,
and initial prefixes of the words are acceptable abbreviations.
The ambiguity of abbreviations is resolved in favor of the more commonly
used commands.*
.FS
* As an example, the command
.I substitute
can be abbreviated `s'
while the shortest available abbreviation for the
.I set
command is `se'.
.FE
.NH 2
Command parameters
.PP
Most commands accept prefix addresses specifying the lines in the file
upon which they are to have effect.
The forms of these addresses will be discussed below.
A number of commands also may take a trailing
.I count
specifying the number of lines to be involved in the command.\(dg
.FS
\(dg Counts are rounded down if necessary.
.FE
Thus the command ``10p'' will print the tenth line in the buffer while
``delete 5'' will delete five lines from the buffer,
starting with the current line.
.PP
Some commands take other information or parameters,
this information always being given after the command name.\(dd
.FS
\(dd Examples would be option names in a
.I set
command i.e. ``set number'',
a file name in an
.I edit
command,
a regular expression in a
.I substitute
command,
or a target address for a
.I copy
command, i.e. ``1,5 copy 25''.
.FE
.NH 2
Command variants
.PP
A number of commands have two distinct variants.
The variant form of the command is invoked by placing an
`!' immediately after the command name.
Some of the default variants may be controlled by options;
in this case, the `!' serves to toggle the default.
.NH 2
Flags after commands
.PP
The characters `#', `p' and `l' may be placed after many commands.**
.FS
**
A `p' or `l' must be preceded by a blank or tab
except in the single special case `dp'.
.FE
In this case, the command abbreviated by these characters
is executed after the command completes.
Since
.I ex
normally prints the new current line after each change, `p' is rarely necessary.
Any number of `+' or `\-' characters may also be given with these flags.
If they appear, the specified offset is applied to the current line
value before the printing command is executed.
.NH 2
Comments
.PP
It is possible to give editor commands which are ignored.
This is useful when making complex editor scripts
for which comments are desired.
The comment character is the double quote: ".
Any command line beginning with " is ignored.
Comments beginning with " may also be placed at the ends
of commands, except in cases where they could be confused as part
of text (shell escapes and the substitute and map commands).
.NH 2
Multiple commands per line
.PP
More than one command may be placed on a line by separating each pair
of commands by a `|' character.
However the
.I global
commands,
comments,
and the shell escape `!'
must be the last command on a line, as they are not terminated by a `|'.
.NH 2
Reporting large changes
.PP
Most commands which change the contents of the editor buffer give
feedback if the scope of the change exceeds a threshold given by the
.I report
option.
This feedback helps to detect undesirably large changes so that they may
be quickly and easily reversed with an
.I undo.
After commands with more global effect such as
.I global
or
.I visual,
you will be informed if the net change in the number of lines
in the buffer during this command exceeds this threshold.
.NH 1
Command addressing
.NH 2
Addressing primitives
.IP \fB.\fR 20
The current line.
Most commands leave the current line as the last line which they affect.
The default address for most commands is the current line,
thus `\fB.\fR' is rarely used alone as an address.
.IP \fIn\fR 20
The \fIn\fRth line in the editor's buffer, lines being numbered
sequentially from 1.
.IP \fB$\fR 20
The last line in the buffer.
.IP \fB%\fR 20
An abbreviation for ``1,$'', the entire buffer.
.IP \fI+n\fR\ \fI\-n\fR 20
An offset relative to the current buffer line.\(dg
.FS
\(dg
The forms `.+3' `+3' and `+++' are all equivalent;
if the current line is line 100 they all address line 103.
.FE
.IP \fB/\fIpat\fR\fB/\fR\ \fB?\fIpat\fR\fB?\fR 20
Scan forward and backward respectively for a line containing \fIpat\fR, a
regular expression (as defined below). The scans normally wrap around the end
of the buffer.
If all that is desired is to print the next line containing \fIpat\fR, then
the trailing \fB/\fR or \fB?\fR may be omitted.
If \fIpat\fP is omitted or explicitly empty, then the last
regular expression specified is located.\(dd
.FS
\(dd The forms \fB\e/\fP and \fB\e?\fP scan
using the last regular expression used in a scan; after a substitute
\fB//\fP and \fB??\fP would scan using the substitute's regular expression.
.FE
.IP \fB\(aa\(aa\fP\ \fB\(aa\fP\fIx\fP 20
Before each non-relative motion of the current line `\fB.\fP',
the previous current line is marked with a tag, subsequently referred to as
`\(aa\(aa'.
This makes it easy to refer or return to this previous context.
Marks may also be established by the
.I mark
command, using single lower case letters
.I x
and the marked lines referred to as
`\(aa\fIx\fR'.
.NH 2
Combining addressing primitives
.PP
Addresses to commands consist of a series of addressing primitives,
separated by `,' or `;'.
Such address lists are evaluated left-to-right.
When addresses are separated by `;' the current line `\fB.\fR'
is set to the value of the previous addressing expression
before the next address is interpreted.
If more addresses are given than the command requires,
then all but the last one or two are ignored.
If the command takes two addresses, the first addressed line must
precede the second in the buffer.\(dg
.FS
\(dg Null address specifications are permitted in a list of addresses,
the default in this case is the current line `.';
thus `,100' is equivalent to `\fB.\fR,100'.
It is an error to give a prefix address to a command which expects none.
.FE
.NH 1
Command descriptions
.PP
The following form is a prototype for all
.I ex
commands:
.DS
\fIaddress\fR \fBcommand\fR \fI! parameters count flags\fR
.DE
All parts are optional; the degenerate case is the empty command which prints
the next line in the file. For sanity with use from within
.I visual
mode,
.I ex
ignores a ``:'' preceding any command.
.PP
In the following command descriptions, the
default addresses are shown in parentheses,
which are
.I not,
however,
part of the command.
.LC
\fBabbreviate\fR \fIword rhs\fP abbr: \fBab\fP
.ZP
Add the named abbreviation to the current list.
When in input mode in visual, if
.I word
is typed as a complete word, it will be changed to
.I rhs .
.LC
( \fB.\fR ) \fBappend\fR abbr: \fBa\fR
.br
\fItext\fR
.br
\&\fB.\fR
.ZP
Reads the input text and places it after the specified line.
After the command, `\fB.\fR'
addresses the last line input or the
specified line if no lines were input.
If address `0' is given,
text is placed at the beginning of the buffer.
.LC
\fBa!\fR
.br
\fItext\fR
.br
\&\fB.\fR
.ZP
The variant flag to
.I append
toggles the setting for the
.I autoindent
option during the input of
.I text.
.LC
\fBargs\fR
.ZP
The members of the argument list are printed, with the current argument
delimited by `[' and `]'.
.ig
.PP
\fBcd\fR \fIdirectory\fR
.ZP
The
.I cd
command is a synonym for
.I chdir.
..
.LC
( \fB.\fP , \fB.\fP ) \fBchange\fP \fIcount\fP abbr: \fBc\fP
.br
\fItext\fP
.br
\&\fB.\fP
.ZP
Replaces the specified lines with the input \fItext\fP.
The current line becomes the last line input;
if no lines were input it is left as for a
\fIdelete\fP.
.LC
\fBc!\fP
.br
\fItext\fP
.br
\&\fB.\fP
.ZP
The variant toggles
.I autoindent
during the
.I change.
.ig
.LC
\fBchdir\fR \fIdirectory\fR
.ZP
The specified \fIdirectory\fR becomes the current directory.
If no directory is specified, the current value of the
.I home
option is used as the target directory.
After a
.I chdir
the current file is not considered to have been
edited so that write restrictions on pre-existing files apply.
..
.LC
( \fB.\fP , \fB.\fP )\|\fBcopy\fP \fIaddr\fP \fIflags\fP abbr: \fBco\fP
.ZP
A
.I copy
of the specified lines is placed after
.I addr,
which may be `0'.
The current line
`\fB.\fR'
addresses the last line of the copy.
The command
.I t
is a synonym for
.I copy.
.LC
( \fB.\fR , \fB.\fR )\|\fBdelete\fR \fIbuffer\fR \fIcount\fR \fIflags\fR abbr: \fBd\fR
.ZP
Removes the specified lines from the buffer.
The line after the last line deleted becomes the current line;
if the lines deleted were originally at the end,
the new last line becomes the current line.
If a named
.I buffer
is specified by giving a letter,
then the specified lines are saved in that buffer,
or appended to it if an upper case letter is used.
.LC
\fBedit\fR \fIfile\fR abbr: \fBe\fR
.br
\fBex\fR \fIfile\fR
.ZP
Used to begin an editing session on a new file.
The editor
first checks to see if the buffer has been modified since the last
.I write
command was issued.
If it has been,
a warning is issued and the
command is aborted.
The
command otherwise deletes the entire contents of the editor buffer,
makes the named file the current file and prints the new filename.
After insuring that this file is sensible\(dg
.FS
\(dg I.e., that it is not a binary file such as a directory,
a block or character special file other than
.I /dev/tty,
a terminal,
or a binary or executable file
(as indicated by the first word).
.FE
the editor reads the file into its buffer.
.IP
If the read of the file completes without error,
the number of lines and characters read is typed.
If there were any non-\s-2ASCII\s0 characters
in the file they are stripped of their non-\s-2ASCII\s0
high bits,
and any null characters in the file are discarded.
If none of these errors occurred, the file is considered
.I edited.
If the last line of the input file is missing the trailing
newline character, it will be supplied and a complaint will be issued.
This command leaves the current line `\fB.\fR' at the last line read.\(dd
.FS
\(dd If executed from within
.I open
or
.I visual,
the current line is initially the first line of the file.
.FE
.LC
\fBe!\fR \fIfile\fR
.ZP
The variant form suppresses the complaint about modifications having
been made and not written from the editor buffer, thus
discarding all changes which have been made before editing the new file.
.LC
\fBe\fR \fB+\fIn\fR \fIfile\fR
.ZP
Causes the editor to begin at line
.I n
rather than at the last line;
\fIn\fR may also be an editor command containing no spaces, e.g.: ``+/pat''.
.LC
\fBfile\fR abbr: \fBf\fR
.ZP
Prints the current file name,
whether it has been `[Modified]' since the last
.I write
command,
whether it is
.I "read only" ,
the current line,
the number of lines in the buffer,
and the percentage of the way through the buffer of the current line.*
.FS
* In the rare case that the current file is `[Not edited]' this is
noted also; in this case you have to use the form \fBw!\fR to write to
the file, since the editor is not sure that a \fBwrite\fR will not
destroy a file unrelated to the current contents of the buffer.
.FE
.LC
\fBfile\fR \fIfile\fR
.ZP
The current file name is changed to
.I file
which is considered
`[Not edited]'.
.LC
( 1 , $ ) \fBglobal\fR /\fIpat\|\fR/ \fIcmds\fR abbr: \fBg\fR
.ZP
First marks each line among those specified which matches
the given regular expression.
Then the given command list is executed with `\fB.\fR' initially
set to each marked line.
.IP
The command list consists of the remaining commands on the current
input line and may continue to multiple lines by ending all but the
last such line with a `\e'.
If
.I cmds
(and possibly the trailing \fB/\fR delimiter) is omitted, each line matching
.I pat
is printed.
.I Append,
.I insert,
and
.I change
commands and associated input are permitted;
the `\fB.\fR' terminating input may be omitted if it would be on the
last line of the command list.
.I Open
and
.I visual
commands are permitted in the command list and take input from the terminal.
.IP
The
.I global
command itself may not appear in
.I cmds.
The
.I undo
command is also not permitted there,
as
.I undo
instead can be used to reverse the entire
.I global
command.
The options
.I autoprint
and
.I autoindent
are inhibited during a
.I global,
(and possibly the trailing \fB/\fR delimiter) and the value of the
.I report
option is temporarily infinite,
in deference to a \fIreport\fR for the entire global.
Finally, the context mark `\'\'' is set to the value of
`.' before the global command begins and is not changed during a global
command,
except perhaps by an
.I open
or
.I visual
within the
.I global.
.LC
\fBg!\fR \fB/\fIpat\fB/\fR \fIcmds\fR abbr: \fBv\fR
.IP
The variant form of \fIglobal\fR runs \fIcmds\fR at each line not matching
\fIpat\fR.
.LC
( \fB.\fR )\|\fBinsert\fR abbr: \fBi\fR
.br
\fItext\fR
.br
\&\fB.\fR
.ZP
Places the given text before the specified line.
The current line is left at the last line input;
if there were none input it is left at the line before the addressed line.
This command differs from
.I append
only in the placement of text.
.KS
.LC
\fBi!\fR
.br
\fItext\fR
.br
\&\fB.\fR
.ZP
The variant toggles
.I autoindent
during the
.I insert.
.KE
.LC
( \fB.\fR , \fB.\fR+1 ) \fBjoin\fR \fIcount\fR \fIflags\fR abbr: \fBj\fR
.ZP
Places the text from a specified range of lines
together on one line.
White space is adjusted at each junction to provide at least
one blank character, two if there was a `\fB.\fR' at the end of the line,
or none if the first following character is a `)'.
If there is already white space at the end of the line,
then the white space at the start of the next line will be discarded.
.LC
\fBj!\fR
.ZP
The variant causes a simpler
.I join
with no white space processing; the characters in the lines are simply
concatenated.
.LC
( \fB.\fR ) \fBk\fR \fIx\fR
.ZP
The
.I k
command is a synonym for
.I mark.
It does not require a blank or tab before the following letter.
.LC
( \fB.\fR , \fB.\fR ) \fBlist\fR \fIcount\fR \fIflags\fR
.ZP
Prints the specified lines in a more unambiguous way:
tabs are printed as `^I'
and the end of each line is marked with a trailing `$'.
The current line is left at the last line printed.
.LC
\fBmap\fR \fIlhs\fR \fIrhs\fR
.ZP
The
.I map
command is used to define macros for use in
.I visual
mode.
.I Lhs
should be a single character, or the sequence ``#n'', for n a digit,
referring to function key \fIn\fR. When this character or function key
is typed in
.I visual
mode, it will be as though the corresponding \fIrhs\fR had been typed.
On terminals without function keys, you can type ``#n''.
See section 6.9 of the ``Introduction to Display Editing with Vi''
for more details.
.LC
( \fB.\fR ) \fBmark\fR \fIx\fR
.ZP
Gives the specified line mark
.I x,
a single lower case letter.
The
.I x
must be preceded by a blank or a tab.
The addressing form `\'x' then addresses this line.
The current line is not affected by this command.
.LC
( \fB.\fR , \fB.\fR ) \fBmove\fR \fIaddr\fR abbr: \fBm\fR
.ZP
The
.I move
command repositions the specified lines to be after
.I addr .
The first of the moved lines becomes the current line.
.LC
\fBnext\fR abbr: \fBn\fR
.ZP
The next file from the command line argument list is edited.
.LC
\fBn!\fR
.ZP
The variant suppresses warnings about the modifications to the buffer not
having been written out, discarding (irretrievably) any changes which may
have been made.
.LC
\fBn\fR \fIfilelist\fR
.br
\fBn\fR \fB+\fIcommand\fR \fIfilelist\fR
.ZP
The specified
.I filelist
is expanded and the resulting list replaces the
current argument list;
the first file in the new list is then edited.
If
.I command
is given (it must contain no spaces), then it is executed after editing the first such file.
.LC
( \fB.\fR , \fB.\fR ) \fBnumber\fR \fIcount\fR \fIflags\fR abbr: \fB#\fR or \fBnu\fR
.ZP
Prints each specified line preceded by its buffer line
number.
The current line is left at the last line printed.
.KS
.LC
( \fB.\fR ) \fBopen\fR \fIflags\fR abbr: \fBo\fR
.br
( \fB.\fR ) \fBopen\fR /\fIpat\|\fR/ \fIflags\fR
.ZP
Enters intraline editing \fIopen\fR mode at each addressed line.
If
.I pat
is given,
then the cursor will be placed initially at the beginning of the
string matched by the pattern.
To exit this mode use Q.
See
.I "An Introduction to Display Editing with Vi"
for more details.
.KE
.LC
\fBpreserve\fR
.ZP
The current editor buffer is saved as though the system had just crashed.
This command is for use only in emergencies when a
.I write
command has resulted in an error and you don't know how to save your work.
After a
.I preserve
you should seek help.
.LC
( \fB.\fR , \fB.\fR )\|\fBprint\fR \fIcount\fR abbr: \fBp\fR or \fBP\fR
.ZP
Prints the specified lines
with non-printing characters printed as control characters `^\fIx\fR\|';
delete (octal 177) is represented as `^?'.
The current line is left at the last line printed.
.LC
( \fB.\fR )\|\fBput\fR \fIbuffer\fR abbr: \fBpu\fR
.ZP
Puts back
previously
.I deleted
or
.I yanked
lines.
Normally used with
.I delete
to effect movement of lines,
or with
.I yank
to effect duplication of lines.
If no
.I buffer
is specified, then the last
.I deleted
or
.I yanked
text is restored.*
.FS
* But no modifying commands may intervene between the
.I delete
or
.I yank
and the
.I put,
nor may lines be moved between files without using a named buffer.
.FE
By using a named buffer, text may be restored that was saved there at any
previous time.
.LC
\fBquit\fR abbr: \fBq\fR
.ZP
Causes
.I ex
to terminate.
No automatic write of the editor buffer to a file is performed.
However,
.I ex
issues a warning message if the file has changed
since the last
.I write
command was issued, and does not
.I quit.\(dg
.FS
\(dg \fIEx\fR
will also issue a diagnostic if there are more files in the argument
list.
.FE
Normally, you will wish to save your changes, and you
should give a \fIwrite\fR command;
if you wish to discard them, use the \fBq!\fR command variant.
.LC
\fBq!\fR
.ZP
Quits from the editor, discarding changes to the buffer without complaint.
.LC
( \fB.\fR ) \fBread\fR \fIfile\fR abbr: \fBr\fR
.ZP
Places a copy of the text of the given file in the
editing buffer after the specified line.
If no
.I file
is given the current file name is used.
The current file name is not changed unless there is none in which
case
.I file
becomes the current name.
The sensibility restrictions for the
.I edit
command apply here also.
If the file buffer is empty and there is no current name then
.I ex
treats this as an
.I edit
command.
.IP
Address `0' is legal for this command and causes the file to be read at
the beginning of the buffer.
Statistics are given as for the
.I edit
command when the
.I read
successfully terminates.
After a
.I read
the current line is the last line read.\(dd
.FS
\(dd Within
.I open
and
.I visual
the current line is set to the first line read rather than the last.
.FE
.LC
( \fB.\fR ) \fBread\fR \fB!\fR\fIcommand\fR
.ZP
Reads the output of the command
.I command
into the buffer after the specified line.
This is not a variant form of the command, rather a read
specifying a
.I command
rather than a
.I filename;
a blank or tab before the \fB!\fR is mandatory.
.LC
\fBrecover \fIfile\fR
.ZP
Recovers
.I file
from the system save area.
Used after a accidental hangup of the phone**
.FS
** The system saves a copy of the file you were editing only if you
have made changes to the file.
.FE
or a system crash** or
.I preserve
command.
Except when you use
.I preserve
you will be notified by mail when a file is saved.
.LC
\fBrewind\fR abbr: \fBrew\fR
.ZP
The argument list is rewound, and the first file in the list is edited.
.LC
\fBrew!\fR
.ZP
Rewinds the argument list discarding any changes made to the current buffer.
.LC
\fBset\fR \fIparameter\fR
.ZP
With no arguments, prints those options whose values have been
changed from their defaults;
with parameter
.I all
it prints all of the option values.
.IP
Giving an option name followed by a `?'
causes the current value of that option to be printed.
The `?' is unnecessary unless the option is Boolean valued.
Boolean options are given values either by the form
`set \fIoption\fR' to turn them on or
`set no\fIoption\fR' to turn them off;
string and numeric options are assigned via the form
`set \fIoption\fR=value'.
.IP
More than one parameter may be given to
.I set \|;
they are interpreted left-to-right.
.LC
\fBshell\fR abbr: \fBsh\fR
.IP
A new shell is created.
When it terminates, editing resumes.
.LC
\fBsource\fR \fIfile\fR abbr: \fBso\fR
.IP
Reads and executes commands from the specified file.
.I Source
commands may be nested.
.LC
( \fB.\fR , \fB.\fR ) \fBsubstitute\fR /\fIpat\fR\|/\fIrepl\fR\|/ \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR
.IP
On each specified line, the first instance of pattern
.I pat
is replaced by replacement pattern
.I repl.
If the
.I global
indicator option character `g'
appears, then all instances are substituted;
if the
.I confirm
indication character `c' appears,
then before each substitution the line to be substituted
is typed with the string to be substituted marked
with `\(ua' characters.
By typing an `y' one can cause the substitution to be performed,
any other input causes no change to take place.
After a
.I substitute
the current line is the last line substituted.
.IP
Lines may be split by substituting
new-line characters into them.
The newline in
.I repl
must be escaped by preceding it with a `\e'.
Other metacharacters available in
.I pat
and
.I repl
are described below.
.LC
.B stop
.ZP
Suspends the editor, returning control to the top level shell.
If
.I autowrite
is set and there are unsaved changes,
a write is done first unless the form
.B stop !
is used.
This commands is only available where supported by the teletype driver
and operating system.
.LC
( \fB.\fR , \fB.\fR ) \fBsubstitute\fR \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR
.ZP
If
.I pat
and
.I repl
are omitted, then the last substitution is repeated.
This is a synonym for the
.B &
command.
.LC
( \fB.\fR , \fB.\fR ) \fBt\fR \fIaddr\fR \fIflags\fR
.ZP
The
.I t
command is a synonym for
.I copy .
.LC
\fBta\fR \fItag\fR
.ZP
The focus of editing switches to the location of
.I tag,
switching to a different line in the current file where it is defined,
or if necessary to another file.\(dd
.FS
\(dd If you have modified the current file before giving a
.I tag
command, you must write it out; giving another
.I tag
command, specifying no
.I tag
will reuse the previous tag.
.FE
.IP
The tags file is normally created by a program such as
.I ctags,
and consists of a number of lines with three fields separated by blanks
or tabs. The first field gives the name of the tag,
the second the name of the file where the tag resides, and the third
gives an addressing form which can be used by the editor to find the tag;
this field is usually a contextual scan using `/\fIpat\fR/' to be immune
to minor changes in the file. Such scans are always performed as if
.I nomagic
was set.
.PP
The tag names in the tags file must be sorted alphabetically.
.LC
\fBunabbreviate\fR \fIword\fP abbr: \fBuna\fP
.ZP
Delete
.I word
from the list of abbreviations.
.LC
\fBundo\fR abbr: \fBu\fR
.ZP
Reverses the changes made in the buffer by the last
buffer editing command.
Note that
.I global
commands are considered a single command for the purpose of
.I undo
(as are
.I open
and
.I visual.)
Also, the commands
.I write
and
.I edit
which interact with the
file system cannot be undone.
.I Undo
is its own inverse.
.IP
.I Undo
always marks the previous value of the current line `\fB.\fR'
as `\'\''.
After an
.I undo
the current line is the first line restored
or the line before the first line deleted if no lines were restored.
For commands with more global effect
such as
.I global
and
.I visual
the current line regains it's pre-command value after an
.I undo.
.LC
\fBunmap\fR \fIlhs\fR
.ZP
The macro expansion associated by
.I map
for
.I lhs
is removed.
.LC
( 1 , $ ) \fBv\fR /\fIpat\fR\|/ \fIcmds\fR
.ZP
A synonym for the
.I global
command variant \fBg!\fR, running the specified \fIcmds\fR on each
line which does not match \fIpat\fR.
.LC
\fBversion\fR abbr: \fBve\fR
.ZP
Prints the current version number of the editor
as well as the date the editor was last changed.
.LC
( \fB.\fR ) \fBvisual\fR \fItype\fR \fIcount\fR \fIflags\fR abbr: \fBvi\fR
.ZP
Enters visual mode at the specified line.
.I Type
is optional and may be `\-' , `\(ua' or `\fB.\fR'
as in the
.I z
command to specify the placement of the specified line on the screen.
By default, if
.I type
is omitted, the specified line is placed as the first on the screen.
A
.I count
specifies an initial window size; the default is the value of the option
.I window.
See the document
.I "An Introduction to Display Editing with Vi"
for more details.
To exit this mode, type Q.
.LC
\fBvisual\fP file
.br
\fBvisual\fP +\fIn\fP file
.ZP
From visual mode,
this command is the same as edit.
.LC
( 1 , $ ) \fBwrite\fR \fIfile\fR abbr: \fBw\fR
.ZP
Writes changes made back to \fIfile\fR, printing the number of lines and
characters written.
Normally \fIfile\fR is omitted and the text goes back where it came from.
If a \fIfile\fR is specified, then text will be written to that file.*
.FS
* The editor writes to a file only if it is
the current file and is
.I edited ,
if the file does not exist,
or if the file is actually a teletype,
.I /dev/tty,
.I /dev/null.
Otherwise, you must give the variant form \fBw!\fR to force the write.
.FE
If the file does not exist it is created.
The current file name is changed only if there is no current file
name; the current line is never changed.
.IP
If an error occurs while writing the current and
.I edited
file, the editor
considers that there has been ``No write since last change''
even if the buffer had not previously been modified.
.LC
( 1 , $ ) \fBwrite>>\fR \fIfile\fR abbr: \fBw>>\fR
.ZP
Writes the buffer contents at the end of
an existing file.
.IP
.LC
\fBw!\fR \fIname\fR
.ZP
Overrides the checking of the normal \fIwrite\fR command,
and will write to any file which the system permits.
.LC
( 1 , $ ) \fBw\fR \fB!\fR\fIcommand\fR
.ZP
Writes the specified lines into
.I command.
Note the difference between \fBw!\fR which overrides checks and
\fBw\ \ !\fR which writes to a command.
.LC
\fBwq\fR \fIname\fR
.ZP
Like a \fIwrite\fR and then a \fIquit\fR command.
.LC
\fBwq!\fR \fIname\fR
.ZP
The variant overrides checking on the sensibility of the
.I write
command, as \fBw!\fR does.
.LC
\fBxit\fP \fIname\fR
.ZP
If any changes have been made and not written, writes the buffer out.
Then, in any case, quits.
.LC
( \fB.\fR , \fB.\fR )\|\fByank\fR \fIbuffer\fR \fIcount\fR abbr: \fBya\fR
.ZP
Places the specified lines in the named
.I buffer,
for later retrieval via
.I put.
If no buffer name is specified, the lines go to a more volatile place;
see the \fIput\fR command description.
.LC
( \fB.+1\fR ) \fBz\fR \fIcount\fR
.ZP
Print the next \fIcount\fR lines, default \fIwindow\fR.
.LC
( \fB.\fR ) \fBz\fR \fItype\fR \fIcount\fR
.ZP
Prints a window of text with the specified line at the top.
If \fItype\fR is `\-' the line is placed at the bottom; a `\fB.\fR' causes
the line to be placed in the center.*
A count gives the number of lines to be displayed rather than
double the number specified by the \fIscroll\fR option.
On a \s-2CRT\s0 the screen is cleared before display begins unless a
count which is less than the screen size is given.
The current line is left at the last line printed.
.FS
* Forms `z=' and `z\(ua' also exist; `z=' places the current line in the
center, surrounds it with lines of `\-' characters and leaves the current
line at this line. The form `z\(ua' prints the window before `z\-'
would. The characters `+', `\(ua' and `\-' may be repeated for cumulative
effect.
On some v2 editors, no
.I type
may be given.
.FE
.LC
\fB!\fR \fIcommand\fR\fR
.ZP
The remainder of the line after the `!' character is sent to a shell
to be executed.
Within the text of
.I command
the characters
`%' and `#' are expanded as in filenames and the character
`!' is replaced with the text of the previous command.
Thus, in particular,
`!!' repeats the last such shell escape.
If any such expansion is performed, the expanded line will be echoed.
The current line is unchanged by this command.
.IP
If there has been ``[No\ write]'' of the buffer contents since the last
change to the editing buffer, then a diagnostic will be printed
before the command is executed as a warning.
A single `!' is printed when the command completes.
.LC
( \fIaddr\fR , \fIaddr\fR ) \fB!\fR \fIcommand\fR\fR
.ZP
Takes the specified address range and supplies it as
standard input to
.I command;
the resulting output then replaces the input lines.
.LC
( $ ) \fB=\fR
.ZP
Prints the line number of the
addressed line.
The current line is unchanged.
.KS
.LC
( \fB.\fR , \fB.\fR ) \fB>\fR \fIcount\fR \fIflags\fR
.br
( \fB.\fR , \fB.\fR ) \fB<\fR \fIcount\fR \fIflags\fR
.IP
Perform intelligent shifting on the specified lines;
\fB<\fR shifts left and \fB>\fR shift right.
The quantity of shift is determined by the
.I shiftwidth
option and the repetition of the specification character.
Only white space (blanks and tabs) is shifted;
no non-white characters are discarded in a left-shift.
The current line becomes the last line which changed due to the
shifting.
.KE
.LC
\fB^D\fR
.ZP
An end-of-file from a terminal input scrolls through the file.
The
.I scroll
option specifies the size of the scroll, normally a half screen of text.
.LC
( \fB.\fR+1 , \fB.\fR+1 )
.br
( \fB.\fR+1 , \fB.\fR+1 ) |
.ZP
An address alone causes the addressed lines to be printed.
A blank line prints the next line in the file.
.LC
( \fB.\fR , \fB.\fR ) \fB&\fR \fIoptions\fR \fIcount\fR \fIflags\fR
.ZP
Repeats the previous
.I substitute
command.
.LC
( \fB.\fR , \fB.\fR ) \fB\s+2~\s0\fR \fIoptions\fR \fIcount\fR \fIflags\fR
.ZP
Replaces the previous regular expression with the previous
replacement pattern from a substitution.
.NH 1
Regular expressions and substitute replacement patterns
.NH 2
Regular expressions
.PP
A regular expression specifies a set of strings of characters.
A member of this set of strings is said to be
.I matched
by the regular expression.
.I Ex
remembers two previous regular expressions:
the previous regular expression used in a
.I substitute
command
and the previous regular expression used elsewhere
(referred to as the previous \fIscanning\fR regular expression.)
The previous regular expression
can always be referred to by a null \fIre\fR, e.g. `//' or `??'.
.NH 2
Magic and nomagic
.PP
The regular expressions allowed by
.I ex
are constructed in one of two ways depending on the setting of
the
.I magic
option.
The
.I ex
and
.I vi
default setting of
.I magic
gives quick access to a powerful set of regular expression
metacharacters.
The disadvantage of
.I magic
is that the user must remember that these metacharacters are
.I magic
and precede them with the character `\e'
to use them as ``ordinary'' characters.
With
.I nomagic,
the default for
.I edit,
regular expressions are much simpler,
there being only two metacharacters.
The power of the other metacharacters is still available by preceding
the (now) ordinary character with a `\e'.
Note that `\e' is thus always a metacharacter.
.PP
The remainder of the discussion of regular expressions assumes
that
that the setting of this option is
.I magic.\(dg
.FS
\(dg To discern what is true with
.I nomagic
it suffices to remember that the only
special characters in this case will be `\(ua' at the beginning
of a regular expression,
`$' at the end of a regular expression,
and `\e'.
With
.I nomagic
the characters `\s+2~\s0' and `&' also lose their special meanings
related to the replacement pattern of a substitute.
.FE
.NH 2
Basic regular expression summary
.PP
The following basic constructs are used to construct
.I magic
mode regular expressions.
.IP \fIchar\fR 15
An ordinary character matches itself.
The characters `\(ua' at the beginning of a line,
`$' at the end of line,
`*' as any character other than the first,
`.', `\e', `[', and `\s+2~\s0' are not ordinary characters and
must be escaped (preceded) by `\e' to be treated as such.
.IP \fB\(ua\fR
At the beginning of a pattern
forces the match to succeed only at the beginning of a line.
.IP \fB$\fR
At the end of a regular expression forces the match to
succeed only at the end of the line.
.IP \&\fB.\fR
Matches any single character except
the new-line character.
.IP \fB\e<\fR
Forces the match
to occur only at the beginning of a ``variable'' or ``word'';
that is, either at the beginning of a line, or just before
a letter, digit, or underline and after a character not one of
these.
.IP \fB\e>\fR
Similar to `\e<', but matching the end of a ``variable''
or ``word'', i.e. either the end of the line or before character
which is neither a letter, nor a digit, nor the underline character.
.IP \fB[\fIstring\fR]\fR
Matches any (single) character in the class defined by
.I string.
Most characters in
.I string
define themselves.
A pair of characters separated by `\-' in
.I string
defines the set of characters collating between the specified lower and upper
bounds, thus `[a\-z]' as a regular expression matches
any (single) lower-case letter.
If the first character of
.I string
is an `\(ua' then the construct
matches those characters which it otherwise would not;
thus `[\(uaa\-z]' matches anything but a lower-case letter (and of course a
newline).
To place any of the characters
`\(ua', `[', or `\-' in
.I string
you must escape them with a preceding `\e'.
.NH 2
Combining regular expression primitives
.PP
The concatenation of two regular expressions matches the leftmost and
then longest string
which can be divided with the first piece matching the first regular
expression and the second piece matching the second.
Any of the (single character matching) regular expressions mentioned
above may be followed by the character `*' to form a regular expression
which matches any number of adjacent occurrences (including 0) of characters
matched by the regular expression it follows.
.PP
The character `\s+2~\s0' may be used in a regular expression,
and matches the text which defined the replacement part
of the last
.I substitute
command.
A regular expression may be enclosed between the sequences
`\e(' and `\e)' with side effects in the
.I substitute
replacement patterns.
.NH 2
Substitute replacement patterns
.PP
The basic metacharacters for the replacement pattern are
`&' and `~'; these are
given as `\e&' and `\e~' when
.I nomagic
is set.
Each instance of `&' is replaced by the characters
which the regular expression matched.
The metacharacter `~' stands, in the replacement pattern,
for the defining text of the previous replacement pattern.
.PP
Other metasequences possible in the replacement pattern
are always introduced by the escaping character `\e'.
The sequence `\e\fIn\fR' is replaced by the text matched
by the \fIn\fR-th regular subexpression enclosed between
`\e(' and `\e)'.\(dg
.FS
\(dg When nested, parenthesized subexpressions are present,
\fIn\fR is determined by counting occurrences of `\e(' starting from the left.
.FE
The sequences `\eu' and `\el' cause the immediately following character in
the replacement to be converted to upper- or lower-case respectively
if this character is a letter.
The sequences `\eU' and `\eL' turn such conversion on, either until
`\eE' or `\ee' is encountered, or until the end of the replacement pattern.
.de LC
.br
.sp .1i
.ne 4
.LP
.ta 3i
..
.NH 1
Option descriptions
.PP
.LC
\fBautoindent\fR, \fBai\fR default: noai
.ZP
Can be used to ease the preparation of structured program text.
At the beginning of each
.I append ,
.I change
or
.I insert
command
or when a new line is
.I opened
or created by an
.I append ,
.I change ,
.I insert ,
or
.I substitute
operation within
.I open
or
.I visual
mode,
.I ex
looks at the line being appended after,
the first line changed
or the line inserted before and calculates the amount of white space
at the start of the line.
It then aligns the cursor at the level of indentation so determined.
.IP
If the user then types lines of text in,
they will continue to be justified at the displayed indenting level.
If more white space is typed at the beginning of a line,
the following line will start aligned with the first non-white character
of the previous line.
To back the cursor up to the preceding tab stop one can hit
\fB^D\fR.
The tab stops going backwards are defined at multiples of the
.I shiftwidth
option.
You
.I cannot
backspace over the indent,
except by sending an end-of-file with a \fB^D\fR.
.IP
Specially processed in this mode is a line with no characters added
to it, which turns into a completely blank line (the white
space provided for the
.I autoindent
is discarded.)
Also specially processed in this mode are lines beginning with
an `\(ua' and immediately followed by a \fB^D\fR.
This causes the input to be repositioned at the beginning of the line,
but retaining the previous indent for the next line.
Similarly, a `0' followed by a \fB^D\fR
repositions at the beginning but without
retaining the previous indent.
.IP
.I Autoindent
doesn't happen in
.I global
commands or when the input is not a terminal.
.LC
\fBautoprint\fR, \fBap\fR default: ap
.ZP
Causes the current line to be printed after each
.I delete ,
.I copy ,
.I join ,
.I move ,
.I substitute ,
.I t ,
.I undo
or
shift command.
This has the same effect as supplying a trailing `p'
to each such command.
.I Autoprint
is suppressed in globals,
and only applies to the last of many commands on a line.
.LC
\fBautowrite\fR, \fBaw\fR default: noaw
.ZP
Causes the contents of the buffer to be written to the current file
if you have modified it and give a
.I next,
.I rewind,
.I stop,
.I tag,
or
.I !
command, or a \fB^\(ua\fR (switch files) or \fB^]\fR (tag goto) command
in
.I visual.
Note, that the
.I edit
and
.I ex
commands do
.B not
autowrite.
In each case, there is an equivalent way of switching when autowrite
is set to avoid the
.I autowrite
(\fIedit\fR
for
.I next ,
.I rewind!
for .I rewind ,
.I stop!
for
.I stop ,
.I tag!
for
.I tag ,
.I shell
for
.I ! ,
and
\fB:e\ #\fR and a \fB:ta!\fR command from within
.I visual).
.LC
\fBbeautify\fR, \fBbf\fR default: nobeautify
.ZP
Causes all control characters except tab, newline and form-feed
to be discarded from the input.
A complaint is registered the first time a
backspace character is discarded.
.I Beautify
does not apply to command input.
.LC
\fBdirectory\fR, \fBdir\fR default: dir=/tmp
.ZP
Specifies the directory in which
.I ex
places its buffer file.
If this directory in not
writable, then the editor will exit abruptly when it fails to be
able to create its buffer there.
.LC
\fBedcompatible\fR default: noedcompatible
.ZP
Causes the presence of absence of
.B g
and
.B c
suffixes on substitute commands to be remembered, and to be toggled
by repeating the suffices. The suffix
.B r
makes the substitution be as in the
.I ~
command, instead of like
.I &.
.LC
\fBerrorbells\fR, \fBeb\fR default: noeb
.ZP
Error messages are preceded by a bell.*
.FS
* Bell ringing in
.I open
and
.I visual
on errors is not suppressed by setting
.I noeb.
.FE
If possible the editor always places the error message in a standout mode of the
terminal (such as inverse video) instead of ringing the bell.
.LC
\fBhardtabs\fR, \fBht\fR default: ht=8
.ZP
Gives the boundaries on which terminal hardware tabs are set (or
on which the system expands tabs).
.LC
\fBignorecase\fR, \fBic\fR default: noic
.ZP
All upper case characters in the text are mapped to lower case in regular
expression matching.
In addition, all upper case characters in regular expressions are mapped
to lower case except in character class specifications.
.LC
\fBlisp\fR default: nolisp
.ZP
\fIAutoindent\fR indents appropriately for
.I lisp
code, and the \fB( ) { } [[\fR and \fB]]\fR commands in
.I open
and
.I visual
are modified to have meaning for \fIlisp\fR.
.LC
\fBlist\fR default: nolist
.ZP
All printed lines will be displayed (more) unambiguously,
showing tabs and end-of-lines as in the
.I list
command.
.LC
\fBmagic\fR default: magic for \fIex\fR and \fIvi\fR\(dg
.FS
\(dg \fINomagic\fR for \fIedit\fR.
.FE
.ZP
If
.I nomagic
is set, the number of regular expression metacharacters is greatly reduced,
with only `\(ua' and `$' having special effects.
In addition the metacharacters
`~'
and
`&'
of the replacement pattern are treated as normal characters.
All the normal metacharacters may be made
.I magic
when
.I nomagic
is set by preceding them with a `\e'.
.LC
\fBmesg\fR default: mesg
.ZP
Causes write permission to be turned off to the terminal
while you are in visual mode, if
.I nomesg
is set.
.LC
\fBmodeline\fR default: nomodeline
.ZP
If
.I modeline
is set, then the first 5 lines and the last five lines of the file
will be checked for ex command lines and the comands issued.
To be recognized as a command line, the line must have the string
.B ex:
or
.B vi:
preceeded by a tab or a space. This string may be anywhere in the
line and anything after the
.I :
is interpeted as editor commands. This option defaults to off because
of unexpected behavior when editting files such as
.I /etc/passwd.
.LC
\fBnumber, nu\fR default: nonumber
.ZP
Causes all output lines to be printed with their
line numbers.
In addition each input line will be prompted for by supplying the line number
it will have.
.LC
\fBopen\fR default: open
.ZP
If \fInoopen\fR, the commands
.I open
and
.I visual
are not permitted.
This is set for
.I edit
to prevent confusion resulting from accidental entry to
open or visual mode.
.LC
\fBoptimize, opt\fR default: optimize
.ZP
Throughput of text is expedited by setting the terminal
to not do automatic carriage returns
when printing more than one (logical) line of output,
greatly speeding output on terminals without addressable
cursors when text with leading white space is printed.
.LC
\fBparagraphs,\ para\fR default: para=IPLPPPQPP\0LIbp
.ZP
Specifies the paragraphs for the \fB{\fR and \fB}\fR operations in
.I open
and
.I visual.
The pairs of characters in the option's value are the names
of the macros which start paragraphs.
.LC
\fBprompt\fR default: prompt
.ZP
Command mode input is prompted for with a `:'.
.LC
\fBredraw\fR default: noredraw
.ZP
The editor simulates (using great amounts of output), an intelligent
terminal on a dumb terminal (e.g. during insertions in
.I visual
the characters to the right of the cursor position are refreshed
as each input character is typed.)
Useful only at very high speed.
.LC
\fBremap\fP default: remap
.ZP
If on, macros are repeatedly tried until they are unchanged.
For example, if
.B o
is mapped to
.B O ,
and
.B O
is mapped to
.B I ,
then if
.I remap
is set,
.B o
will map to
.B I ,
but if
.I noremap
is set, it will map to
.B O .
.LC
\fBreport\fR default: report=5\(dg
.FS
\(dg 2 for \fIedit\fR.
.FE
.ZP
Specifies a threshold for feedback from commands.
Any command which modifies more than the specified number of lines
will provide feedback as to the scope of its changes.
For commands such as
.I global ,
.I open ,
.I undo ,
and
.I visual
which have potentially more far reaching scope,
the net change in the number of lines in the buffer is
presented at the end of the command, subject to this same threshold.
Thus notification is suppressed during a
.I global
command on the individual commands performed.
.LC
\fBscroll\fR default: scroll=\(12 window
.ZP
Determines the number of logical lines scrolled when an end-of-file
is received from a terminal input in command mode,
and the number of lines printed by a command mode
.I z
command (double the value of
.I scroll ).
.LC
\fBsections\fR default: sections=SHNHH\0HU
.ZP
Specifies the section macros for the \fB[[\fR and \fB]]\fR operations
in
.I open
and
.I visual.
The pairs of characters in the options's value are the names
of the macros which start paragraphs.
.LC
\fBshell\fR, \fBsh\fR default: sh=/bin/sh
.ZP
Gives the path name of the shell forked for
the shell escape command `!', and by the
.I shell
command.
The default is taken from SHELL in the environment, if present.
.LC
\fBshiftwidth\fR, \fBsw\fR default: sw=8
.ZP
Gives the width a software tab stop,
used in reverse tabbing with \fB^D\fR when using
.I autoindent
to append text,
and by the shift commands.
.LC
\fBshowmatch, sm\fR default: nosm
.ZP
In
.I open
and
.I visual
mode, when a \fB)\fR or \fB}\fR is typed, move the cursor to the matching
\fB(\fR or \fB{\fR for one second if this matching character is on the
screen. Extremely useful with
.I lisp.
.LC
\fBslowopen, slow\fR terminal dependent
.ZP
Affects the display algorithm used in
.I visual
mode, holding off display updating during input of new text to improve
throughput when the terminal in use is both slow and unintelligent.
See
.I "An Introduction to Display Editing with Vi"
for more details.
.LC
\fBtabstop,\ ts\fR default: ts=8
.ZP
The editor expands tabs in the input file to be on
.I tabstop
boundaries for the purposes of display.
.LC
\fBtaglength,\ tl\fR default: tl=0
.ZP
Tags are not significant beyond this many characters.
A value of zero (the default) means that all characters are significant.
.LC
\fBtags\fR default: tags=tags /usr/lib/tags
.ZP
A path of files to be used as tag files for the
.I tag
command.
A requested tag is searched for in the specified files, sequentially.
By default, files called
.B tags
are searched for in the current directory and in /usr/lib
(a master file for the entire system).
.LC
\fBterm\fR from environment TERM
.ZP
The terminal type of the output device.
.LC
\fBterse\fR default: noterse
.ZP
Shorter error diagnostics are produced for the experienced user.
.LC
\fBwarn\fR default: warn
.ZP
Warn if there has been `[No write since last change]' before a `!'
command escape.
.LC
\fBwindow\fR default: window=speed dependent
.ZP
The number of lines in a text window in the
.I visual
command.
The default is 8 at slow speeds (600 baud or less),
16 at medium speed (1200 baud),
and the full screen (minus one line) at higher speeds.
.LC
\fBw300,\ w1200\, w9600\fR
.ZP
These are not true options but set
.B window
only if the speed is slow (300), medium (1200), or high (9600),
respectively.
They are suitable for an EXINIT
and make it easy to change the 8/16/full screen rule.
.LC
\fBwrapscan\fR, \fBws\fR default: ws
.ZP
Searches using the regular expressions in addressing
will wrap around past the end of the file.
.LC
\fBwrapmargin\fR, \fBwm\fR default: wm=0
.ZP
Defines a margin for automatic wrapover of text during input in
.I open
and
.I visual
modes. See
.I "An Introduction to Text Editing with Vi"
for details.
.LC
\fBwriteany\fR, \fBwa\fR default: nowa
.IP
Inhibit the checks normally made before
.I write
commands, allowing a write to any file which the system protection
mechanism will allow.
.NH 1
Acknowledgements
.PP
Chuck Haley contributed greatly to the early development of
.I ex.
Bruce Englar encouraged the redesign which led to
.I ex
version 1.
Bill Joy wrote versions 1 and 2.0 through 2.7,
and created the framework that users see in the present editor.
Mark Horton added macros and other features and made the
editor work on a large number of terminals and Unix systems.
Index: head/share/doc/usd/18.msdiffs/ms.diffs
===================================================================
--- head/share/doc/usd/18.msdiffs/ms.diffs (revision 282217)
+++ head/share/doc/usd/18.msdiffs/ms.diffs (revision 282218)
@@ -1,284 +1,285 @@
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)ms.diffs 8.1 (Berkeley) 6/8/93
.\"
.\" $FreeBSD$
.\"
.nr LL 6.5i
.nr FL 6.0i
.if t .nr PD .5v
.if t .ds m \u\(ul\dm
.if n .ds m -m
.AM
.OH 'A Revised Version of \*ms''USD:18-%'
.EH 'USD:18-%''A Revised Version of \*ms'
+.ND
.TL
A Revised Version of \*ms
.AU
Bill Tuthill
.AI
Computing Services
University of California
Berkeley, CA 94720
.PP
The \*ms macros have been slightly revised and re\%arranged for the
Berkeley Unix distribution.
Because of the rearrangement,
the new macros can be read by the computer
in about half the time required by the previous version of \*ms.
This means that output will begin to appear between ten seconds
and several minutes more quickly, depending on the system load.
On long files, however, the savings in total time are not substantial.
The old version of \*ms is still available as \*mos.
.PP
Several bugs in \*ms have been fixed, including
a bad problem with the .1C macro,
minor difficulties with boxed text,
a break induced by .EQ before initialization,
the failure to set tab stops in displays,
and several bothersome errors in the \fBrefer\fP macros.
Macros used only at Bell Laboratories have been removed.
There are a few extensions to previous \*ms macros,
and a number of new macros, but all the documented \*ms macros
still work exactly as they did before, and have the same names as before.
Output produced with \*ms should look like output produced with \*mos.
.PP
One important new feature is automatically numbered footnotes.
Footnote numbers are printed by means of a pre-defined string
(\e\(**\(**), which you invoke separately from .FS and .FE.
Each time it is used, this string increases the footnote number by one,
whether or not you use .FS and .FE in your text.
Footnote numbers will be superscripted on the phototypesetter
and on daisy-wheel terminals, but on low-resolution devices
(such as the lpr and a crt), they will be bracketed.
If you use \e\(**\(** to indicate numbered footnotes,
then the .FS macro will automatically include
the footnote number at the bottom of the page.
This footnote, for example, was produced as follows:\**
.DS
This footnote, for example, was produced as follows:\e\(**\(**
\&.FS
.sp -.2
...
\&.FE
.DE
.FS
If you never use the ``\e\(**\(**'' string,
no footnote numbers will appear anywhere in the text,
including down here.
The output footnotes will look exactly like
footnotes produced with \*mos.
.FE
If you are using \e\(**\(** to number footnotes,
but want a particular footnote to be marked with an asterisk or a dagger,
then give that mark as the first argument to .FS: \(dg
.DS
then give that mark as the first argument to .FS: \e(dg
\&.FS \e(dg
.sp -.2
...
\&.FE
.DE
.FS \(dg
In the footnote, the dagger will appear where the footnote
number would otherwise appear, as on the left.
.FE
Footnote numbering will be temporarily suspended,
because the \e\(**\(** string is not used.
Instead of a dagger, you could use an asterisk *
or double dagger \(dd, represented as \|\e(dd.
.PP
Another new feature is a macro for printing theses
according to Berkeley standards.
This macro is called .TM, which stands for thesis mode.
(It is much like the .th macro in \*me.)
It will put page numbers in the upper right-hand corner;
number the first page; suppress the date;
and doublespace everything except quotes, displays, and keeps.
Use it at the top of each file making up your thesis.
Calling .TM defines the .CT macro for chapter titles,
which skips to a new page and moves the pagenumber to the center footer.
The .P1 (P one) macro can be used even without thesis mode
to print the header on page 1,
which is suppressed except in thesis mode.
If you want roman numeral page numbering,
use an ``.af\0PN\0i'' request.
.PP
There is a new macro especially for bibliography entries,
called .XP, which stands for exdented paragraph.
It will exdent the first line of the paragraph by \en(PI units,
usually 5n (the same as the indent for the first line of a .PP).
Most bibliographies are printed this way.
Here are some examples of exdented paragraphs:
.XP
Lumley, Lyle S., \fISex in Crustaceans: Shell Fish Habits,\fP\|
Harbinger Press, Tampa Bay and San Diego, October 1979.
243 pages.
The pioneering work in this field.
.XP
Leffadinger, Harry A., ``Mollusk Mating Season: 52 Weeks, or All Year?''
in \fIActa Biologica,\fP\| vol. 42, no. 11, November 1980.
A provocative thesis, but the conclusions are wrong.
.LP
Of course, you will have to take care of
italicizing the book title and journal,
and quoting the title of the journal article.
Indentation or exdentation can be changed
by setting the value of number register PI.
.PP
If you need to produce endnotes rather than footnotes,
put the references in a file of their own.
This is similar to what you would do if you were
typing the paper on a conventional typewriter.
Note that you can use automatic footnote numbering
without actually having .FS and .FE pairs in your text.
If you place footnotes in a separate file,
you can use .IP macros with \e\(**\(**\| as a hanging tag;
this will give you numbers at the left-hand margin.
With some styles of endnotes,
you would want to use .PP rather then .IP macros,
and specify \e\(**\(** before the reference begins.
.PP
There are four new macros to help produce a table of contents.
Table of contents entries must be enclosed in .XS and .XE pairs,
with optional .XA macros for additional entries;
arguments to .XS and .XA specify the page number,
to be printed at the right.
A final .PX macro prints out the table of contents.
Here is a sample of typical input and output text:
.DS
\&.XS ii
Introduction
\&.XA 1
Chapter 1: Review of the Literature
\&.XA 23
Chapter 2: Experimental Evidence
\&.XE
\&.PX
.sp .5
.lt 5.5i
.tl ''\fBTable of Contents\fP''
.ta 5i 5.5iR
.sp
Introduction ii\|
Chapter 1: Review of the Literature 1
Chapter 2: Experimental Evidence 23
.sp .5
.DE
The .XS and .XE pairs may also be used in the text,
after a section header for instance,
in which case page numbers are supplied automatically.
However, most documents that require a table of contents
are too long to produce in one run,
which is necessary if this method is to work.
It is recommended that you do a table of contents
after finishing your document.
To print out the table of contents, use the .PX macro;
if you forget it, nothing will happen.
.PP
As an aid in producing text that will format correctly
with both \fBnroff\fP and \fBtroff\fP,
there are some new string definitions that define quotation marks
and dashes for each of these two formatting programs.
The \e\(**\^\u_\d string will yield two hyphens in \fBnroff\fP,
but in \fBtroff\fP it will produce an em dash\*-
like this one.
The \e\(**Q and \e\(**U strings will produce
`` and '' in \fBtroff\fP, but " in \fBnroff\fP.
(In typesetting, the double quote is traditionally considered bad form.)
.PP
There are now a large number of optional
foreign accent marks defined by the \*ms macros.
All the accent marks available in \*mos are present,
and they all work just as they always did.
However, there are better definitions available
by placing .AM at the beginning of your document.
Unlike the \*mos accent marks,
the accent strings should come \fIafter\fP\| the letter being accented.
Here is a list of the diacritical marks,
with examples of what they look like.
.DS
.ta 2i 3i
name of accent input output
\l'3.5i'
acute accent e\e\(**\' e\*'
grave accent e\e\(**\` e\*`
circumflex o\e\(**\d^\u o\*^
cedilla c\e\(**, c\*,
tilde n\e\(**\d~\u n\*~
question \e\(**? \*?
exclamation \e\(**! \*!
umlaut u\e\(**: u\*:
digraph s \e\(**8 \*8
hac\*vek c\e\(**v c\*v
macron a\e\(**_ a\*_
underdot s\e\(**. s\*.
o-slash o\e\(**/ o\*/
angstrom a\e\(**o a\*o
yogh kni\e\(**3t kni\*3t
Thorn \e\(**(Th \*(Th
thorn \e\(**(th \*(th
Eth \e\(**(D- \*(D-
eth \e\(**(d- \*(d-
hooked o \e\(**q \*q
ae ligature \e\(**(ae \*(ae
AE ligature \e\(**(Ae \*(Ae
oe ligature \e\(**(oe \*(oe
OE ligature \e\(**(Oe \*(Oe
.DE
If you want to use these new diacritical marks,
don't forget the .AM at the top of your file.
Without it, some will not print at all,
and others will be placed on the wrong letter.
.PP
It is also possible to produce custom headers and footers
that are different on even and odd pages.
The .OH and .EH macros define odd and even headers,
while .OF and .EF define odd and even footers.
Arguments to these four macros are specified as with .tl.
This document was produced with:
.DS
\&.OH \'\ef\^IThe -mx Macros\'\'Page %\ef\^P\'
\&.EH \'\ef\^IPage %\'\'The -mx Macros\ef\^P\'
.DE
Note that it would be an error to have an apostrophe in the header text;
if you need one, you will have to use a different delimiter
around the left, center, and right portions of the title.
You can use any character as a delimiter, provided it doesn't appear
elsewhere in the argument to .OH, .EH, .OF, or EF.
.PP
The \*ms macros work in conjunction with
the \fBtbl\fR, \fBeqn\fR, and \fBrefer\fR preprocessors.
Macros to deal with these items are read in only as needed,
as are the thesis macros (.TM),
the special accent mark definitions (.AM),
table of contents macros (.XS and .XE),
and macros to format the optional cover page.
The code for the \*ms package lives in /usr/lib/tmac/tmac.s,
and sourced files reside in the directory /usr/ucb/lib/ms.
.sp
Index: head/share/doc/usd/22.trofftut/tt00
===================================================================
--- head/share/doc/usd/22.trofftut/tt00 (revision 282217)
+++ head/share/doc/usd/22.trofftut/tt00 (revision 282218)
@@ -1,122 +1,123 @@
.\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode!
.\" This module is believed to contain source code proprietary to AT&T.
.\" Use and redistribution is subject to the Berkeley Software License
.\" Agreement and your Software Agreement with AT&T (Western Electric).
.\"
.\" @(#)tt00 8.1 (Berkeley) 6/8/93
.\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" Redistributions of source code and documentation must retain the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer.
.\"
.\" Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\"
.\" This product includes software developed or owned by Caldera
.\" International, Inc. Neither the name of Caldera International, Inc.
.\" nor the names of other contributors may be used to endorse or promote
.\" products derived from this software without specific prior written
.\" permission.
.\"
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.EH 'USD:22-%''A TROFF Tutorial'
.OH 'A TROFF Tutorial''USD:22-%'
.\".RP
.\" .....TM 76-1273-7 39199 39199-11
+.ND
.TL
A TROFF Tutorial
.AU "MH 2C-518" 6021
Brian W. Kernighan
(updated for 4.3BSD by Mark Seiden)
.AI
.\" What's this? .MH
.\" And this? .OK
\"Typesetting
\"Text formatting
\"NROFF
.AB
.PP
.UL troff
is a text-formatting program for
typesetting on the
.UX
operating system.
This device is capable of producing high quality
text;
this paper is an example of
.UL troff
output.
.PP
The phototypesetter itself normally runs with four fonts,
containing roman, italic and bold letters
(as on this page),
a full greek alphabet, and a substantial number of
special characters and mathematical symbols.
Characters can be printed in a range of sizes,
and placed anywhere on the page.
.PP
.UL troff
allows the user full control over fonts,
sizes, and character positions,
as well as the usual features of a formatter _
right-margin justification, automatic hyphenation,
page titling and numbering, and so on.
It also provides macros, arithmetic variables and operations,
and conditional testing, for complicated formatting tasks.
.PP
This document is an introduction to the most basic use of
.UL troff .
It presents just enough information to enable the user
to do simple formatting
tasks like making viewgraphs,
and to make incremental changes to existing packages
of
.UL troff
commands.
In most respects, the
.UC UNIX
formatter
.UL nroff
and a more recent version
.ul
(device-independent
.UL troff)
are identical to
the version described here, so this document also serves as a tutorial for
them as well.
.PP
.vs 12p
\fB\s+1NOTE: This document refers to the historical \f(BItroff\fB program, and
not to \f(BIgroff\fB. This is a first cut at importing the tutorial from
4.4BSD, now that the code has been released. It should at some time be modified
to describe \f(BIgroff\fR.\s0
.AE
.nr LL 6.5i
.nr LT 6.5i
.\" Unknown macro .CS 13 1 14 0 0 5
.if t .2C
.nr PS 9
.nr VS 11
Index: head/share/doc/usd/contents/contents.ms
===================================================================
--- head/share/doc/usd/contents/contents.ms (revision 282217)
+++ head/share/doc/usd/contents/contents.ms (revision 282218)
@@ -1,308 +1,309 @@
.\" Copyright (c) 1986, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)00.contents 8.2 (Berkeley) 4/20/94
.\" $FreeBSD$
.\"
.de ND
.KE
.sp
.KS
..
.OH '''USD Contents'
.EH 'USD Contents'''
+.ND
.TL
UNIX User's Supplementary Documents (USD)
.if !r.U .nr .U 0
.if \n(.U \{\
.br
.>> Title.html
.\}
.sp
\s-2 4.4 Berkeley Software Distribution\s+2
.sp
\fRJune, 1993\fR
.PP
This volume contains documents which supplement the manual pages in
.I
The Unix User's Reference Manual
.R
for the 4.4BSD system as distributed by U.C. Berkeley.
.sp
.KS
.SH
Getting Started
.ND
.IP
.tl 'Unix for Beginners \- Second Edition''USD:1'
.QP
An introduction to the most basic uses of the system.
.ND
.IP
.tl 'Learn \- Computer\-Aided Instruction on UNIX (Second Edition)''USD:2'
.QP
Describes a computer-aided instruction program that walks new users through
the basics of files, the editor, and document prepararation software.
.ND
.SH
Basic Utilities
.ND
.IP
.tl 'An Introduction to the UNIX Shell''USD:3'
.QP
Steve Bourne's introduction to the capabilities of
.I sh,
a command interpreter especially popular for writing shell scripts.
.ND
.IP
.tl 'An Introduction to the C shell''USD:4'
.if \n(.U \{\
.br
.>> 04.csh/paper.html
.\}
.QP
This introduction to
.I csh,
(a command interpreter popular for interactive work) describes many
commonly used UNIX commands, assumes little prior knowledge of UNIX,
and has a glossary useful for beginners.
.ND
.IP
.tl 'DC \- An Interactive Desk Calculator''USD:5'
.QP
A super HP calculator, if you do not need floating point.
.ND
.IP
.tl 'BC \- An Arbitrary Precision Desk-Calculator Language''USD:6'
.QP
A front end for DC that provides infix notation, control flow, and
built\-in functions.
.ND
.SH
Communicating with the World
.ND
.IP
.tl 'Mail Reference Manual''USD:7'
.if \n(.U \{\
.br
.>> 07.mail/paper.html
.\}
.QP
Complete details on one of the programs for sending and reading your mail.
.ND
.IP
.tl 'The Rand MH Message Handling System''USD:8'
.QP
This system for managing your computer mail uses lots of small programs,
instead of one large one.
.ND
.SH
Text Editing
.ND
.IP
.tl 'A Tutorial Introduction to the Unix Text Editor''USD:9'
.QP
An easy way to get started with the line editor,
.I ed.
.ND
.IP
.tl 'Advanced Editing on Unix''USD:10'
.if \n(.U \{\
.br
.>> 10.exref/paper.html
.\}
.QP
The next step.
.ND
.IP
.tl 'An Introduction to Display Editing with Vi''USD:11'
.if \n(.U \{\
.br
.>> 11.vitut/paper.html
.\}
.QP
The document to learn to use the \fIvi\fR screen editor.
.ND
.IP
.tl 'Ex Reference Manual (Version 3.7)''USD:12'
.if \n(.U \{\
.br
.>> 12.vi/paper.html
.\}
.QP
The final reference for the \fIex\fR editor.
.ND
.IP
.tl 'Vi Reference Manual''USD:13'
.if \n(.U \{\
.br
.>> 13.viref/paper.html
.\}
.QP
The definitive reference for the \fInvi\fR editor.
.ND
.IP
.tl 'Jove Manual for UNIX Users''USD:14'
.QP
Jove is a small, self-documenting, customizable display editor, based on
EMACS. A plausible alternative to
.I vi.
.ND
.IP
.tl 'SED \- A Non-interactive Text Editor''USD:15'
.QP
Describes a one-pass variant of
.I ed
useful as a filter for processing large files.
.ND
.IP
.tl 'AWK \- A Pattern Scanning and Processing Language (Second Edition)''USD:16'
.QP
A program for data selection and transformation.
.ND
.SH
Document Preparation
.ND
.IP
.tl 'Typing Documents on UNIX: Using the \-ms Macros with Troff and Nroff''USD:17'
.QP
Describes and gives examples of the basic use of the typesetting tools and
``-ms'', a frequently used package of formatting requests that make it easier
to lay out most documents.
.ND
.IP
.tl 'A Revised Version of \-ms''USD:18'
.if \n(.U \{\
.br
.>> 18.msdiffs/paper.html
.\}
.QP
A brief description of the Berkeley revisions made to the \-ms formatting
macros for nroff and troff.
.ND
.IP
.tl 'Writing Papers with \fInroff\fR using \-me''USD:19'
.if \n(.U \{\
.br
.>> 19.memacros/paper.html
.\}
.QP
Another popular macro package for
.I nroff.
.ND
.IP
.tl '\-me Reference Manual''USD:20'
.if \n(.U \{\
.br
.>> 20.meref/paper.html
.\}
.QP
The final word on \-me.
.ND
.IP
.tl 'NROFF/TROFF User\'s Manual''USD:21'
.QP
Extremely detailed information about these document formatting programs.
.ND
.IP
.tl 'A TROFF Tutorial''USD:22'
.QP
An introduction to the most basic uses of
.I troff
for those who really want to know such things, or want to write their
own macros.
.ND
.IP
.tl 'A System for Typesetting Mathematics''USD:23'
.QP
Describes
.I eqn,
an easy-to-learn language for high-quality mathematical typesetting.
.ND
.IP
.tl 'Typesetting Mathematics \- User\'s Guide (Second Edition)''USD:24'
.QP
More details about how to use
.I eqn.
.ND
.IP
.tl 'Tbl \- A Program to Format Tables''USD:25'
.QP
A program for easily typesetting tabular material.
.ND
.IP
.tl 'Refer \- A Bibliography System''USD:26'
.QP
An introduction to one set of tools used to maintain bibliographic databases.
The major program,
.I refer,
is used to automatically retrieve and format the references
based on document citations.
.ND
.IP
.tl 'Some Applications of Inverted Indexes on the UNIX System''USD:27'
.QP
Mike Lesk's paper describes the
.I refer
programs in a somewhat larger context.
.ND
.IP
.tl 'BIB \- A Program for Formatting Bibliographies''USD:28'
.QP
This is an alternative to
.I refer
for expanding citations in documents.
.ND
.IP
.tl 'Writing Tools \- The STYLE and DICTION Programs''USD:29'
.QP
These are programs which can help you understand and improve your
writing style.
.ND
.SH
Amusements
.ND
.IP
.tl 'A Guide to the Dungeons of Doom''USD:30'
.if \n(.U \{\
.br
.>> 30.rogue/paper.html
.\}
.QP
An introduction to the popular game of \fIrogue\fP, a fantasy game
which is one of the biggest known users of VAX cycles.
.ND
.IP
.tl 'Star Trek''USD:31'
.if \n(.U \{\
.br
.>> 31.trek/paper.html
.\}
.QP
You are the Captain of the Starship Enterprise. Wipe out the
Klingons and save the Federation.
.KE