@g@soelim(@MAN1EXT@)

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

Synopsis
@g@soelim [-Crt] [-I dir] [input-file ...]
@g@soelim --help
@g@soelim -v
@g@soelim --version

Description
GNU soelim is a preprocessor for the groff(@MAN7EXT@) document formatting system. @g@soelim works as a filter to eliminate source requests in roff(@MAN7EXT@) 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, @g@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 @g@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 @g@soelim to handle it. This convention allows source requests to be “protected” from processing by @g@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 @g@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, @g@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 @g@eqn(@MAN1EXT@), @g@pic(@MAN1EXT@), @g@refer(@MAN1EXT@), or @g@tbl(@MAN1EXT@). The usual processing sequence of groff(@MAN1EXT@) is as follows. In the diagrams below, the traditional names for soelim and troff are used; on this system, the GNU versions are installed as @g@soelim and @g@troff.

              input        sourced
              file          file
                |             |
                ↓             ↓
            preprocessor → troff → postprocessor
                                          |
                                          ↓
                                       output
                                        file

That is, files sourced with “so” are normally read only by the formatter, @g@troff. @g@soelim is not required for @g@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. @g@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(@MAN1EXT@)