soelim(1)

📦
version 1.24.2 · 13 versions
, in arch rolling

💖 soelim — the manual, but make it make sense 💖

okay bestie, buckle up, because we're talking about soelim, a General Commands Manual icon from the groff 1.24.2 era (dated 2026-10-04, for the record 📅). she recursively interpolates source requests in roff or other text files. yes. that's the whole vibe. let's go ✨

🌸 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, no cap. What she does is eliminate source requests in roff(7) and other text files — like, she takes every line shaped like .so included-file inside each text input-file and swaps it out for the actual contents of included-file, recursively, flattening a whole tree of documents into one gorgeous flat situation. 🌳➡️🌸

By default she also writes roff lf requests 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 back to the original input. bestie that's just good bookkeeping. 📝 Options let you suppress that info (-r) or supply it in TeX comments instead (-t). And if you hand her zero input-file arguments? She reads the standard input stream. She always writes to the standard output stream. periodt. 💁‍♀️

soelim reads the included-file argument the same way GNU troff does. She ignores spaces immediately after “so”; if you want to embed a sequence of one or more leading spaces in the argument, prefix that sequence with a neutral double quote ("). Non-leading spaces are interpreted literally, fr fr. A backslash followed by a space (\ ) also encodes a space, for compatibility with earlier versions of GNU soelim (she's sentimental like that 🥺). 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. and listen — 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. different era, different rules. 💀

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 lets source requests 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. (we love a loophole ✨)

And now the honest part: the foregoing is the limit of soelim's understanding of the roff language. She does not, for example, replace the input line

.if 1 .so otherfile

with the contents of otherfile. nope. not happening. 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

so like — files sourced with so are normally read only by the formatter, troff(1). soelim is not required for troff to source files. she's a helper, not a bodyguard. 💅

But 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 exactly this. iconic behavior honestly.

                 input
                 file
                   ⎪
                   ↓
                 soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
                   ↑                                     ⎪
                   ⎪                                     ↓
                sourced                               output
                 file                                  file

🎀 OPTIONS 🎀

  • --help — displays a usage message. meanwhile -v and --version show version information. all of them exit afterward, so it's a little farewell tour. 👋
  • -C — Recognize an input line starting with .so even if a character other than a space or newline follows. she's being flexible, let her cook 🔥
  • -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. order matters, bestie, she's not guessing 🧚
  • -r — Write files “raw”; do not add lf requests. minimal. clean. no receipts.
  • -t — Emit TeX comment lines starting with % indicating the current file and line number, rather than lf requests for the same purpose. aesthetic choice 💜
If both -r and -t are given, the last one specified controls. so say what you mean, and say it last. 😭

⭐ EXIT STATUS ⭐

  • soelim exits with status 0 on successful operation 🎉
  • status 2 if the program cannot interpret its command-line arguments 🙈
  • status 1 if it encounters an error during operation 💀

🌈 SEE ALSO 🌈

and that's the whole page, babe 💖 this was groff 1.24.2, dated 2026-10-04, and honestly? she ate. now go flatten some documents, you absolute main character 👑✨🌸

📦 where this page comes from