%soelim
Section: User Commands (1)
Updated: 202-0-22
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
eliminates source requests in
and other text 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,
flattening a tree of documents.
By default,
it writes
roff
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.
The program writes to the standard output stream.
soelim
reads the
include-file
argument as
GNU
troff does.
It ignores spaces immediately after [lq]so[rq];
to embed a sequence of one or more leading spaces in the argument,
prefix the sequence with a neutral double quote
([dq]).
No-leading spaces are interpreted literally.
A backslash followed by a space
([lq][rs]~[rq])
also encodes a space,
for compatibility with earlier versions of
GNU
soelim.
If the included file name requires a backslash,
use
[rs][rs]
or
[rs]e
to embed it.
Any other escape sequence in
include-file,
including
[lq][rs][rs][rq],
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
[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
include-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
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,
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
[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
for
inpu-
and
include-files.
If 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.
Exit status
soelim
exits with
status~
0
on successful operation,
status~
2
if the program cannot interpret its comman-line arguments,
and
status~
1
if it encounters an error during operation.
See also
Index
- Name
-
- Synopsis
-
- Description
-
- Options
-
- Exit status
-
- See also
-
|
|
- Running on 
-
:
