www.LinuxHowtos.org

%soelim

Section: User Commands (1)
Updated: 2 July 2023
Index Return to Main Contents

Name

soelim - recursively interpolate source requests in roff or other text files
.nr d-fallback 1
.nr d-fallback 1

Synopsis

[-Crt] [-I dir] [inpu-file~...] --help -v --version

Description

GNU soelim is a preprocessor for the document formatting system. soelim works as a filter to eliminate source requests in input files; that is, it replaces lines of the form [lq].so include-file[rq] within each text inpu-file with the contents of include-file, recursively. By default, it writes lf requests as well to record the name and line number of each inpu-file and include-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 tx] comments instead (-t). In the absence of inpu-file arguments, soelim reads the standard input stream. Output is written to the standard output stream.

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

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

There must also be at least one space between [lq]so[rq] and its macr-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 or The usual processing sequence of is as follows.

          input        sourced
          file          file
            [bv]             [bv]
            [da]             [da]
        preprocessor [an][->] troff [an][->] postprocessor
                                      [bv]
                                      [da]
                                   output
                                    file

That is, files sourced with [lq]so[rq] 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
            [bv]
            [da]
          soelim [an][->] preprocessor [an][->] troff [an][->] postprocessor
            [ua]                                     [bv]
            [bv]                                     [da]
         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 inpu- and include-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 [lq]-I .[rq] at the desired place; it is otherwise searched last.
-r: Write files [lq]raw[rq]; do not add lf requests.
-t: Emit tx] comment lines starting with [lq]%[rq] 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.