| blob | cf6ca83b33c118d5f97e238ba9eb30e453cd88ae |
1 '\" p -- preprocess: pic(1)
2 .ig
3 @ L_P_SOELIM@.1
5 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
7 Copyright (C) 1989 - 2001, 2003, 2004, 2006, 2008
8 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 are preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be included in
22 translations approved by the Free Software Foundation instead of in
23 the original English.
24 ..
25 .
26 .mso pic.tmac
27 .
28 .do nr __compat \n[.C]
29 .cp 0
30 .
31 .
32 .TH @U_P_SOELIM@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
33 .
34 .
35 .SH NAME
36 .
37 @L_P_SOELIM@ \- interpret .so requests in @T_ROFF@ input
38 .
39 .
40 .SH SYNOPSIS
41 .
42 .SY @L_P_SOELIM@
43 .OP \-Crtv
44 .OP \-I dir
45 .RI [ files
46 .IR \|.\|.\|. ]
47 .YS
48 .
49 .PP
50 It is possible to have whitespace between the
51 .B \-I
52 command line option and its parameter.
53 .
54 .
55 .SH DESCRIPTION
56 .
57 .B @L_P_SOELIM@
58 reads
59 .I files
60 and replaces lines of the form
61 .IP
62 .BI .so\~ file
63 .LP
64 by the contents of
65 .IR file .
66 It is useful if files included with
67 .B .so
68 need to be preprocessed.
69 Normally,
70 .B @L_P_SOELIM@
71 should be invoked with the
72 .B \-s
73 option of
74 .BR @L_TROFF .
75 .
76 .PP
77 To embed `\[rs]' in the file name, write `\[rs]\[rs]' or `\[rs]e'.
78 To embed a space, write `\[rs]\ '.
79 Any other escape sequence in
80 .I file
81 makes
82 .B @L_P_SOELIM@
83 ignore the whole line.
84 .
85 .PP
86 Note that there must be no whitespace between the leading dot and the two
87 characters `s' and `o'.
88 Otherwise, only
89 .B @L_ROFF@
90 interprets the
91 .B .so
92 request (and
93 .B @L_P_SOELIM@
94 ignores it).
95 .
96 .
97 .SH OPTIONS
98 .
99 .TP
100 .B \-C
101 Recognize
102 .B .so
103 even when followed by a character other than space or newline.
104 .
105 .TP
106 .BI \-I dir
107 This option may be used to add a directory to the search path for files
108 (both those on the command line and those named in
109 .B .so
110 requests).
111 The search path is initialized with the current directory.
112 This option may be specified more than once; the directories are then
113 searched in the order specified (but before the current directory).
114 If you want to make the current directory be read before other directories,
115 add
116 .B \-I.\&
117 at the appropriate place.
118 .IP
119 No directory search is performed for files with an absolute file name.
120 .
121 .TP
122 .B \-r
123 Do not add
124 .B .lf
125 requests (for general use, with non-roff files).
126 .
127 .TP
128 .B \-t
129 Don't emit
130 .B .lf
131 requests but TeX comment lines (starting with `%') giving the current file
132 and line number.
133 .
134 .TP
135 .B \-v
136 Print the version number.
137 .
138 .
139 .SH USAGE
140 .
141 The normal processing sequence of @T_ROFF@ is this:
142 .
143 .PP
144 .ie t \{\
145 .PS
146 .ps 10
147 .vs 12
148 box invisible width 0.5 height 0.4 "input" "file";
149 move to last box .bottom;
150 down;
151 arrow 0.3;
152 box invisible width 0.8 height 0.2 "preprocessor";
153 move to last box .right
154 right;
155 arrow 0.3;
156 A: box invisible width 0.35 height 0.2 "troff";
157 move to last box .top;
158 up;
159 move 0.3;
160 box invisible width 0.6 height 0.4 "sourced" "file";
161 line <- up 0.3 from A.top;
162 move to A.right;
163 right;
164 arrow 0.3;
165 box invisible width 0.85 height 0.2 "postprocessor";
166 move to last box .bottom;
167 down;
168 arrow 0.3;
169 box invisible width 0.5 height 0.4 "output" "file"
170 .ps
171 .vs
172 .PE
173 .\}
174 .el \{\
175 .nf
176 input sourced
177 file file
178 | |
179 v v
180 preprocessor -> troff -> postprocessor
181 |
182 v
183 output
184 file
185 .fi
186 .\}
187 .PP
188 .
189 That is, files sourced with
190 .B .so
191 are normally read
192 .I only
193 by
194 .B @L_TROFF@
195 (the actual formatter).
196 .B @L_P_SOELIM@
197 is
198 .I not
199 required for
200 .B troff
201 to source files.
202 .
203 .PP
204 If a file to be sourced should also be preprocessed, it must already be read
205 .I before
206 the input file passes through the preprocessor.
207 This is handled by
208 .BR @L_P_SOELIM@ :
209 .
210 .PP
211 .ie t \{\
212 .PS
213 .ps 10
214 .vs 12
215 box invisible width 0.5 height 0.4 "input" "file";
216 move to last box .bottom;
217 down;
218 arrow 0.3;
219 A: box invisible width 0.5 height 0.2 "soelim";
220 line <- 0.3;
221 box invisible width 0.5 height 0.4 "sourced" "file";
222 move to A.right;
223 right;
224 arrow 0.3;
225 box invisible width 0.8 height 0.2 "preprocessor";
226 arrow 0.3;
227 box invisible width 0.35 height 0.2 "troff";
228 arrow 0.3
229 box invisible width 0.85 height 0.2 "postprocessor";
230 move to last box .bottom;
231 down;
232 arrow 0.3;
233 box invisible width 0.5 height 0.4 "output" "file"
234 .ps
235 .vs
236 .PE
237 .\}
238 .el \{\
239 .nf
240 input
241 file
242 |
243 v
244 soelim -> preprocessor -> troff -> postprocessor
245 ^ |
246 | v
247 sourced output
248 file file
249 .fi
250 .\}
251 .
252 .
253 .SH "SEE ALSO"
254 .
255 .BR @L_ROFF@ (@MAN1EXT@)
256 .
257 .cp \n[__compat]
258 .rr __compat
259 .
260 .\" s-ts-mode