Added man page - it looks a little odd in places (the 'i' and 'o'

commands), but this is the way it looked in the texinfo docs so I
stayed faithful to RMS's original presentation.

2 files changed, 278 insertions, 1 deletions

diff --git a/gnu/usr.bin/dc/Makefile b/gnu/usr.bin/dc/Makefile
index 6f6a7074b777..937c7d9f2d65 100644
--- a/gnu/usr.bin/dc/Makefile
+++ b/gnu/usr.bin/dc/Makefile
@@ -1,6 +1,5 @@
 PROG=	dc
 SRCS=	dc.c decimal.c
-NOMAN=	noman
 CFLAGS+=-I${.CURDIR} -DHAVE_BCOPY=1 -DHAVE_BZERO=1
 DPADD=	${LIBM}
 LDADD=	-lm
diff --git a/gnu/usr.bin/dc/dc.1 b/gnu/usr.bin/dc/dc.1
new file mode 100644
index 000000000000..17d9356a8fa0
--- /dev/null
+++ b/gnu/usr.bin/dc/dc.1
@@ -0,0 +1,278 @@
+.TH DC 1 "03 Aug 1993" "GNU Project"
+.SH NAME
+dc, An Arbitrary Precision Calculator
+.SH SYNOPSIS
+.B dc
+.SH DESCRIPTION
+.PP
+DC is a reverse-polish desk calculator which supports unlimited
+precision arithmetic.  It also allows you to define and call macros.
+Normally DC reads from the standard input; if any command arguments
+are given to it, they are filenames, and DC reads and executes the
+contents of the files before reading from standard input.  All output
+is to standard output.
+
+A reverse-polish calculator stores numbers on a stack.  Entering a
+number pushes it on the stack.  Arithmetic operations pop arguments off
+the stack and push the results.
+
+To enter a number in DC, type the digits, with an optional decimal
+point.  Exponential notation is not supported.  To enter a negative
+number, begin the number with `_'.  `-' cannot be used for this, as it
+is a binary operator for subtraction instead.  To enter two numbers in
+succession, separate them with spaces or newlines.  These have no
+meaning as commands.
+.PD
+.SH "Printing Commands"
+.PP
+.B p
+Prints the value on the top of the stack,
+without altering the stack.  A newline is printed
+after the value.
+.PP
+.B P
+Prints the value on the top of the stack,
+popping it off, and does not print a newline after.
+.PP
+.B f
+Prints the entire contents of the stack
+and the contents of all of the registers,
+without altering anything.  This is a good command
+to use if you are lost or want to figure out
+what the effect of some command has been.
+.PD
+.SH "Arithmetic"
+.PP
+.B +
+Pops two values off the stack, adds them,
+and pushes the result.  The precision of the result
+is determined only by the values of the arguments,
+and is enough to be exact.
+.PP
+.B -
+Pops two values, subtracts the first one popped
+from the second one popped, and pushes the result.
+.PP
+.B *
+Pops two values, multiplies them, and pushes the result.
+The number of fraction digits in the result is controlled
+by the current precision flag (see below) and does not
+depend on the values being multiplied.
+.PP
+.B /
+Pops two values, divides the second one popped from
+the first one popped, and pushes the result.
+The number of fraction digits is specified by the precision flag.
+.PP
+.B %
+Pops two values, computes the remainder of the division
+that the \fB/\fR command would do, and pushes that.
+The division is done with as many fraction digits
+as the precision flag specifies, and the remainder
+is also computed with that many fraction digits.
+.PP
+.B ^
+Pops two values and exponentiates, using the first
+value popped as the exponent and the second popped as the base.
+The fraction part of the exponent is ignored.
+The precision flag specifies the number of fraction
+digits in the result.
+.PP
+.B v
+Pops one value, computes its square root, and pushes that.
+The precision flag specifies the number of fraction digits
+in the result.
+.PP
+Most arithmetic operations are affected by the "precision flag",
+which you can set with the
+.BR k
+command.  The default precision
+value is zero, which means that all arithmetic except for
+addition and subtraction produces integer results.
+.PP
+The remainder operation
+.BR %
+requires some explanation: applied to
+arguments `a' and `b' it produces `a - (b * (a / b))',
+where `a / b' is computed in the current precision.
+.PP
+.SH "Stack Control"
+.PP
+.B c
+Clears the stack, rendering it empty.
+.PP
+.B d
+Duplicates the value on the top of the stack,
+pushing another copy of it.  Thus,
+`4d*p' computes 4 squared and prints it.
+.SH "Registers"
+.PP
+DC provides 128 memory registers, each named by a single
+ASCII character.  You can store a number in a register
+and retrieve it later.
+.PP
+.B s\fIr\fR
+Pop the value off the top of the stack and store
+it into register \fIr\fR.
+.PP
+.B l\fIr\fR
+Copy the value in register \fIr\fR and push it onto the stack.  This
+does not alter the contents of \fIr\fR.
+.PP
+Each register also contains its own stack.  The current
+register value is the top of the register's stack.
+.PP
+.B S\fIr\fR
+Pop the value off the top of the (main) stack and
+push it onto the stack of register \fIr\fR.
+The previous value of the register becomes inaccessible.
+.PP
+.B L\fIr\fR
+Pop the value off the top of register \fIr\fR's stack
+and push it onto the main stack.  The previous value
+in register \fIr\fR's stack, if any, is now accessible
+via the 
+.BR Ir
+command.
+.PP
+The
+.BR f
+command prints a list of all registers that have contents
+stored in them, together with their contents.  Only the
+current contents of each register (the top of its stack)
+is printed.
+.PP
+.SH "Parameters"
+.PP
+DC has three parameters that control its operation: the precision, the
+input radix, and the output radix.  The precision specifies the number
+of fraction digits to keep in the result of most arithmetic operations.
+The input radix controls the interpretation of numbers typed in;
+allnumbers typed in use this radix.  The output radix is used
+for printing numbers.
+.PP
+The input and output radices are separate parameters; you can make them
+unequal, which can be useful or confusing.  Each radix must be between 2
+and 36 inclusive.  The precision must be zero or greater.  The precision
+is always measured in decimal digits, regardless of the current input or
+output radix.
+.PP
+.B i
+Pops the value off the top of the stack
+and uses it to set the input radix.
+.PP
+.B o
+.PP
+.B k
+Similarly set the output radix and the precision.
+.PP
+.B I
+Pushes the current input radix on the stack.
+.PP
+.B O
+.PP
+.B K
+Similarly push the current output radix and the current precision.
+.PP
+.SH "Strings"
+.PP
+DC can operate on strings as well as on numbers.  The only things you
+can do with strings are print them and execute them as macros (which
+means that the contents of the string are processed as DC commands).
+Both registers and the stack can hold strings, and DC always knows
+whether any given object is a string or a number.  Some commands such as
+arithmetic operations demand numbers as arguments and print errors if
+given strings.  Other commands can accept either a number or a string;
+for example, the
+.BR p
+command can accept either and prints the object
+according to its type.
+.PP
+.B [characters]
+Makes a string containing
+.BR characters
+and pushes it
+on the stack.  For example,
+.BR [foo]p
+prints the
+characters \fBfoo\fR (with no newline).
+.PP
+.B x
+Pops a value off the stack and executes it as a macro.
+Normally it should be a string; if it is a number,
+it is simply pushed back onto the stack.
+For example,
+.BR [1p]x
+executes the macro
+.BR 1p
+which pushes \fB1\fR on the stack and prints \fB1\fR
+on a separate line.
+.PP
+Macros are most often stored in registers;
+\fB[1p]sa\fR stores a macro to print \fB1\fR into register \fBa\fR,
+and \fBlax\fR invokes the macro.
+.PP
+.B >\fIr\fR
+Pops two values off the stack and compares them
+assuming they are numbers, executing the contents
+of register \fIr\fR as a macro if the original top-of-stack
+is greater.  Thus, \fB1 2>a\fR will invoke register \fBa\fR's contents
+and \fB2 1>a\fR will not.
+.PP
+.B <\fIr\fB
+Similar but invokes the macro if the original top-of-stack
+is less.
+.PP
+.B =\fIr\fR
+Similar but invokes the macro if the two numbers popped
+are equal.  This can also be validly used to compare two
+strings for equality.
+.PP
+.B ?
+Reads a line from the terminal and executes it.
+This command allows a macro to request input from the user.
+.PP
+.B q
+During the execution of a macro, this comand
+does not exit DC.  Instead, it exits from that
+macro and also from the macro which invoked it (if any).
+.PP
+.B Q
+Pops a value off the stack and uses it as a count
+of levels of macro execution to be exited.  Thus,
+\fB3Q\fR exits three levels.
+.SH "Status Inquiry"
+.PP
+.B Z
+Pops a value off the stack, calculates the number of
+digits it has (or number of characters, if it is a string)
+and pushes that number.
+.PP
+.B X
+Pops a value off the stack, calculates the number of
+fraction digits it has, and pushes that number.
+For a string, the value pushed is -1.
+.PP
+.B z
+Pushes the current stack depth; the number of
+objects on the stack before the execution of the \fBz\fR command.
+.PP
+.B I
+Pushes the current value of the input radix.
+.PP
+.B O
+Pushes the current value of the output radix.
+.PP
+.B K
+Pushes the current value of the precision.
+.SH "Notes"
+.PP
+The \fB:\fR and \fB;\fR commands of the Unix DC program are
+not supported, as the documentation does not say what they do.
+The \fB!\fR command is not supported, but will be supported
+as soon as a library for executing a line as a command exists.
+.SH BUGS
+.PP
+Email bug reports to
+.BR bug-gnu-utils@prep.ai.mit.edu .
+Be sure to include the word ``dc'' somewhere in the ``Subject:'' field.