%soelim
Section: User Commands (1)
Updated: 2 July 2023
Index
Return to Main Contents
Name
soelim - recursively interpolate source requests in
roff
or other text files
.nr d-fallback 1
.nr d-fallback 1
Synopsis
[
-Crt]
[
-I
dir]
[
inpu-file~...]
--help
-v
--version
Description
GNU
soelim is a preprocessor for the
document formatting system.
soelim
works as a filter to eliminate source requests in
input files;
that is,
it replaces lines of the form
[lq]
.so
include-file[rq]
within each text
inpu-file
with the contents of
include-file,
recursively.
By default,
it writes
lf
requests as well to record the name and line number of each
inpu-file
and
include-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 tx] comments instead
(
-t).
In the absence of
inpu-file
arguments,
soelim
reads the standard input stream.
Output is written to the standard output stream.
If the name of a
macr-file
contains a backslash,
use
[rs][rs]
or
[rs]e
to embed it.
To embed a space,
write
[lq][rs]~[rq]
(backslash followed by a space).
Any other escape sequence in
macr-file,
including
[lq][rs][rs][rq],
prevents
soelim
from replacing the source request.
The dot must be at the beginning of a line and must be followed by
[lq]so[rq]
without intervening spaces or tabs for
soelim
to handle it.
This convention allows source requests to be [lq]protected[rq] from
processing by
soelim,
for instance as part of macro definitions or
[lq]if[rq]
requests.
There must also be at least one space between
[lq]so[rq]
and its
macr-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,
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
or
The usual processing sequence of
is as follows.
input sourced
file file
[bv] [bv]
[da] [da]
preprocessor [an][->] troff [an][->] postprocessor
[bv]
[da]
output
file
That is,
files sourced with
[lq]so[rq]
are normally read
only
by the formatter,
troff.
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 file passes through the preprocessor.
soelim,
normally invoked via
groff's
-s
option,
handles this.
input
file
[bv]
[da]
soelim [an][->] preprocessor [an][->] troff [an][->] postprocessor
[ua] [bv]
[bv] [da]
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
path for
inpu-
and
include-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
[lq]-I .[rq]
at the desired place;
it is otherwise searched last.
- -r
-
Write files [lq]raw[rq];
do not add
lf
requests.
- -t
-
Emit tx] comment lines starting with
[lq]%[rq]
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.
See also
Index
- Name
-
- Synopsis
-
- Description
-
- Options
-
- See also
-
|
|
- Running on 
-
:
