gtroff has several requests for including files:
Read in the specified file and includes it in place of the
sorequest. This is quite useful for large documents, e.g. keeping each chapter in a separate file. See gsoelim, for more information.
sorequest 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, thisThis is .so xxx bar
yields ‘This is foobar’.
The search path for file can be controlled with the -I command line option.
The comment regarding a final newline for the
sorequest is valid for
Identical to the
sorequest except that
gtroffsearches 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,
msotries to include tmac.name and vice versa. If the file does not exist, a warning of type ‘file’ is emitted. See Debugging, for information about warnings.
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 (
trfonly). For example, to define a macro
xcontaining the contents of file f, use.ev 1 .di x .trf f .di .ev
The calls to
evprevent that the current partial input line becomes part of the diversion.
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.
cfcopies the contents of file completely unprocessed,
trfdisallows characters such as NUL that are not valid
gtroffinput characters (see Identifiers).
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.
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.’ printsThis is bar.
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
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
Multiple calls to
piare allowed, acting as a chain. For example,.pi foo .pi bar ...
is the same as ‘.pi foo | bar’.
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]' > /tmp/x\n[$$] .so /tmp/x\n[$$] .sy rm /tmp/x\n[$$] \nH:\nM:\nS
Note that this works by having the
perlscript (run by
sy) print out the
nrrequests which set the number registers
S, and then reads those commands in with the
For most practical purposes, the number registers
hourswhich are initialized at start-up of
gtroffshould be sufficient. Use the
afrequest to get a formatted output:.af hours 00 .af minutes 00 .af seconds 00 \n[hours]:\n[minutes]:\n[seconds]
openarequest is like
open, but if the file exists, append to it instead of truncating it.
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
dsrequest reads its second argument: A leading ‘"’ is stripped, and it is read in copy-in mode.
writecrequest is like
write, but only
writeappends a newline to the data.
Here a simple macro to write an index entry..open idx test.idx . .de IX . write idx \\n[%] \\$* .. . .IX test entry . .close idx