1 01/30/87 compose_index, comp_index, cndx
  2 
  3 
  4 Syntax as a command:  comp_index, cndx path {-control_args}
  5 
  6 
  7 Function:  processes raw index data gathered by compose and produces a
  8 cross-reference index file according to a specified format.
  9 
 10 
 11 Arguments:
 12 path
 13    is the pathname of the compin file producing the raw index data.
 14    The compin suffix need not be given.
 15 
 16 
 17 Control arguments:
 18 -alpha_header, -ahdr
 19    inserts centered uppercase alphabetic characters as group separators
 20    whenever the first character of the primary key changes.
 21 -control_file ctl_path, -cf ctl_path
 22    uses ctl_path.cndxctl as the control file for this index.  The
 23    suffix "cndxctl" is assumed if not given.  (The default control file
 24    is path.cndxctl.)
 25 -number n, -nb n
 26    one of the 10 (0 through 9) possible raw index data files.  (The
 27    default value is 0.)  See Notes below.
 28 
 29 
 30 Notes:  The raw index data files are produced by compose when the .hit
 31 control is used.  (The default raw data file is path.0.cndx.)  The
 32 output file is path_entryname.n.index in the current working directory.
 33 If the output file does not exist, it is created; if it does, it is
 34 overwritten.
 35 
 36 
 37 The data in the raw data file is processed into an arbitrarily chosen
 38 format, the style of which is determined partially by constants built
 39 into the program and partially by statements in path.cndxctl.
 40 
 41 
 42 The final set of hit strings (after all raw data processing is
 43 complete) is sorted into an alphabetic collating sequence (i.e.,
 44 without regard to case).  The handling of certain prefix characters is
 45 provided by the use of a control directive.
 46 
 47 
 48 Index control files
 49    The index control file contains compose controls and text lines that
 50    partially determine the format of the index, and directives for
 51    compose_index that control the processing of the hit strings (see
 52    "compose_index Control Directives") and complete the definition of
 53    the index format.  The use of an index control file is not required.
 54    If one does not exist, defaults in the documentation macros and the
 55    program determine the format of the index.
 56 
 57 
 58    The output file created by this program is to be treated just like
 59    any other section of the document to which it applies.  Therefore,
 60    the same macro package initialization must be performed and this is
 61    done with compose controls at the beginning of the index control
 62    file.  A standard macro, l0index, is provided for users who do not
 63    wish to provide their own detailed index format.  The format
 64    established by this macro is the one used by all Multics user
 65    documentation.
 66 
 67 
 68    All hit string processing control directives are given as compose
 69    comment strings.  During processing of the index control file, any
 70    line that is not recognized as a control directive is written to the
 71    output file for further processing by compose.
 72 
 73 compose_index control directives
 74    For the control directives that follow, all input is given in
 75    lowercase without regard to the case of the output.
 76 
 77 
 78 .*blind abcd...
 79    In many instances, a particular keyword will appear as such and with
 80    one or more prefix characters.  A typical example is "rawo" and
 81    "^rawo" in tty_ modes.  It is desirable to have such prefixed and
 82    unprefixed keys sort together in the index.  To accomplished this,
 83    the sort algorithm may be made "blind" to such prefix characters by
 84    the use of this directive.  The set of characters abcd...  are
 85    treated specially as prefix characters such that keywords with them
 86    sort after their unprefixed counterparts.  For example:
 87 
 88       .*blind ^\$
 89 
 90       NOTE:  An older form of this directive, ".*ignore" is also
 91       supported.
 92 
 93    The following directives apply to permuted keys only.
 94 
 95 
 96 .*phrase str
 97    Very frequently, it is necessary that a short phrase instead of a
 98    single word be a key in the index.  This directive provides the
 99    ability to indicate that such phrases are to be treated as keys.
100    Since punctutation may be wanted in the phrase, only one str may be
101    given in the line.  For example:
102 
103       .*phrase access control
104       .*phrase pack labels
105       .*phrase control cards
106 
107 
108 .*tran str1,str2
109    Also very frequently, various grammatical forms of a root keyword or
110    a suffixed keyword appear in an index and should be sorted together.
111    This directive provides the ability to transform such keys for
112    sorting only; the given keys will appear in the final index.  For
113    example:
114 
115       .*tran labels,label
116       .*tran labeled,label
117       .*tran labelling,label
118       .*tran sys_info_$,sys_info_
119 
120 
121 .*excl excl_key{,excl_key}...
122    During permutation, many unwanted hit strings may be generated,
123    primarily due to conjunctions, articles, prepositions, etc., in the
124    given primary key.  Further, permutation may generate unwanted hit
125    strings that have a primary key that is wanted for other hits.  This
126    directive controls the exclusion of hit strings that begin with the
127    partial hit string excl_key.  Only as much of the unwanted hit
128    string as is needed for unique identification need be given, but it
129    must contain the entire new primary key.  For example:
130 
131       .*excl to,for,from,and,but
132       .*excl system~info,reporting~standard