GNU Info

(groff)I/O

---

Next: Postprocessor Access Prev: Suppressing output Up: gtroff Reference

---

Enter node , (file) or (file)node

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.