1soelim(1) General Commands Manual soelim(1)
2
6 soelim - recursively interpolate source requests in roff or other text
7 files
8
10 soelim [-Crt] [-I dir] [input-file ...]
11 soelim --help
13 soelim -v
15 soelim --version
16
18 GNU soelim is a preprocessor for the groff(7) document formatting sys‐
19 tem. soelim works as a filter to eliminate source requests in roff(7)
20 input files; that is, it replaces lines of the form “.so included-file”
21 within each text input-file with the contents of included-file, recur‐
22 sively. By default, it writes lf requests as well to record the name
23 and line number of each input-file and included-file, so that any diag‐
24 nostics produced by later processing can be accurately traced to the
25 original input. Options allow this information to be suppressed (-r)
26 or supplied in TeX comments instead (-t). In the absence of input-file
27 arguments, soelim reads the standard input stream. Output is written
28 to the standard output stream.
29 If the name of a macro-file contains a backslash, use \\ or \e to embed
31 it. To embed a space, write “\ ” (backslash followed by a space). Any
32 other escape sequence in macro-file, including “\[rs]”, prevents soelim
33 from replacing the source request.
34 The dot must be at the beginning of a line and must be followed by “so”
36 without intervening spaces or tabs for soelim to handle it. This con‐
37 vention allows source requests to be “protected” from processing by
38 soelim, for instance as part of macro definitions or “if” requests.
39 There must also be at least one space between “so” and its macro-file
41 argument. The -C option overrides this requirement.
42 The foregoing is the limit of soelim's understanding of the roff lan‐
44 guage; it does not, for example, replace the input line
45 .if 1 .so otherfile
46 with the contents of otherfile. With its -r option, therefore, soelim
47 can be used to process text files in general, to flatten a tree of in‐
48 put documents.
49 soelim was designed to handle situations where the target of a roff
51 source request requires a preprocessor such as eqn(1), pic(1),
52 refer(1), or tbl(1). The usual processing sequence of groff(1) is as
53 follows.
54 input sourced
56 file file
57 ⎪ ⎪
58 ↓ ↓
59 preprocessor ⎯→ troff ⎯→ postprocessor
60 ⎪
61 ↓
62 output
63 file
64 That is, files sourced with “so” are normally read only by the format‐
66 ter, troff. soelim is not required for troff to source files.
67 If a file to be sourced should also be preprocessed, it must already be
69 read before the input file passes through the preprocessor. soelim,
70 normally invoked via groff's -s option, handles this.
71 input
73 file
74 ⎪
75 ↓
76 soelim ⎯→ preprocessor ⎯→ troff ⎯→ postprocessor
77 ↑ ⎪
78 ⎪ ↓
79 sourced output
80 file file
81
83 --help displays a usage message, while -v and --version show version
84 information; all exit afterward.
85 -C Recognize an input line starting with .so even if a character
87 other than a space or newline follows.
88 -I dir Search the directory dir path for input- and included-files. -I
90 may be specified more than once; each dir is searched in the
91 given order. To search the current working directory before
92 others, add “-I .” at the desired place; it is otherwise
93 searched last.
94 -r Write files “raw”; do not add lf requests.
96 -t Emit TeX comment lines starting with “%” indicating the current
98 file and line number, rather than lf requests for the same pur‐
99 pose.
100 If both -r and -t are given, the last one specified controls.
102
104 groff(1)
105groff 1.23.0 2 November 2023 soelim(1)