— 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. See 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. See 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 (see 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.

     
     .ce
     \*(td
     .sp 2
     .nf
     .rd
     .sp
     .rd
     .fi
     Body of letter.
     .bp
     .nx repeat.let

     
     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]' > /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.

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.