---
name: "soelim"
section: "1"
platform: "linux"
package: "groff"
version: "1.24.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/soelim"
---

# soelim(1)

recursively interpolate source requests in roff or other text files

## 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)](/groff/7.md) document formatting system. *soelim* eliminates source requests in [*roff*(7)](/roff/7.md) 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)](/eqn/1.md), [*pic*(1)](/pic/1.md), [*refer*(1)](/refer/1.md), or [*tbl*(1)](/tbl/1.md). The usual processing sequence of [*groff*(1)](/groff/1.md) 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)](/troff/1.md). *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)](/groff/1.md)