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

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