|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
Name | Synopsis | Description | Options | Exit status | See also | COLOPHON |
|
|
|
soelim(1) General Commands Manual soelim(1)
soelim - recursively interpolate source requests in roff or other
text files
soelim [-Crt] [-I dir] [input-file ...]
soelim --help
soelim -v
soelim --version
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
⎪ ⎪
↓ ↓
preprocessor ⎯→ troff ⎯→ postprocessor
⎪
↓
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
⎪
↓
soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
↑ ⎪
⎪ ↓
sourced output
file file
--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.
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.
groff(1)
This page is part of the groff (GNU troff) project. Information
about the project can be found at
⟨http://www.gnu.org/software/groff/⟩. If you have a bug report for
this manual page, see ⟨http://www.gnu.org/software/groff/⟩. This
page was obtained from the project's upstream Git repository
⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2025-08-11. (At
that time, the date of the most recent commit that was found in
the repository was 2025-08-09.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
groff 1.23.0.3821-a8b3f 2025-08-09 soelim(1)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|