groff: I/O
5.29 I/O
========
'gtroff' has several requests for including files:
-- Request: .so file
Read 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. 
gsoelim, for more
information.
Since 'gtroff' replaces the 'so' request with the contents of
'file', it makes a difference whether the data is terminated with a
newline or not: Assuming that file 'xxx' contains the word 'foo'
without a final newline, this
This is
.so xxx
bar
yields 'This is foobar'.
The search path for FILE can be controlled with the '-I' command
line option.
-- Request: .pso command
Read the standard output from the specified COMMAND and includes it
in place of the 'pso' request.
This request causes an error if used in safer mode (which is the
default). Use 'groff''s or 'troff''s '-U' option to activate
unsafe mode.
The comment regarding a final newline for the 'so' request is valid
for 'pso' also.
-- 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. If the file does not exist, a warning
of type 'file' is emitted. Debugging, for information
about warnings.
-- Request: .trf file
-- Request: .cf file
Transparently output the contents of FILE. Each line is output as
if 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 ('trf' only). For example, to
define a macro 'x' containing the contents of file 'f', use
.ev 1
.di x
.trf f
.di
.ev
The calls to 'ev' prevent that the current partial input line
becomes part of the diversion.
Both 'trf' and 'cf', when used in a diversion, embeds an object in
the diversion which, when reread, causes the contents of FILE to be
transparently copied through to the output. In UNIX 'troff', the
contents of FILE 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.
While 'cf' copies the contents of FILE completely unprocessed,
'trf' disallows characters such as NUL that are not valid 'gtroff'
input characters (Identifiers).
For 'cf', within a diversion, 'completely unprocessed' means that
each line of a file to be inserted is handled as if it were
preceded by '\!\\!'.
Both requests cause a line break.
-- Request: .nx [file]
Force 'gtroff' to continue processing of the file specified as an
argument. If no argument is given, immediately jump to the end of
file.
-- Request: .rd [prompt [arg1 arg2 ...]]
Read from standard input, and include what is read as though it
were part of the input file. Text is read until a blank line is
encountered.
If standard input is a TTY input device (keyboard), write PROMPT to
standard error, followed by a colon (or send BEL for a beep if no
argument is given).
Arguments after PROMPT are available for the input. For example,
the line
.rd data foo bar
with the input 'This is \$2.' prints
This is bar.
Using the 'nx' and 'rd' requests, it is easy to set up form letters.
The form letter template is constructed like this, putting the following
lines into a file called 'repeat.let':
.ce
\*(td
.sp 2
.nf
.rd
.sp
.rd
.fi
Body of letter.
.bp
.nx repeat.let
When this is run, a file containing the following lines 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' request, 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
Pipe the output of 'gtroff' to the shell command(s) specified by
PIPE. This request must occur before 'gtroff' has a chance to
print anything.
'pi' causes an error if used in safer mode (which is the default).
Use 'groff''s or 'troff''s '-U' option to activate unsafe mode.
Multiple calls to 'pi' are allowed, acting as a chain. For
example,
.pi foo
.pi bar
...
is the same as '.pi foo | bar'.
Note that the intermediate output format of 'gtroff' is piped to
the specified commands. Consequently, calling 'groff' without the
'-Z' option normally causes a fatal error.
-- Request: .sy cmds
-- Register: \n[systat]
Execute the shell command(s) specified by CMDS. The output is not
saved anyplace, so it is up to the user to do so.
This request causes an error if used in safer mode (which is the
default). Use 'groff''s or 'troff''s '-U' option to activate
unsafe mode.
For example, the following code fragment 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]' > timefile\n[$$]
.so timefile\n[$$]
.sy rm timefile\n[$$]
\nH:\nM:\nS
Note that this works by having the 'perl' script (run by 'sy')
print out the 'nr' requests that set the number registers 'H', 'M',
and 'S', and then reads those commands in with the 'so' request.
For most practical purposes, the number registers 'seconds',
'minutes', and 'hours', which are initialized at start-up of
'gtroff', should be sufficient. Use the 'af' request to get a
formatted output:
.af hours 00
.af minutes 00
.af seconds 00
\n[hours]:\n[minutes]:\n[seconds]
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
Open the specified FILE for writing and associates the specified
STREAM with it.
The 'opena' request is like 'open', but if the file exists, append
to it instead of truncating it.
Both 'open' and 'opena' cause an error if used in safer mode (which
is the default). Use 'groff''s or 'troff''s '-U' option to
activate unsafe mode.
-- Request: .write stream data
-- Request: .writec stream data
Write 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.
The 'writec' request is like 'write', but only 'write' appends a
newline to the data.
-- Request: .writem stream xx
Write the contents of the macro or string XX to the file associated
with the specified STREAM.
XX is read in copy mode, i.e., already formatted elements are
ignored. Consequently, diversions must be unformatted with the
'asciify' request before calling 'writem'. Usually, this means a
loss of information.
-- Request: .close stream
Close the specified STREAM; the stream is no longer an acceptable
argument to the 'write' request.
Here a simple macro to write an index entry.
.open idx test.idx
.
.de IX
. write idx \\n[%] \\$*
..
.
.IX test entry
.
.close idx
-- Escape: \Ve
-- Escape: \V(ev
-- Escape: \V[env]
Interpolate the contents of the specified environment variable ENV
(one-character name E, two-character name EV) as returned by the
function 'getenv'. '\V' is interpreted in copy-in mode.
Info Catalog
groff: Colors
groff: gtroff Reference
groff: Postprocessor Access