Man page - soelim(1)

Packages contains this manual

Package: groff-base
apt-get install groff-base

Manuals in package:

Documentations in package:

groff-base

Available languages:

en pl ja ro de

Manual

soelim

Name
Synopsis
Description
Options
See also

Name

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

Synopsis

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

Description

GNU soelim is a preprocessor for the groff (7) document formatting system. soelim 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, 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 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 . 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

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 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.