Name

       soelim - recursively interpolate source requests in roff or other text files

Synopsis

       soelim [-Crt] [-I dir] [input-file ...]

       soelim --help

       soelim -v
       soelim --version

Description

       GNU soelim is a preprocessor for the groff(7) document formatting system.  soelim works as
       a filter to eliminate source requests in roff(7) input files; that is, it  replaces  lines
       of the form “.so included-file” within each text input-file with the contents of included-
       file, recursively.  By default, it writes lf requests as well to record the name and  line
       number  of  each  input-file  and included-file, so that any diagnostics produced by later
       processing can be accurately traced to the original input.  Options allow this information
       to  be suppressed (-r) or supplied in TeX comments instead (-t).  In the absence of input-
       file arguments, soelim reads the standard input stream.  Output is written to the standard
       output stream.

       If  the  name  of a macro-file contains a backslash, use \\ or \e to embed it.  To embed a
       space, write “\ ” (backslash followed by a space).  Any other escape  sequence  in  macro-
       file, including “\[rs]”, prevents soelim from replacing the source request.

       The  dot  must  be  at  the  beginning  of  a  line  and  must be followed by “so” without
       intervening spaces or tabs for  soelim  to  handle  it.   This  convention  allows  source
       requests  to  be  “protected”  from  processing  by  soelim, for instance as part of macro
       definitions or “if” requests.

       There must also be at least one space between “so” and its macro-file  argument.   The  -C
       option overrides this requirement.

       The  foregoing  is  the limit of soelim's understanding of the roff language; it does not,
       for example, replace the input line
              .if 1 .so otherfile
       with the contents of otherfile.  With its -r option, therefore,  soelim  can  be  used  to
       process text files in general, to flatten a tree of input documents.

       soelim  was  designed  to  handle  situations  where  the  target of a roff source request
       requires a preprocessor such as eqn(1), pic(1), refer(1), or tbl(1).  The usual processing
       sequence of groff(1) is as follows.

                 input        sourced
                 file          file
                   ⎪             ⎪
                   ↓             ↓
               preprocessor ⎯→ troff ⎯→ postprocessor
                                             ⎪
                                             ↓
                                          output
                                           file

       That  is,  files sourced with “so” are normally read only by the formatter, troff.  soelim
       is not required for troff to source files.

       If a file to be sourced should also be preprocessed, it must already be  read  before  the
       input  file  passes  through  the  preprocessor.   soelim, normally invoked via groff's -s
       option, handles this.

                 input
                 file
                   ⎪
                   ↓
                 soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
                   ↑                                     ⎪
                   ⎪                                     ↓
                sourced                               output
                 file                                  file

Options

       --help displays a usage message, while -v and --version show version information; all exit
       afterward.

       -C     Recognize an input line starting with .so even if a character other than a space or
              newline follows.

       -I dir Search the directory dir path for input- and included-files.  -I may  be  specified
              more  than  once;  each  dir is searched in the given order.  To search the current
              working directory before others, add “-I .” at the desired place; it  is  otherwise
              searched last.

       -r     Write files “raw”; do not add lf requests.

       -t     Emit  TeX  comment  lines  starting  with  “%” indicating the current file and line
              number, rather than lf requests for the same purpose.

       If both -r and -t are given, the last one specified controls.

See also

       groff(1)