I/O
===
`gtroff' has several requests for including files:
- Request: .so file
Reads in the specified FILE and includes it in place of the `so'
request. This is quite useful for large documents, e.g. keeping
each chapter in a separate file. Note:gsoelim, for more
information.
- Request: .mso file
Identical to the `so' request except that `gtroff' searches for
the specified FILE in the same directories as macro files for the
the `-m' command line option. If the file name to be included has
the form `NAME.tmac' and it isn't found, `mso' tries to include
`tmac.NAME' and vice versa.
- Request: .cf file
- Request: .trf file
Transparently outputs the contents of FILE. Each line is output
as it were preceded by `\!'; however, the lines are not subject to
copy mode interpretation. If the file does not end with a
newline, then a newline is added. For example, to define a
macro `x' containing the contents of file `f', use
.di x
.trf f
.di
The request `.cf FILENAME', when used in a diversion, embeds an
object in the diversion which, when reread, causes the contents of
FILENAME to be transparently copied through to the output.
In UNIX `troff', the contents of FILENAME is immediately copied
through to the output regardless of whether there is a current
diversion; this behaviour is so anomalous that it must be
considered a bug. This request causes a line break.
With `trf', unlike `cf', the file cannot contain characters such
as NUL that are not valid `gtroff' input characters (Note:Identifiers). This request causes a line break.
- Request: .nx
Forces `gtroff' to continue processing of the file specified as an
argument.
- Request: .rd
The `rd' request reads from standard input, and includes what is
read as though it were part of the input file. Text is read until
a blank line is encountered.
Using the `nx' and `rd' requests, it is easy to set up form letters.
The form letter template is constructed like this:
.ce
\*(td
.sp 2
.nf
.rd
.sp
.rd
.fi
Body of letter.
.bp
.nx repeat.let
When this is run, the following file should be redirected in. Note that
requests included in this file are executed as though they were part of
the form letter. The last block of input is the `ex' requests which
tells groff to stop processing. If this was not there, groff would not
know when to stop.
Trent A. Fisher
708 NW 19th Av., #202
Portland, OR 97209
Dear Trent,
Len Adollar
4315 Sierra Vista
San Diego, CA 92103
Dear Mr. Adollar,
.ex
- Request: .pi pipe
Pipes the output of `gtroff' to the shell command(s) specified by
PIPE. This request must occur before `gtroff' has a chance to
print anything.
- Request: .sy cmds
- Register: \n[systat]
In "unsafe" mode, executes the shell command(s) specified by CMDS.
The output is not saved anyplace, so it is up to the user to do
so.
For example, the following example introduces the current time
into a document:
.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
(localtime(time))[2,1,0]' > /tmp/x\n[$$]
.so /tmp/x\n[$$]
.sy rm /tmp/x\n[$$]
\nH:\nM:\nS
Note that this works by having the `perl' script (run by `sy')
print out the `nr' requests which set the number registers `H',
`M' and `S', and then reads those commands in with the `so'
request.
The `systat' read-write number register contains the return value
of the `system()' function executed by the last `sy' request.
- Request: .open stream file
- Request: .opena stream file
Opens the specified FILE for writing and associates the specified
STREAM with it.
The `opena' is like `open', but if the file exists, append to it
instead of truncating it.
- Request: .write stream data
Writes to the file associated with the specified STREAM. The
stream must previously have been the subject of an open request.
The remainder of the line is interpreted as the `ds' request reads
its second argument: A leading `"' is stripped, and it is read in
copy-in mode.
- Request: .close stream
Closes the specified STREAM; the stream is no longer an acceptable
argument to the `write' request.
- Escape: \V'XXX'
Interpolates the contents of the specified environment variable,
as returned by the function `getenv'. Specify the argument to
`\V' as an identifier, i.e. `\VX', `\V(XX' or `\V[XXX]'. `\V' is
interpreted in copy-in mode.