soelim

soelim [-C] [-Idirectory] [-r] [-s] [-V] [--] [file ...]

-C
    Recognizes lines starting with .so (with a dot) as well as so (without a dot) as source directives.

-Idirectory
    Adds directory to the search path for files referenced by .so directives. Multiple -I options can be used.

-r
    Activates recursive expansion of nested .so files. By default, soelim only expands the top-level directives.

-s
    Causes soelim to exit with a non-zero status code if any file specified in a .so directive cannot be opened or found.

-V
    Prints the version number of soelim to standard error and then exits.

--
    Marks the end of options, allowing subsequent arguments that begin with a hyphen to be treated as filenames rather than options.

file ...
    One or more input files to be processed. If no files are specified, soelim reads from standard input.

The soelim command is a preprocessor for groff and other roff-like text formatting systems. Its primary function is to replace .so (source) directives within an input stream with the actual content of the files they refer to. This effectively "inlines" external files into the main document. It is particularly useful for preparing man pages or other structured documents that leverage modularity by breaking content into multiple files.

By expanding these directives before the document is passed to groff, soelim ensures that the final processing step receives a self-contained, single stream of data. This avoids potential issues where groff itself might not handle .so directives when outputting to standard output, or in environments where direct file system access during final rendering is restricted. It streamlines the document processing workflow, making modular document creation more robust.

When processing files with .so directives from untrusted sources, caution is advised. soelim can be coerced into reading arbitrary files on the system if malicious paths are embedded within the directives. Users should ensure input files are trustworthy before processing.

If no input file arguments are provided, soelim reads its content from standard input. The processed output, with all .so directives expanded, is always written to standard output.

When soelim encounters a .so directive, it searches for the specified file in a defined order:
1. The current working directory.
2. Directories specified by any -Idirectory options, in the order they appear.
3. Various standard groff macro directories, such as /usr/lib/groff/tmac, /usr/share/groff/site-tmac, and system-specific /usr/share/groff/<version>/tmac directories.

soelim is an integral part of the groff (GNU roff) text formatting system, which is the GNU Project's free software replacement for the proprietary troff typesetter. It was developed to provide a robust and standard way to handle .so file inclusion directives, particularly for the preparation of man pages. Its development ensured compatibility and functionality across various Unix-like systems, becoming a standard utility within the groff toolchain since its early versions.

groff(1), nroff(1), troff(1), man(1), manpath(5)