src/preproc/soelim/soelim.1.man

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