Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/608b.lha/ARoff/Sources.LZH/Sources/aroffenglish.doc.src

Text File | 1992-01-06 | 16.1 KB | 524 lines

.ll 76
.lt 76
.pl 66
.nh
\" section number (register)
.nr PN 0 1
\"------------- section start
.de PR
.nf
.ne 5
.fs u1
\\n+(PN. \\$1
.fs n
.fi

..
\"------- request description
.de RQ

.ne 3
.ti -4
\\$1  \\$2
.br
Syntax\\ \\ \\ \\ \\ :\\ \\$1 \\$3
.br
Description:\\ \\
..
.de SP
.br
.ti -16
..
\" page header
.de HD
.ls 2
.tl "ARoff"User's Reference Manual"Page \\n(pn"
.ls 1
..
\"-------- start of important note
.de NI

.ne 4
.ce
CAUTION:

.in 8
.ll -8
..
\"---------- end of important note
.de FN

.in
.ll
..
.wh 1 HD
\"--------------------------- TEXT

.PR Foreword
.ti +8
This manual describes release 1.12 of the utility ARoff. This program is
freeware, and permission is granted to freely copy and distribute it
by all mediums, provided no charge or fee is ask for, and no modification
is done to this program. ARoff is copyright (c) 1991 by Denis GOUNELLE, any
commercial usage or selling of this program, without written authorization,
is ABSOLUTLY FORBIDDEN.
.ti +8
In spite of several tests, no warranty is made that there's no errors in
ARoff. YOU USE THIS PROGRAM AT YOUR OWN RISKS. In no event will I be liable
for any damage, direct or indirect, resulting of the use of ARoff.

.PR Introduction
.ti +8
ARoff is a complete and powerful program for text formatting, with
registers, macros, etc.: it takes as input a source file including both
text and formatting commands, to produce a formatted output file as
you required.
.ti +8
You can look upon ARoff as a portage of "nroff" utility you find usually
under UNIX system. However, both programs are fairly different, and there
is surely a lot of things ARoff doesn't know.

.ti +8
ARoff is invoked via the following CLI command:

.ce
aroff [-wstack] [-l] <filename>

where <filename> is the name of file to process. If you specify "-" for
<filename>, ARoff will use the standard input.
.NI
The ARoff current version doesn't work properly if you use it
as a pipe output (e.g. "cat toto | aroff -").
.FN
.br
.ti +8
The -w option allows you to increase the size of the internal stack used
by ARoff. Default size has 256 locations (each of 8 bytes), but sometimes
this isn't enough; in this case, you'll obtain the following message "Error
2 in file pile.c at line 58". For instance, in order to increase the stack
size to 300 locations, invoke ARoff by "aroff -w300 <filename>".
.ti +8
If specified, the -l option tells ARoff to load the file in memory before
processing it. On an Amiga, this can make the programme two or three times
faster, but of course you'll need to have more free memory.

.ti +8
If you invoke ARoff without arguments (or with bad arguments), you'll
obtain a message telling you about the program version and the right syntax
for the arguments.

.PR How\ does\ it\ work
.ti +8
Like "nroff", ARoff concatenates automatically the text lines in order to
obtain a fairly long line. This is called "filling mode", and means a text
is seen like a words suite that ARoff just copies until it reaches an output
line or until you cause a "line break" (either by a command or by an empty
line). The following commands will cause a line break:
.nf
.in 16

bp\tnew page
br\tnew line
ce\tcenters the following line(s)
fi\tenables the filling mode
nf\tdisables the filling mode
sp\tline skip
in\tindentation
ti\ttemporary indentation

.in
.fi
.ti +8
Once a line has been built, ARoff "adjusts" it according to the
mode you specified: centering, justification, left or right alignement.
As a result of this you'll have an output line.
.ti +8
The formatting commands (also called "requests") must be given on a separate
line beginning by a period, followed by the request name (exactly two
characters), followed by the optional command arguments. For using one of
the above commands without causing a line break, specify a "quote" instead
of a period character (e.g.: "'ti -3" in place of ".ti -3").

.PR List\ of\ main\ requests
.ti +8
In all that follows, N is a positive integer number and ±N is either a
positive integer number (for specifying a definite value), or the plus sign
followed by a positive integer number (for specifying an increment), or the
minus sign followed by a positive integer number (for specifying a
decrement).
.in 8
.RQ ab ABort message
displays the specified message, flushes the output buffer and ends.
.RQ ad ADjust [mode]
modifies the adjusting mode. If no argument is specified, ARoff
will re-use the previous value. Here are the values of mode:
.nf

\tl\tleft justification
\tr\tright justification
\tc\tcentering
\tb\talignement
.fi
.RQ bp Begin\ Page [N]
causes a page break. Next page number will be N, if an argument is
specified.
.RQ br BReak
causes a line break. Current line filling is stopped, and the line
is printed without adjusting.
.RQ ce CEnter [N]
centers the following line, or the following N lines if you specify an
argument.
.RQ ex EXit
flushes the output buffer and ends.
.RQ fi FIll
enables the filling mode.
.RQ fs Font\ Style style
changes font style. The argument is any combination of:
.nf

\tb0\tboldface off
\tb1\tboldface on
\ti0\titalics off
\ti1\titalic on
\tu0\tunderlined off
\tu1\tunderlined on
\tn\tnormal characters
.fi
.RQ in INdent [±N]
changes the indentation. If no argument is specified, ARoff will re-use
the previous value.
.RQ ll Line\ Length [±N]
changes the output lines length (included indentation). If no argument is
specified, ARoff will re-use the previous value.
.RQ ls Line\ Spacing [±N]
changes the output lines spacing. If no argument is specified, ARoff
will re-use the previous value.
.RQ lt Title\ Length [±N]
changes the title length (see "tl" request). If no argument is specified,
ARoff will re-use the previous value.
.RQ na No\ Adjusting
disables the output lines adjusting.
.RQ ne NEed [N]
causes a page break if you have less than N lines before the page ending
(1 line if no argument is specified) or before the next trap.
.RQ nf No\ Filling
disables the filling mode.
.RQ nm line\ NuMbering [±num\ int\ spc\ idt]
enables the line numbering. Numbering begins at number "num" and will occur
every "int" lines (by default, 1 line). You'll have "spc" spaces (by
default, 1 space) between the numbers and the text, and "idt" spaces (by
default, 0 spaces) between the margin and the numbers. Without arguments,
numbering is disabled. A non-numeric argument is regarded as a missing one.
A missing argument is not modified.
.RQ nn No\ line\ Numbering [N]
no numbering is made for the following N lines, or for the following line,
if no argument is specified.
.RQ pl Page\ Length [±N]
changes the number of lines per page. If no argument is specified, ARoff
will re-use the default value.
.RQ pn Page\ Number ±N
changes the next page number.
.RQ po Page\ Offset [±N]
changes the left margin on all the document (this is different from
indenting). If no argument is specified, ARoff will re-use the previous
value.
.RQ so SOurce filename
inserts the content of the file you specified.
.RQ sp SPace [N]
inserts N empty lines (by default, 1 line).
.RQ ta TAbulation N
sets tab marks at columns 1, N+1, 2N+1, etc..
.RQ tc Tab\ Character [c]
tells what character will be used to expand tabs. If no argument is
specified, ARoff will re-use the previous value.
.RQ ti Temporary\ Indent N
indents the following line by the specified value.
.RQ tl TitLe 'a'b'c'
prints a text into three parts: "a" will be left aligned, "b" will be
centered, and "c" right aligned. You can use any character for separating
these three parts; moreover, one or two parts may be empty.
.RQ tm Terminal\ Message message
displays the specified message.
.RQ tr TRanslate abcd...
tells you'll have a conversion on your output: 'a' will be changed
into 'b', 'c' into 'd', etc.. If you specify an odd number of characters,
the last one will be changed into a space.
.RQ ts Title\ Style str
speficies title style. "str" is any combination of:

