Debian Codegraph @

upstream/debian-unstable/man1/soelim.1

raw
1 '\" p
2 .TH \%soelim 1 "2026-04-22" "groff 1.24.1"
3 .SH Name
4 \%soelim \- recursively interpolate source requests in
5 .I roff
6 or other text files
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
14 .\"
15 .\" Permission is granted to make and distribute verbatim copies of this
16 .\" manual provided the copyright notice and this permission notice are
17 .\" preserved on all copies.
18 .\"
19 .\" Permission is granted to copy and distribute modified versions of
20 .\" this manual under the conditions for verbatim copying, provided that
21 .\" the entire resulting derived work is distributed under the terms of
22 .\" a permission notice identical to this one.
23 .\"
24 .\" Permission is granted to copy and distribute translations of this
25 .\" manual into another language, under the above conditions for
26 .\" modified versions, except that this permission notice may be
27 .\" included in translations approved by the Free Software Foundation
28 .\" instead of in the original English.
29 .
30 .
31 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
32 .do nr *groff_soelim_1_man_C \n[.cp]
33 .cp 0
34 .
35 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
36 .nr do-fallback 0
37 .if !\n(.f .nr do-fallback 1 \" mandoc
38 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
39 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
40 .if \n[do-fallback] \{\
41 . de MR
42 . ie \\n(.$=1 \
43 . I \%\\$1
44 . el \
45 . IR \%\\$1 (\\$2)\\$3
46 . .
47 .\}
48 .rr do-fallback
49 .\" Man pages are seldom preprocessed with pic(1).
50 .mso pic.tmac
51 .
52 .
53 .\" ====================================================================
54 .\" Definitions
55 .\" ====================================================================
56 .
57 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
58 .el .ds tx TeX
59 .
60 .
61 .\" ====================================================================
62 .SH Synopsis
63 .\" ====================================================================
64 .
65 .SY \%soelim
66 .RB [ \-Crt ]
67 .RB [ \-I
68 .IR dir ]
69 .RI [ input-file\~ .\|.\|.]
70 .YS
71 .
72 .
73 .P
74 .SY \%soelim
75 .B \-\-help
76 .YS
77 .
78 .
79 .P
80 .SY \%soelim
81 .B \-v
82 .YS
83 .
84 .SY \%soelim
85 .B \%\-\-version
86 .YS
87 .
88 .
89 .\" ====================================================================
90 .SH Description
91 .\" ====================================================================
92 .
93 GNU
94 .I soelim \" GNU
95 is a preprocessor for the
96 .MR groff 7
97 document formatting system.
98 .
99 .I \%soelim
100 eliminates source requests in
101 .MR roff 7
102 and other text files;
103 that is,
104 it replaces lines of the form
105 .RB \[lq] .so
106 .IR included-file \[rq]
107 within each text
108 .I input-file
109 with the contents of
110 .I included-file
111 recursively,
112 flattening a tree of documents.
113 .
114 By default,
115 it writes
116 .I roff
117 .B lf
118 requests as well to record the name and line number of each
119 .I input-file
120 and
121 .IR included-file ,
122 so that any diagnostics produced by later processing can be accurately
123 traced to the original input.
124 .
125 Options allow this information to be suppressed
126 .RB ( \-r )
127 or supplied in \*[tx] comments instead
128 .RB ( \-t ).
129 .
130 In the absence of
131 .I input-file
132 arguments,
133 .I \%soelim
134 reads the standard input stream.
135 .
136 The program writes to the standard output stream.
137 .
138 .
139 .PP
140 .I \%soelim
141 reads the
142 .I included-file
143 argument as
144 GNU
145 .I troff \" GNU
146 does.
147 .
148 It ignores spaces immediately after \[lq]so\[rq];
149 to embed a sequence of one or more leading spaces in the argument,
150 prefix the sequence with a neutral double quote
151 .RB ( \[dq] ).
152 .
153 Non-leading spaces are interpreted literally.
154 .
155 A backslash followed by a space
156 .RB (\[lq] \[rs]\~ \[rq])
157 also encodes a space,
158 for compatibility with earlier versions of
159 GNU
160 .IR soelim . \" GNU
161 .
162 If the included file name requires a backslash,
163 use
164 .B \[rs]\[rs]
165 or
166 .B \[rs]e
167 to embed it.
168 .
169 Any other escape sequence in
170 .IR included-file ,
171 including
172 .RB \[lq] \[rs][rs] \[rq],
173 prevents
174 .I \%soelim
175 from replacing the source request.
176 .
177 AT&T and descendant versions of
178 .I soelim
179 have no means of embedding spaces in file names;
180 they replace the first space encountered with a newline
181 and stop interpreting the request.
182 .
183 .
184 .PP
185 The dot must be at the beginning of a line and must be followed by
186 .RB \[lq] so \[rq]
187 without intervening spaces or tabs for
188 .I \%soelim
189 to handle it.
190 .
191 This convention allows source requests to be \[lq]protected\[rq] from
192 processing by
193 .IR \%soelim ,
194 for instance as part of macro definitions or
195 .RB \[lq] if \^\[rq]
196 requests.
197 .
198 .
199 .PP
200 There must also be at least one space between
201 .RB \[lq] so \[rq]
202 and its
203 .I included-file
204 argument.
205 .
206 The
207 .B \-C
208 option overrides this requirement.
209 .
210 .
211 .PP
212 The foregoing is the limit of
213 .IR \%soelim 's
214 understanding of the
215 .I roff
216 language;
217 it does not,
218 for example,
219 replace the input line
220 .
221 .RS
222 .EX
223 \&.if 1 .so otherfile
224 .EE
225 .RE
226 .
227 with the contents of
228 .IR otherfile .
229 .
230 With its
231 .B \-r
232 option,
233 therefore,
234 .I \%soelim
235 can be used to process text files in general.
236 .
237 .
238 .PP
239 .I soelim \" generic
240 was designed to handle situations where the target of a
241 .I roff \" generic
242 source request requires a preprocessor such as
243 .MR \%eqn 1 ,
244 .MR \%pic 1 ,
245 .MR \%refer 1 ,
246 or
247 .MR \%tbl 1 .
248 .
249 The usual processing sequence of
250 .MR groff 1
251 is as follows.
252 .
253 .\" Does this groff installation use a command prefix? In installed
254 .\" pages, this comparison will not look like it needs to be dynamically
255 .\" decided.
256 .\"
257 .\" This is done so that the box sizes (in the pic(1) diagram) and arrow
258 .\" alignments (in the text alternative) can remain fixed.
259 .if !'\%'\%' \{\
260 In the diagrams below,
261 the traditional names for
262 .I soelim
263 and
264 .I troff
265 are used;
266 on this system,
267 the GNU versions are installed as
268 .I \%soelim
269 and
270 .IR \%troff .
271 .\}
272 .
273 .
274 .PP
275 .ie t \{\
276 .PS
277 .ps 10
278 .vs 12
279 box invisible width 0.5 height 0.4 "input" "file";
280 move to last box .bottom;
281 down;
282 arrow 0.3;
283 box invisible width 0.8 height 0.2 "preprocessor";
284 move to last box .right
285 right;
286 arrow 0.3;
287 A: box invisible width 0.35 height 0.2 "troff";
288 move to last box .top;
289 up;
290 move 0.3;
291 box invisible width 0.6 height 0.4 "sourced" "file";
292 line <- up 0.3 from A.top;
293 move to A.right;
294 right;
295 arrow 0.3;
296 box invisible width 0.85 height 0.2 "postprocessor";
297 move to last box .bottom;
298 down;
299 arrow 0.3;
300 box invisible width 0.5 height 0.4 "output" "file"
301 .ps
302 .vs
303 .PE
304 .\}
305 .el \{\
306 .EX
307 input sourced
308 file file
309 \[bv] \[bv]
310 \[da] \[da]
311 preprocessor \[an]\[->] troff \[an]\[->] postprocessor
312 \[bv]
313 \[da]
314 output
315 file
316 .EE
317 .\}
318 .PP
319 That is,
320 files sourced with
321 .RB \[lq] so \[rq]
322 are normally read
323 .I only
324 by the formatter,
325 .MR \%troff 1 .
326 .
327 .I \%soelim
328 is
329 .I not
330 required for
331 .I \%troff
332 to source files.
333 .
334 .
335 .br
336 .ne 2v
337 .P
338 If a file to be sourced should also be preprocessed,
339 it must already be read
340 .I before
341 the input passes through the preprocessor.
342 .
343 .IR \%soelim ,
344 normally invoked via
345 .IR groff 's
346 .B \-s
347 option,
348 handles this.
349 .
350 .
351 .PP
352 .ie t \{\
353 .PS
354 .ps 10
355 .vs 12
356 box invisible width 0.5 height 0.4 "input" "file";
357 move to last box .bottom;
358 down;
359 arrow 0.3;
360 A: box invisible width 0.5 height 0.2 "soelim";
361 line <- 0.3;
362 box invisible width 0.5 height 0.4 "sourced" "file";
363 move to A.right;
364 right;
365 arrow 0.3;
366 box invisible width 0.8 height 0.2 "preprocessor";
367 arrow 0.3;
368 box invisible width 0.35 height 0.2 "troff";
369 arrow 0.3
370 box invisible width 0.85 height 0.2 "postprocessor";
371 move to last box .bottom;
372 down;
373 arrow 0.3;
374 box invisible width 0.5 height 0.4 "output" "file"
375 .ps
376 .vs
377 .PE
378 .\}
379 .el \{\
380 .EX
381 input
382 file
383 \[bv]
384 \[da]
385 soelim \[an]\[->] preprocessor \[an]\[->] troff \[an]\[->] \
386 postprocessor
387 \[ua] \[bv]
388 \[bv] \[da]
389 sourced output
390 file file
391 .EE
392 .\}
393 .
394 .
395 .\" ====================================================================
396 .SH Options
397 .\" ====================================================================
398 .
399 .B \-\-help
400 displays a usage message,
401 while
402 .B \-v
403 and
404 .B \%\-\-version
405 show version information;
406 all exit afterward.
407 .
408 .
409 .TP 8n \" "-I dir" + 2n
410 .B \-C
411 Recognize an input line starting with
412 .B .so
413 even if a character other than a space or newline follows.
414 .
415 .TP
416 .BI \-I\~ dir
417 Search the directory
418 .I dir
419 for
420 .I input-
421 and
422 .I included-files.
423 .
424 If specified more than once,
425 each
426 .I dir
427 is searched in the given order.
428 .
429 To search the current working directory before others,
430 add
431 .RB \[lq] "\-I .\&" \[rq]
432 at the desired place;
433 it is otherwise searched last.
434 .
435 .
436 .TP
437 .B \-r
438 Write files \[lq]raw\[rq];
439 do not add
440 .B lf
441 requests.
442 .
443 .
444 .TP
445 .B \-t
446 Emit \*[tx] comment lines starting with
447 .RB \[lq] % \[rq]
448 indicating the current file and line number,
449 rather than
450 .B lf
451 requests for the same purpose.
452 .
453 .
454 .PP
455 If both
456 .B \-r
457 and
458 .B \-t
459 are given,
460 the last one specified controls.
461 .
462 .
463 .\" ====================================================================
464 .SH "Exit status"
465 .\" ====================================================================
466 .
467 .I \%soelim
468 exits with
469 .RB status\~ 0
470 on successful operation,
471 .RB status\~ 2
472 if the program cannot interpret its command-line arguments,
473 and
474 .RB status\~ 1
475 if it encounters an error during operation.
476 .
477 .
478 .\" ====================================================================
479 .SH "See also"
480 .\" ====================================================================
481 .
482 .MR groff 1
483 .
484 .
485 .\" Clean up.
486 .rm tx
487 .
488 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
489 .cp \n[*groff_soelim_1_man_C]
490 .do rr *groff_soelim_1_man_C
491 .
492 .
493 .\" Local Variables:
494 .\" fill-column: 72
495 .\" mode: nroff
496 .\" End:
497 .\" vim: set filetype=groff textwidth=72: