src/preproc/soelim/soelim.1.man

   1 '\" p
   2 .TH @g@soelim @MAN1EXT@ "@MDATE@" "groff @VERSION@"
   3 .SH Name
   4 @g@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-2020 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 @g@soelim
  66 .RB [ \-Crt ]
  67 .RB [ \-I
  68 .IR dir ]
  69 .RI [ input-file\~ .\|.\|.]
  70 .YS
  71 .
  72 .
  73 .SY @g@soelim
  74 .B \-\-help
  75 .YS
  76 .
  77 .
  78 .SY @g@soelim
  79 .B \-v
  80 .
  81 .SY @g@soelim
  82 .B \-\-version
  83 .YS
  84 .
  85 .
  86 .\" ====================================================================
  87 .SH Description
  88 .\" ====================================================================
  89 .
  90 GNU
  91 .I soelim \" GNU
  92 is a preprocessor for the
  93 .MR groff @MAN7EXT@
  94 document formatting system.
  95 .
  96 .I @g@soelim
  97 works as a filter to eliminate source requests in
  98 .MR roff @MAN7EXT@
  99 input files;
 100 that is,
 101 it replaces lines of the form
 102 .RB \[lq] .so
 103 .IR included-file \[rq]
 104 within each text
 105 .I input-file
 106 with the contents of
 107 .IR included-file ,
 108 recursively.
 109 .
 110 By default,
 111 it writes
 112 .B lf
 113 requests as well to record the name and line number of each
 114 .I input-file
 115 and
 116 .IR included-file ,
 117 so that any diagnostics produced by later processing can be accurately
 118 traced to the original input.
 119 .
 120 Options allow this information to be suppressed
 121 .RB ( \-r )
 122 or supplied in \*[tx] comments instead
 123 .RB ( \-t ).
 124 .
 125 In the absence of
 126 .I input-file
 127 arguments,
 128 .I @g@soelim
 129 reads the standard input stream.
 130 .
 131 Output is written to the standard output stream.
 132 .
 133 .
 134 .PP
 135 If the name of a
 136 .I macro-file
 137 contains a backslash,
 138 use
 139 .B \[rs]\[rs]
 140 or
 141 .B \[rs]e
 142 to embed it.
 143 .
 144 To embed a space,
 145 write
 146 .RB \[lq] \[rs]\~ \[rq]
 147 (backslash followed by a space).
 148 .
 149 Any other escape sequence in
 150 .IR macro-file ,
 151 including
 152 .RB \[lq] \[rs][rs] \[rq],
 153 prevents
 154 .I @g@soelim
 155 from replacing the source request.
 156 .
 157 .
 158 .PP
 159 The dot must be at the beginning of a line and must be followed by
 160 .RB \[lq] so \[rq]
 161 without intervening spaces or tabs for
 162 .I @g@soelim
 163 to handle it.
 164 .
 165 This convention allows source requests to be \[lq]protected\[rq] from
 166 processing by
 167 .IR @g@soelim ,
 168 for instance as part of macro definitions or
 169 .RB \[lq] if \[rq]
 170 requests.
 171 .
 172 .
 173 .PP
 174 There must also be at least one space between
 175 .RB \[lq] so \[rq]
 176 and its
 177 .I macro-file
 178 argument.
 179 .
 180 The
 181 .B \-C
 182 option overrides this requirement.
 183 .
 184 .
 185 .PP
 186 The foregoing is the limit of
 187 .IR @g@soelim 's
 188 understanding of the
 189 .I roff
 190 language;
 191 it does not,
 192 for example,
 193 replace the input line
 194 .
 195 .RS
 196 .EX
 197 \&.if 1 .so otherfile
 198 .EE
 199 .RE
 200 .
 201 with the contents of
 202 .IR otherfile .
 203 .
 204 With its
 205 .B \-r
 206 option,
 207 therefore,
 208 .I @g@soelim
 209 can be used to process text files in general,
 210 to flatten a tree of input documents.
 211 .
 212 .
 213 .PP
 214 .I soelim \" generic
 215 was designed to handle situations where the target of a
 216 .I roff \" generic
 217 source request requires a preprocessor such as
 218 .MR @g@eqn @MAN1EXT@ ,
 219 .MR @g@pic @MAN1EXT@ ,
 220 .MR @g@refer @MAN1EXT@ ,
 221 or
 222 .MR @g@tbl @MAN1EXT@ .
 223 .
 224 The usual processing sequence of
 225 .MR groff @MAN1EXT@
 226 is as follows.
 227 .
 228 .\" Does this groff installation use a command prefix?  In installed
 229 .\" pages, this comparison will not look like it needs to be dynamically
 230 .\" decided.
 231 .\"
 232 .\" This is done so that the box sizes (in the pic(1) diagram) and arrow
 233 .\" alignments (in the text alternative) can remain fixed.
 234 .if !'@g@'\%' \{\
 235 In the diagrams below,
 236 the traditional names for
 237 .I soelim
 238 and
 239 .I troff
 240 are used;
 241 on this system,
 242 the GNU versions are installed as
 243 .I @g@soelim
 244 and
 245 .IR @g@troff .
 246 .\}
 247 .
 248 .
 249 .PP
 250 .ie t \{\
 251 .PS
 252 .ps 10
 253 .vs 12
 254 box invisible width 0.5 height 0.4 "input" "file";
 255 move to last box .bottom;
 256 down;
 257 arrow 0.3;
 258 box invisible width 0.8 height 0.2 "preprocessor";
 259 move to last box .right
 260 right;
 261 arrow 0.3;
 262 A: box invisible width 0.35 height 0.2 "troff";
 263 move to last box .top;
 264 up;
 265 move 0.3;
 266 box invisible width 0.6 height 0.4 "sourced" "file";
 267 line <- up 0.3 from A.top;
 268 move to A.right;
 269 right;
 270 arrow 0.3;
 271 box invisible width 0.85 height 0.2 "postprocessor";
 272 move to last box .bottom;
 273 down;
 274 arrow 0.3;
 275 box invisible width 0.5 height 0.4 "output" "file"
 276 .ps
 277 .vs
 278 .PE
 279 .\}
 280 .el \{\
 281 .EX
 282           input        sourced
 283           file          file
 284             \[bv]             \[bv]
 285             \[da]             \[da]
 286         preprocessor \[an]\[->] troff \[an]\[->] postprocessor
 287                                       \[bv]
 288                                       \[da]
 289                                    output
 290                                     file
 291 .EE
 292 .\}
 293 .PP
 294 That is,
 295 files sourced with
 296 .RB \[lq] so \[rq]
 297 are normally read
 298 .I only
 299 by the formatter,
 300 .IR @g@troff .
 301 .
 302 .I @g@soelim
 303 is
 304 .I not
 305 required for
 306 .I @g@troff
 307 to source files.
 308 .
 309 .
 310 .PP
 311 If a file to be sourced should also be preprocessed,
 312 it must already be read
 313 .I before
 314 the input file passes through the preprocessor.
 315 .
 316 .IR @g@soelim ,
 317 normally invoked via
 318 .IR groff 's
 319 .B \-s
 320 option,
 321 handles this.
 322 .
 323 .
 324 .PP
 325 .ie t \{\
 326 .PS
 327 .ps 10
 328 .vs 12
 329 box invisible width 0.5 height 0.4 "input" "file";
 330 move to last box .bottom;
 331 down;
 332 arrow 0.3;
 333 A: box invisible width 0.5 height 0.2 "soelim";
 334 line <- 0.3;
 335 box invisible width 0.5 height 0.4 "sourced" "file";
 336 move to A.right;
 337 right;
 338 arrow 0.3;
 339 box invisible width 0.8 height 0.2 "preprocessor";
 340 arrow 0.3;
 341 box invisible width 0.35 height 0.2 "troff";
 342 arrow 0.3
 343 box invisible width 0.85 height 0.2 "postprocessor";
 344 move to last box .bottom;
 345 down;
 346 arrow 0.3;
 347 box invisible width 0.5 height 0.4 "output" "file"
 348 .ps
 349 .vs
 350 .PE
 351 .\}
 352 .el \{\
 353 .EX
 354           input
 355           file
 356             \[bv]
 357             \[da]
 358           soelim \[an]\[->] preprocessor \[an]\[->] troff \[an]\[->] \
 359 postprocessor
 360             \[ua]                                     \[bv]
 361             \[bv]                                     \[da]
 362          sourced                               output
 363           file                                  file
 364 .EE
 365 .\}
 366 .
 367 .
 368 .\" ====================================================================
 369 .SH Options
 370 .\" ====================================================================
 371 .
 372 .B \-\-help
 373 displays a usage message,
 374 while
 375 .B \-v
 376 and
 377 .B \-\-version
 378 show version information;
 379 all exit afterward.
 380 .
 381 .
 382 .TP
 383 .B \-C
 384 Recognize an input line starting with
 385 .B .so
 386 even if a character other than a space or newline follows.
 387 .
 388 .TP
 389 .BI \-I\~ dir
 390 Search the directory
 391 .I dir
 392 path for
 393 .I input-
 394 and
 395 .I included-files.
 396 .
 397 .B \-I
 398 may be specified more than once;
 399 each
 400 .I dir
 401 is searched in the given order.
 402 .
 403 To search the current working directory before others,
 404 add
 405 .RB \[lq] "\-I .\&" \[rq]
 406 at the desired place;
 407 it is otherwise searched last.
 408 .
 409 .
 410 .TP
 411 .B \-r
 412 Write files \[lq]raw\[rq];
 413 do not add
 414 .B lf
 415 requests.
 416 .
 417 .
 418 .TP
 419 .B \-t
 420 Emit \*[tx] comment lines starting with
 421 .RB \[lq] % \[rq]
 422 indicating the current file and line number,
 423 rather than
 424 .B lf
 425 requests for the same purpose.
 426 .
 427 .
 428 .PP
 429 If both
 430 .B \-r
 431 and
 432 .B \-t
 433 are given,
 434 the last one specified controls.
 435 .
 436 .
 437 .\" ====================================================================
 438 .SH "See also"
 439 .\" ====================================================================
 440 .
 441 .MR groff @MAN1EXT@
 442 .
 443 .
 444 .\" Clean up.
 445 .rm tx
 446 .
 447 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
 448 .cp \n[*groff_soelim_1_man_C]
 449 .do rr *groff_soelim_1_man_C
 450 .
 451 .
 452 .\" Local Variables:
 453 .\" fill-column: 72
 454 .\" mode: nroff
 455 .\" End:
 456 .\" vim: set filetype=groff textwidth=72: