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