.nf
\tb\tboldface
\ti\titalics
\tu\tunderlined
.fi
.in

.PR Line\ format
.ti +8
ARoff recognizes the following constructions:

.fi
.in 24
.SP
\\t\t\ttabulation
.SP
\\<space>\tfixed space
.SP
\\<newline>\tignored new-line
.SP
\\"\t\trest of this line is a comment
.SP
\\!\t\trest of this line must be read (but not interpreted) and written on
output without any adjusting; this command can be used only in the
beginning of an input line
.SP
\\n\t\tinserts the value of a register
.SP
\\*\t\tinserts the value of a string
.in

It is very strongly recommended not to have tabs in your text, but rather use
the "\\t" sequence.

.ti +8
Registers allow you to store integer numeric values. You can handle
registers with the following requests:
.in 8
.RQ nr New\ Register name\ val\ [inc]
creates a register "name" and give to it "val" as a starting value. If you
specify an argument "inc", this will be stored as the value of register
increment. Register name may be one or two characters long. "val" and "inc"
arguments must be positive integer numbers.
.RQ rr Remove\ Register name
deletes register "name".
.in

Registers can be used as follows:
.nf
.in 8

\\nx\tinserts the value of register x
\\n+x\tincrements then inserts the value of register x
\\n-x\tdecrements then inserts the value of register x
\\n(xx\tinserts the value of register xx
\\n+(xx\tincrements then inserts the value of register xx
\\n-(xx\tdecrements then inserts the value of register xx

.ti -8
ARoff presets the following registers:

dw\tweek day (from 1 to 7)
dy\tmonth day (from 1 to 31)
mo\tmonth (from 1 to 12)
yr\tyear (two digits)
hr\thour (from 0 to 23)
mn\tminutes (from 0 to 59)
sc\tsecondes (from 0 to 59)
pn\tcurrent page number (output)
il\tcurrent line number (output)
ol\tcurrent line number (input)

.fi
.in
Please take notice that registers giving date and time are initialized when
you start ARoff, and will not be updated.

.ti +8
Strings allow you to store strings having 255 characters at most. You can
handle strings with the following requests:
.in 8
.RQ ds Define\ String name\ string
creates a string "name" and affect to it "string" as a value. To keep
spaces at the beginning of string, just put a quotation mark (") before the
first space. String name may be one or two characters long. If string
"name" exists, ARoff only changes its value.
.RQ as Append\ String name\ string
adds a given string to the string "name". If this string doesn't exist,
it will be created. To keep spaces at the beginning of string, just put
a quotation mark (") before the first space.
.RQ rs Remove\ String name
kills string "name".
.in

Strings may be used as follows:

.in 8
\\*x\tinserts the value of string x
.br
\\*(xx\tinserts the value of string xx
.in

ARoff defines automatically "fn" string; and this one takes its value from
the current file name.

.PR Macros
.ti +8
Macros allow you to store and recall easily a suite of requests and/or a
large part of text. You can handle macros with the following requests:
.in 8
.RQ de DEfine\ macro name
begins the definition of a macro "name". If this one already exists, its
content will be deleted. The following lines will be stored as a definition
until a line begins by two periods ("..").
.RQ am Append\ to\ Macro name
adds the following lines (until a line begins by "..") to a definition of
macro "name". If this macro doesn't exist, it will be created.
.RQ rm Remove\ Macro name
kills the given macro.
.RQ pm Print\ Macro [name]
displays the definition of the given macro. If no argument is specified,
ARoff displays the definition of all the macros.

.in
You call a macro exactly in the same way as a request: a period in the
beginning of line, followed by the macro name. At most, you can pass nine
arguments to a macro. These ones can be accessed to into the macro definition
by \\$1, \\$2, ..., \\$9. The count of arguments may be known by looking at the
".$" register. Space is the arguments separator. If you have to pass an
argument with a space, add a "\\" before the space character. If you have to
pass an argument with a fixed space, add three "\\" before the space character.
.NI
When ARoff is reading a macro definition, text is interpreted in the
same way as usual. So, remember using double "\\" before calling up registers,
strings or arguments if you want to defer their interpretation until the macro
is performed.
.FN
Unlike "nroff", it is forbidden to include a ".de" or ".am" request in your
macro definition. It is possible to call a macro within another one.

.PR Traps
.ti +8
Traps allow you to perform a macro at a given vertical position in a page.
By this mechanism, you can add a header or a footer. You can handle traps
with the following requests:
.in 8
.RQ wh WHen line\ name
sets a trap at a given line. The performed macro will be the macro "name".
If there was already a trap at this position, ARoff only changes the
name of the macro to perform. If "line" is a negative number, it is a
position relative to the end of the page. If "line" is 0, trap will be
performed at the end of the page.
.RQ rt Remove\ Trap line
remove the trap set at a given line.
.NI
In this version of ARoff, the end of page trap is never peformed
over the last page of a text.
.FN
.in 0
When ARoff is just going to write a line, it looks if a trap is set at this
line. In this case, ARoff calls the specified macro before it tries again
to write the line. This allows to activate a stream of traps set on
consecutive lines.

.PR Conditions
.ti +8
ARoff allows macro or request execution, as well as insertion of part of the
text, to depend of a condition. You handle conditions with the following
requests :
.in 8
.RQ if If cond\ anything
ignore 'anything' (i.e. the rest of the line) if the specified condition
is not verified.
.RQ el Else anything
ignore 'anything' (i.e. the rest of the line) if the last condition tested
was verified. The "el" request must IMMEDIATLY follow the "if" request.
.in

The condition in a "if" request may be one of:

.nf
\to\tpage number is odd
\te\tpage number is even
\tn\tformater is "nroff" (always true)
\tt\tformater is "troff" (always false)
\t's1's2'\tstring 's1' and 's2' are the same
\tN<M\tinteger N is lower than integer M
\tN=M\tinteger N is equal to integer M
\tN>M\tinteger N is greater than integer M
.fi

A condition may be negated with the '!' character. Condition arguments may,
of course, be ARoff registers of strings. Here are a few examples:

.nf
.in 8
\!.if o .tl 'Odd page header''\n(pn'
\!.el .tl 'Even page header''\n(pn'

\!.if '\*(fn'macros' the "macros" file
\!.el another file

\!.\" Page break if input line number > 56
\!.if \n(il>56 .bp
.in
.fi

.PR Others
.ti +8
Registers and strings are inserted through a text as it is read. You can
use either a register or a string as an argument of request. The value of
an unknown register is 0; an unknown string is replaced by an empty one. An
unknown request leads ARoff to look for a macro. The call of an undefined
macro will be be ignored.
.ti +8
Unlike "nroff", registers, strings and macros are stored in separate
lists. This means you may give the same name to a register, a string and a
macro: ARoff will make no mistake about them. On the other hand, as the
requests list is read before the macro list, if a macro and a request have
the same name, only the request will be performed.

.nf
Here is the ARoff error codes list:

.in 16
0\tinternal error
1\tstack is empty
2\tstack is full
3\tsyntax error
4\ttable or buffer overflow
5\tcannot open the given file
6\tincorrect arguments
7\twrite error
8\tnot sufficient free memory
9\t"el" request without "if" request
10\tcannot seek in file
11\tread error
12\tfile to process is empty

.in
Here are the default values of ARoff parameters:

.in 16
alignement\t\tad\tb
indentation\t\tin\t0
line length\t\tll\t80
line spacing\t\tls\t1
title length\t\tlt\t80
page length\t\tpl\t66
page number\t\tpn\t1
left margin\t\tpo\t0
tabulation\t\tta\t8
tabulation character\ttc\tspace

.in
.fi
.ti +8
Let me know remarks and criticism about this program by writing at the
following address:

.ne 4
.ce 4
M. GOUNELLE Denis
Boite 71
6, rue des cailloux
92110 CLICHY - FRANCE

.ti +8
ARoff was developped almost totally under an UNIX system, then re-compiled
on an Amiga computer with the Aztec C compiler version 3.6a. Source files
are supplied (there are no many comments, sorry !), with their own makefiles
for UNIX and Aztec. You should be able to compile this program with any
decent C compiler. The parts peculiar to the Aztec C compiler were put
between "#ifdef".