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)

groff 1.23.0                                      31 March 2024                                        soelim(1)