|
Name | Synopsis | Description | Options | 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 document formatting system.
soelim works as a filter to eliminate source requests in 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, soelim
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 soelim 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 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 macro-
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
⎪ ⎪
↓ ↓
preprocessor ⎯→ troff ⎯→ postprocessor
⎪
↓
output
file
That is, files sourced with “so” 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
⎪
↓
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 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.
-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.
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 2022-12-17. (At
that time, the date of the most recent commit that was found in
the repository was 2022-12-14.) 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
man-pages@man7.org
groff 1.23.0.rc1.3569-94746-d1i4rtDyecember 2022 soelim(1)
|
HTML rendering created 2022-12-18 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|