src/preproc/soelim/soelim.man

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