GNU bc 1.05a

1 files changed, 439 insertions, 0 deletions

diff --git a/gnu/usr.bin/bc/doc/dc.info b/gnu/usr.bin/bc/doc/dc.info
new file mode 100644
index 00000000000..d795379aa68
--- /dev/null
+++ b/gnu/usr.bin/bc/doc/dc.info
@@ -0,0 +1,439 @@
+This is Info file dc.info, produced by Makeinfo version 1.68 from the
+input file dc.texi.
+
+   This file documents DC, an arbitrary precision calculator.
+
+   Published by the Free Software Foundation, 675 Massachusetts Avenue,
+Cambridge, MA 02139 USA
+
+   Copyright (C) 1984, 1994, 1997, 1998 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: dc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+
+* Menu:
+
+* Introduction::                Introduction
+* Invocation::                  Invocation
+* Printing Commands::           Printing Commands
+* Arithmetic::                  Arithmetic
+* Stack Control::               Stack Control
+* Registers::                   Registers
+* Parameters::                  Parameters
+* Strings::                     Strings
+* Status Inquiry::              Status Inquiry
+* Miscellaneous::               Other commands
+* Reporting bugs::              Reporting bugs
+
+
+File: dc.info,  Node: Introduction,  Next: Invocation,  Prev: Top,  Up: Top
+
+Introduction
+************
+
+   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 instead of reading from standard input.  All normal output
+is to standard output; all error messages are written to standard error.
+
+   To exit, use `q'.  `C-c' does not exit; it is used to abort macros
+that are looping, etc.  (Currently this is not true; `C-c' does exit.)
+
+   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.
+
+
+File: dc.info,  Node: Invocation,  Next: Printing Commands,  Prev: Introduction,  Up: Top
+
+Invocation
+**********
+
+   DC may be invoked with the following command-line options:
+`-e EXPR'
+
+`--expression=EXPR'
+     Evaluate EXPR as DC commands.
+
+`-f FILE'
+
+`--file=FILE'
+     Read and evaluate DC commands from FILE.
+
+`-h'
+
+`--help'
+     Print a usage message summarizing the command-line options, then
+     exit.
+
+`-V'
+
+`--version'
+     Print the version information for this program, then exit.
+
+   If any command-line parameters remain after processing the options,
+these parameters are interpreted as additional FILEs whose contents are
+read and evaluated.  A file name of `-' refers to the standard input
+stream.  If no `-e' option was specified, and no files were specified,
+then the standard input will be read for commands to evaluate.
+
+
+File: dc.info,  Node: Printing Commands,  Next: Arithmetic,  Prev: Invocation,  Up: Top
+
+Printing Commands
+*****************
+
+`p'
+     Prints the value on the top of the stack, without altering the
+     stack.  A newline is printed after the value.
+
+`n'
+     Prints the value on the top of the stack, popping it off, and does
+     not print a newline after.  (This command is a GNU extension.)
+
+`P'
+     Pops off the value on top of the stack.  If it it a string, it is
+     simply printed without a trailing newline.  Otherwise it is a
+     number, and the integer portion of its absolute value is printed
+     out as a "base (UCHAR_MAX+1)" byte stream.  Assuming that
+     (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit bytes),
+     the sequence `KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk' could
+     also accomplish this function, except for the side-effect of
+     clobbering the x register.  (Details of the behavior with a number
+     are a GNU extension.)
+
+`f'
+     Prints the entire contents of the stack 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.
+
+
+File: dc.info,  Node: Arithmetic,  Next: Stack Control,  Prev: Printing Commands,  Up: Top
+
+Arithmetic
+**********
+
+`+'
+     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.
+
+`-'
+     Pops two values, subtracts the first one popped from the second
+     one popped, and pushes the result.
+
+`*'
+     Pops two values, multiplies them, and pushes the result.  The
+     number of fraction digits in the result is the largest of the
+     precision value, the number of fraction digits in the multiplier,
+     or the number of fraction digits in the multiplicand; but in no
+     event exceeding the number of digits required for an exact result.
+
+`/'
+     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 value.
+
+`%'
+     Pops two values, computes the remainder of the division that the
+     `/' command would do, and pushes that.  The value computed is the
+     same as that computed by the sequence `Sd dld/ Ld*-' .
+
+`~'
+     Pops two values, divides the second one popped from the first one
+     popped.  The quotient is pushed first, and the remainder is pushed
+     next.  The number of fraction digits used in the division is
+     specified by the precision value.  (The sequence `SdSn lnld/
+     LnLd%' could also accomplish this function, with slightly
+     different error checking.)  (This command is a GNU extension.)
+
+`^'
+     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 value specifies the
+     number of fraction digits in the result.
+
+`|'
+     Pops three values and computes a modular exponentiation.  The
+     first value popped is used as the reduction modulus; this value
+     must be a non-zero number, and the result may not be accurate if
+     the modulus is not an integer.  The second popped is used as the
+     exponent; this value must be a non-negative number, and any
+     fractional part of this exponent will be ignored.  The third value
+     popped is the base which gets exponentiated, which should be an
+     integer.  For small integers this is like the sequence `Sm^Lm%',
+     but, unlike `^', this command will work with arbritrarily large
+     exponents.  (This command is a GNU extension.)
+
+`v'
+     Pops one value, computes its square root, and pushes that.  The
+     precision value specifies the number of fraction digits in the
+     result.
+
+   Most arithmetic operations are affected by the *precision value*,
+which you can set with the `k' command.  The default precision value is
+zero, which means that all arithmetic except for addition and
+subtraction produces integer results.
+
+
+File: dc.info,  Node: Stack Control,  Next: Registers,  Prev: Arithmetic,  Up: Top
+
+Stack Control
+*************
+
+`c'
+     Clears the stack, rendering it empty.
+
+`d'
+     Duplicates the value on the top of the stack, pushing another copy
+     of it.  Thus, `4d*p' computes 4 squared and prints it.
+
+`r'
+     Reverses the order of (swaps) the top two values on the stack.
+     (This command is a GNU extension.)
+
+
+File: dc.info,  Node: Registers,  Next: Parameters,  Prev: Stack Control,  Up: Top
+
+Registers
+*********
+
+   DC provides at least 256 memory registers, each named by a single
+character.  You can store a number in a register and retrieve it later.
+
+`sR'
+     Pop the value off the top of the stack and store it into register
+     R.
+
+`lR'
+     Copy the value in register R, and push it onto the stack.  This
+     does not alter the contents of R.
+
+     Each register also contains its own stack.  The current register
+     value is the top of the register's stack.
+
+`SR'
+     Pop the value off the top of the (main) stack and push it onto the
+     stack of register R.  The previous value of the register becomes
+     inaccessible.
+
+`LR'
+     Pop the value off the top of register R's stack and push it onto
+     the main stack.  The previous value in register R's stack, if any,
+     is now accessible via the `lR' command.
+
+
+File: dc.info,  Node: Parameters,  Next: Strings,  Prev: Registers,  Up: Top
+
+Parameters
+**********
+
+   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; *all* numbers typed in use this radix.  The output radix is
+used for printing numbers.
+
+   The input and output radices are separate parameters; you can make
+them unequal, which can be useful or confusing.  The input radix must
+be between 2 and 16 inclusive.  The output radix must be at least 2.
+The precision must be zero or greater.  The precision is always
+measured in decimal digits, regardless of the current input or output
+radix.
+
+`i'
+     Pops the value off the top of the stack and uses it to set the
+     input radix.
+
+`o'
+     Pops the value off the top of the stack and uses it to set the
+     output radix.
+
+`k'
+     Pops the value off the top of the stack and uses it to set the
+     precision.
+
+`I'
+     Pushes the current input radix on the stack.
+
+`O'
+     Pushes the current output radix on the stack.
+
+`K'
+     Pushes the current precision on the stack.
+
+
+File: dc.info,  Node: Strings,  Next: Status Inquiry,  Prev: Parameters,  Up: Top
+
+Strings
+*******
+
+   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 `p' command can accept either and
+prints the object according to its type.
+
+`[CHARACTERS]'
+     Makes a string containing CHARACTERS and pushes it on the stack.
+     For example, `[foo]P' prints the characters `foo' (with no
+     newline).
+
+`a'
+     The mnemonic for this is somewhat erroneous: asciify.  The
+     top-of-stack is popped.  If it was a number, then the low-order
+     byte of this number is converted into a string and pushed onto the
+     stack.  Otherwise the top-of-stack was a string, and the first
+     character of that string is pushed back.  (This command is a GNU
+     extension.)
+
+`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, `[1p]x' executes the macro `1p',
+     which pushes 1 on the stack and prints `1' on a separate line.
+
+     Macros are most often stored in registers; `[1p]sa' stores a macro
+     to print `1' into register `a', and `lax' invokes the macro.
+
+`>R'
+     Pops two values off the stack and compares them assuming they are
+     numbers, executing the contents of register R as a macro if the
+     original top-of-stack is greater.  Thus, `1 2>a' will invoke
+     register `a''s contents and `2 1>a' will not.
+
+`!>R'
+     Similar but invokes the macro if the original top-of-stack is not
+     greater (is less than or equal to) what was the second-to-top.
+
+`<R'
+     Similar but invokes the macro if the original top-of-stack is less.
+
+`!<R'
+     Similar but invokes the macro if the original top-of-stack is not
+     less (is greater than or equal to) what was the second-to-top.
+
+`=R'
+     Similar but invokes the macro if the two numbers popped are equal.
+
+`!=R'
+     Similar but invokes the macro if the two numbers popped are not
+     equal.
+
+`?'
+     Reads a line from the terminal and executes it.  This command
+     allows a macro to request input from the user.
+
+`q'
+     During the execution of a macro, this command exits from the macro
+     and also from the macro which invoked it.  If called from the top
+     level, or from a macro which was called directly from the top
+     level, the `q' command will cause DC to exit.
+
+`Q'
+     Pops a value off the stack and uses it as a count of levels of
+     macro execution to be exited.  Thus, `3Q' exits three levels.
+
+
+File: dc.info,  Node: Status Inquiry,  Next: Miscellaneous,  Prev: Strings,  Up: Top
+
+Status Inquiry
+**************
+
+`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.
+
+`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 0.
+
+`z'
+     Pushes the current stack depth: the number of objects on the stack
+     before the execution of the `z' command.
+
+
+File: dc.info,  Node: Miscellaneous,  Next: Reporting bugs,  Prev: Status Inquiry,  Up: Top
+
+Miscellaneous
+*************
+
+`!'
+     Will run the rest of the line as a system command.  Note that
+     parsing of the !<, !=, and !> commands take precidence, so if you
+     want to run a command starting with <, =, or > you will need to
+     add a space after the !.
+
+`#'
+     Will interpret the rest of the line as a comment.  (This command
+     is a GNU extension.)
+
+`:R'
+     Will pop the top two values off of the stack.  The old
+     second-to-top value will be stored in the array R, indexed by the
+     old top-of-stack value.
+
+`;R'
+     Pops the top-of-stack and uses it as an index into the array R.
+     The selected value is then pushed onto the stack.
+
+   Note that each stacked instance of a register has its own array
+associated with it.  Thus `1 0:A 0SA 2 0:A LA 0;Ap' will print 1,
+because the 2 was stored in an instance of 0:A that was later popped.
+
+
+File: dc.info,  Node: Reporting bugs,  Prev: Miscellaneous,  Up: Top
+
+Reporting bugs
+**************
+
+   Email bug reports to `bug-gnu-utils@prep.ai.mit.edu'.  Be sure to
+include the word "dc" somewhere in the "Subject:" field.
+
+
+
+Tag Table:
+Node: Top983
+Node: Introduction1562
+Node: Invocation2779
+Node: Printing Commands3623
+Node: Arithmetic4801
+Node: Stack Control7714
+Node: Registers8127
+Node: Parameters9053
+Node: Strings10314
+Node: Status Inquiry13284
+Node: Miscellaneous13841
+Node: Reporting bugs14808
+
+End Tag Table