From 9e5ebc8c71fd2769b07eb14201bf52e1eae5af2f Mon Sep 17 00:00:00 2001 From: "Jordan K. Hubbard" Date: Wed, 4 Aug 1993 17:51:47 +0000 Subject: [PATCH] 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. --- gnu/usr.bin/dc/Makefile | 1 - gnu/usr.bin/dc/dc.1 | 278 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 278 insertions(+), 1 deletion(-) create mode 100644 gnu/usr.bin/dc/dc.1 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.