contrib/groff/src/preproc/soelim/soelim.man

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