1 01/30/87  compose,  comp
  2 
  3 Syntax as a command:  comp paths {-control_args}
  4 
  5 
  6 Function:  prepares formatted documents from raw text segments for
  7 production on various documentation devices including typesetters, line
  8 printers, and user terminals.  Output pages are composed from various
  9 text blocks and controls provided in input files.  Detailed control
 10 over page composition is provided by controls in the input file.
 11 
 12 
 13 Arguments:
 14 paths
 15    are the pathnames of the input files to be formatted.  The suffix
 16    compin must be the last component of the input file entryname;
 17    however, the suffix need not be given in the command line.  If two
 18    or more pathnames are specified, they are treated as if compose had
 19    been invoked separately for each.  Up to 200 input files may be
 20    given with one invocation of the command.  Output is produced in the
 21    order in which the pathnames are given in the command line.  Input
 22    files may be either single segments or multisegment files.  Output
 23    files for very large documents are converted to multisegment files.
 24    The star convention is not supported.
 25 
 26 
 27 Control arguments:
 28    all control arguments specified in the command line apply to all
 29    input file pathnames given.  Control arguments may be freely
 30    intermixed with input file pathnames, except for -arguments which
 31    must be last in the command line.
 32 
 33 
 34 -annotate {key key key ...}, -ann {key key key ...}
 35    shows all font/pointsize changes identified by the optional key
 36    (where key may only be "font" at the present time) in an extra
 37    column to the right of the formatted text and at the output line in
 38    which they occur.
 39 
 40    The style of a typeset document usually calls for a large number of
 41    font/pointsize changes to improve readability.  However, when one is
 42    limited to a terminal and/or lineprinter for early checkout of the
 43    documents, it is very difficult to determine if the changes are all
 44    being made correctly.
 45 
 46 
 47 -arguments arg1 ...  argn, -ag arg1 ...  argn
 48    all fields following are string values to be placed in the
 49    indefinite set of program built-in variables named "CommandArg1"
 50    through "CommandArgn" where "n" is the count of such fields.  The
 51    program built-in variable "CommandArgCount" is set to "n".  If any
 52    argument is to contain blanks, it must be given as a quoted string.
 53 
 54    NOTE:  This control argument, if given, must be the last control
 55           argument in the command line.
 56 
 57 
 58 -brief, -bf
 59    shows only the header line of the defined error line (i.e., the
 60    count of errors), both at normal termination and in response to the
 61    program_interrupt command.
 62 -change_bars {x,p,l,r,d}, -cb {x,p,l,r,d}
 63    generates text change symbols in the output according to the
 64    parameters given.  Change symbols are shown in the text margins as
 65    determined by controls in the text.  (The default for change symbol
 66    generation is OFF.)  All the parameters for this control argument
 67    are optional but, if any are given, they must appear in the order
 68    shown.  If any parameter is skipped, its separating comma must still
 69    be given.  Skipped parameters retain their default values.  The
 70    parameters are:
 71 
 72 
 73    x      a change level character.  If the optional change level
 74           character in any change-bar control is less than x (in the
 75           ASCII collating sequence sense), then no text change symbols
 76           are inserted for those controls.  The x character may be
 77           either numeric or alphabetic.  (The default value for x is
 78           the SP (ASCII code 040) character.)
 79    p      a symbol placement key character.  It may have the values "l"
 80           for left margin, "r" for right margin, "i" for inside margin,
 81           or "o" for outside margin.  (The default for p is "o".)
 82    l      the definition of the text change symbol to be placed to the
 83           left of text.  It must be of the form n{string} where string
 84           is any character string and n is the separation from the
 85           text.  (The default value for string is a vertical bar (|)
 86           and the default value for n is 1.  The n may be given without
 87           string, but string may not be given without n.)
 88 
 89 
 90    r      the definition of the text change symbol to be placed to the
 91           right of text.  It must be of the same form as l above.
 92    d      the definition of the text deletion symbol.  It must be of
 93           the same form as l above except that the default for string
 94           is the asterisk (*).
 95 -change_bars_art {x,p,l,r,d}, -cba {x,p,l,r,d}
 96    as for -change_bars above except that the strings in the l, r, and d
 97    fields may be given as conventional artwork symbols.  (The default
 98    values for the strings are also artwork symbols.)
 99 -check, -ck
