gsoelim(1) User Commands gsoelim(1)

gsoelim - recursively interpolate source requests in roff or other text files

gsoelim [-Crt] [-I dir] [input-file ...]
gsoelim --help
gsoelim -v
gsoelim --version

GNU soelim is a preprocessor for the groff(7) document formatting system. gsoelim works as a filter to eliminate source requests in roff(7) input files; that is, it replaces lines of the form “.so included-file” within each text input-file with the contents of included-file, recursively. By default, it writes 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, gsoelim reads the standard input stream. Output is written to the standard output stream.

If the name of a macro-file contains a backslash, use \\ or \e to embed it. To embed a space, write “\ ” (backslash followed by a space). Any other escape sequence in macro-file, including “\[rs]”, prevents gsoelim from replacing the source request.

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

There must also be at least one space between “so” and its macro-file argument. The -C option overrides this requirement.

The foregoing is the limit of gsoelim'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, gsoelim 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 geqn(1), gpic(1), grefer(1), or gtbl(1). The usual processing sequence of groff(1) is as follows. In the diagrams below, the traditional names for soelim and troff are used; on this system, the GNU versions are installed as gsoelim and gtroff.



          input        sourced


          file          file


            ⎪             ⎪


            ↓             ↓


        preprocessor ⎯→ troff ⎯→ postprocessor


                                      ⎪


                                      ↓


                                   output


                                    file

That is, files sourced with “so” are normally read only by the formatter, gtroff. gsoelim is not required for gtroff 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. gsoelim, normally invoked via groff's -s option, handles this.



          input


          file


            ⎪


            ↓


          soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor


            ↑                                     ⎪


            ⎪                                     ↓


         sourced                               output


          file                                  file

--help displays a usage message, while -v and --version show version information; all exit afterward.

Recognize an input line starting with .so even if a character other than a space or newline follows.
Search the directory dir path for input- and included-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 “-I .” at the desired place; it is otherwise searched last.
Write files “raw”; do not add lf requests.
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.

groff(1)

2 July 2023 groff 1.23.0