# soelim

## 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_ eliminates source requests in _roff_(7) and other
           text files; that is, it replaces lines of the form “**.so** _included-_
           _file_ ” within each text _input-file_ with the contents of _included-_
           _file_ recursively, flattening a tree of documents.  By default, it
           writes _roff_ **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.  The
           program writes to the standard output stream.
    
           _soelim_ reads the _included-file_ argument as GNU _troff_ does.  It
           ignores spaces immediately after “so”; to embed a sequence of one
           or more leading spaces in the argument, prefix the sequence with a
           neutral double quote (**"**).  Non-leading spaces are interpreted
           literally.  A backslash followed by a space (“**\** ”) also encodes a
           space, for compatibility with earlier versions of GNU _soelim_.  If
           the included file name requires a backslash, use **\\** or **\e** to embed
           it.  Any other escape sequence in _included-file_ , including
           “**\[rs]** ”, prevents _soelim_ from replacing the source request.  AT&T
           and descendant versions of _soelim_ have no means of embedding
           spaces in file names; they replace the first space encountered
           with a newline and stop interpreting the 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
           _included-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.
    
           _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_(1).  _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 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_ for _input-_ and _included-files._  If
                  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.
    


## Exit status



           _soelim_ exits with status **0** on successful operation, status **2** if
           the program cannot interpret its command-line arguments, and
           status **1** if it encounters an error during operation.
    


## See also



           _groff_(1)
    


* * *