100    performs syntax checking on the input file(s) by processing all text
101    and controls but does not produce any output.  (The default for this
102    feature is OFF.)
103 
104 
105 -device {name}, -dv {name}
106    prepares output compatible with the device specified.  This control
107    argument is used when the target device for output is not the
108    default device for the output mode selected.  (If the -output_file
109    control argument is given, the default device is "printer"; if it is
110    not, the default device is "ascii".)  Any device for which
111    name.comp_dsm exists is a supported device.
112 
113    NOTE:  A list of supported devices is available online.  To examine
114           the list, type:
115 
116                  list_comp_dsm (lcdsm)
117 
118 -from {n}, -fm {n}
119    starts printed output at page n.  This control argument is mutually
120    exclusive with the -pages control argument.  You must give the
121    desired structured page number; for example, to print the fourth
122    page of Section 3, you must give "-page 3-4".  (The default value of
123    n is 1.)
124 -galley {n1}{,n2}, -gl {n1}{,n2}
125    produces galley format (continuous single-column text without page
126    headers and footers) output for lines n1 through n2 of the input
127    file.  (The default value of n1 is 1 and the default value for n2 is
128    the last line in the input file.)  If n2 is not given, the comma
129    need not be given.  If n1 is not given, a comma must precede a given
130    value for n2.  (The default for this feature is OFF.)
131 
132 
133 -hyphenate {n}, -hyph {n}, -hph {n}
134    changes the default hyphenation mode from OFF to ON.  The optional
135    parameter n is the length of the smallest separated word part.  (The
136    default value of n is 2.)
137 -indent {n}, -ind {n}
138    adds n spaces at the left page margin of the output.  This space is
139    in addition to any indention given in the text.  (The default value
140    of n is 0, that is, at the left-hand mechanical stop of the output
141    device.)
142 -input_file path, -if path
143    the name of an input file even though path may have the appearance
144    of a numeric parameter or a control argument.
145 -linespace {n}, -ls {n}
146    changes the default line spacing value to n.  The linespace control
147    uses n as a minimum value.  (The default value for n is 1.)
148 
149 
150 -noart, -noa
151    disables the conversion of conventional artwork constructs and
152    inserts space into the output at the positions that such constructs
153    would occupy.  (The default for the artwork conversion feature is
154    ON.)
155 -nobell, -nob
156    suppresses the audible BELL signal when signalling the "waiting"
157    state to the user when the -stop or -wait control argument is used.
158 -nofill, -nof
159    sets the default fill mode to OFF.  (The default fill mode is ON.)
160 
161 
162 -number, -nb
163    prints  input line numbers  at the left  margin of the  output.
164    The  line numbers  have the  form "i n" where  i is  the index
165    number of an  inserted file.  A list of  inserted files showing
166    the index numbers is written on user_output after completion of
167    all text processing.  (The default for this feature is OFF.)
168 -number_append, -nba
169    same as for -number above except that the insert file list is
170    appended to the compout file (if any), starting with a new page.
171 -number_brief, -nbb
172    prints input line numbers at the left margin of the output as for
173    the -number control argument but the list of inserted files is not
174    produced.
175 
176 
177 -output_file {path}, -of {path}
178    directs the formatted output to a file instead of to the user's
179    terminal.  The assumed output device is the Multics online printer
180    but may be changed with the -device control argument.  If path is
181    not given, then the output for all given input files is written to
182    individual output files whose names are formed by replacing the
183    suffix compin of the input file entrynames with the suffix compout.
184    If path is given, then output for all given input files is
185    accumulated in that single bulk output file.  (The default for this
186    feature is OFF; that is, formatted output is written back to the
187    user's terminal.)
188 
189 
190 -pages page_list, -pgs page_list
191    specifies a blank-separated list of selected pages to be printed.
192    Each element in the page_list must be either a single page, n, or a
193    range of pages, n,n, where n is a structured page number as for
194    -from above.  The page numbers given must steadily increase without
195    duplication.  At least one page must be specified and up to 100 list
196    elements may be given.  This control argument is mutually exclusive
197    with the -from and -to control arguments.  (The default for this
198    feature is OFF.)
199 
200    NOTE: Page number structures containing parentheses are changed by
201           the command processor and must be given as quoted strings.
202 
203 
204 -pages_changed {x}, -pgc {x}
205    specifies that, of the pages selected for printing (either all pages
206    or some subset of pages selected through use of the -pages, -from
207    and -to control arguments), only those pages containing text within
208    the range of an active change-bar control or within the scope of the
209    dot_page documentation macro are actually printed.  The base pages
210    of the dot page set (for example, page 3 of the set 3, 3.1, 3.2) are
211    not considered part of the dot page set.  This control argument is
212    independent of the -change_bars and -change_bars_art control
213    arguments, either of which must be given to cause the text change
214    marks to be created.  The optional parameter x chooses the change
215    bar level and must match the x parameter given with -change_bars for
216    proper operation.  (The default value for x is SP (ASCII 040) and
217    chooses all active change levels.)
218 
219 
220 -parameter {STR}, -pm {STR}
221    assigns STR as the value of the built-in variable "Parameter".  (The
222    default value for STR is an empty string.)
223 -passes n, -pass n
224    processes the input file n times to permit proper evaluation of
225    expressions containing variables that are defined following their
226    reference(s) in the text.  No output is produced until the last
227    pass.  (The default value for n is 1.)
228 
229 
230 -stop, -sp
231    waits for a newline character (ASCII code 012) from the user before
232    beginning each page of output and after the last page.  The pause is
233    signalled by giving two BEL/HT sequences and returning the print
234    head to the left margin.  If only a newline is typed, the next page
235    is printed.  If a q is typed, the command invocation is terminated
236    gracefully.  If an r is typed, the page just printed is reprinted.
237    (The default for this feature is OFF.)
238 -to n
239    ends output after the page numbered n where n is a structured page
240    number as for the -from control argument above.  This control
241    argument is mutually exclusive with the -pages control argument.
242    (The default value for n is the last page.)
243 
244 
245 -wait, -wt
246    waits for a newline character (ASCII code 012) before beginning the
247    first page of output to the terminal, but not between pages (see the
248    -stop control argument above).  (The default for this feature is
249    OFF.)
250 
251 
252 Notes:  The program supports the severity active function with the
253 following severity schedule:
254 
255     0 - No errors
256     2 - User  errors (undefined variables,  misspellings, invalid
257         control parameters, etc.)  that prevent specific actions
258     3 - Missing/inaccessible insert files
259     4 - Program errors/limitations and/or internal
260         inconsistencies that may cause a formatter abort
261     5 - Command line errors that prevent any execution
262 
263 
264 The compose command directly supports the facility to change print
265 wheels on "diablo" type terminals during printing of a document.  The
266 standard device modules for "diablo" terminals assign print wheels as
267 follows:
268 
269         Diablo
270 Index   Order#      Name
271   1     38101-01    PICA 10 (or equivalent 10-pitch wheel)
272   2     38510       APL 10
273   3     38102-01    ELITE 12 (or equivalent 12-pitch wheel)
274 
275 Type "help compose.controls" for a summary of compose controls
276 and "help compose.builtins" for a list of builtin variables.
277 
278 
279 Type "help convert_runoff" for information on converting runoff
280 input files.
281 
282 
283 Type "help compose.artwork.gi" for information on constructing
284 artwork.gi within compose.
285 
286 
287