soelim(1) General Commands Manual soelim(1)
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
| |
v v
preprocessor --> troff --> postprocessor
|
v
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
|
v
soelim --> preprocessor --> troff --> postprocessor
^ |
| v
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)
groff 1.24.1 2026-05-15 soelim(1)
groff 1.24.1 - Generated Mon May 18 15:14:14 CDT 2026