documentation/info_segments/verify

  1 :Info: verify_info: vi:  2020-10-31  verify_info, vi
  2 
  3 Syntax as a command:  vi  {INFO_PATHs} {-control_args}
  4 
  5 
  6 Syntax as an active function:  [vi INFO_PATHs]
  7 
  8 
  9 Function: verifies info segment format, section titles, and names
 10 against guidelines for Multics info segments.  The active function
 11 returns the number of the highest severity error that occurs.
 12 
 13 Also, control arguments display important guidelines for info
 14 segments.
 15 
 16 
 17 Arguments:
 18 INFO_PATHs
 19   relative or absolute pathnames of the info segments to be verified.
 20   A suffix of .info is assumed if not given.  The star convention is
 21   supported to match several segments in the given directory.
 22 
 23 
 24 Control arguments as a command:
 25 -names, -nm
 26   add names required by guidelines if missing from an info segment.
 27   Reorder names following guidelines.  If names exist that conflict
 28   with guidelines, ask user for permission to remove those names.
 29   If removal not granted, move conflicting names to end of name list.
 30   Name changes are listed in informational messages.
 31 -no_names, -nnm
 32   suppress name additions, removals, and reordering.  Error messages
 33   report names that are missing, conflict with guidelines, or need to
 34   be reordered.  (default)
 35 -force_names, -fnm
 36   change names to follow all guidelines without user queries.
 37 
 38 
 39 -totals, -tt
 40   displays only a count of errors found, with level of the highest
 41   severity error.  The active function assumes -totals and returns
 42   only the level of the highest severity error.  All other output is
 43   suppressed.
 44 -long, -lg
 45   displays long error messages and warnings. (default)
 46 -brief, -bf
 47   displays only error message keywords at end of block or section
 48   plus summary messages for paragraph and line errors.
 49 -rules {AREA}
 50   displays verify_info guidelines and rules for info segment structure
 51   and format.  See "List of rule areas" below.
 52 
 53 
 54 Control arguments (displaying info lines):
 55    It is sometimes useful to display lines of an info segment or block
 56    to understand errors reported by verify_info.  Line-related errors
 57    are reported by keyword(s) at the end of each displayed line.
 58 -lines,
 59 -ln COUNT,
 60 -ln START:COUNT
 61   displays lines of the info segment.  The optional START line number
 62   and COUNT of lines refer to lines within the entire info segment.
 63   If START is a negative integer, it refers to a line number
 64   counting back from the end of the segment: -lines -3: displays the
 65   final 3 lines of the segment.  If neither START nor COUNT is given,
 66   the entire info segment is printed.
 67 
 68 
 69 -block,
 70 -bk COUNT,
 71 -bk START:COUNT
 72   displays lines of each block of the info segment.  The START and
 73   COUNT values refer to lines within the block.  If START is a
 74   negative integer, it refers to a line counting back from the end of
 75   the block.  -block -3:  displays the final 3 lines of the info
 76   block.  If neither START nor COUNT is given, each info block is
 77   printed.
 78 
 79 
 80 Control arguments (debugging verify_info):
 81    These control arguments display additional data used to check info
 82    segment format against guidelines.
 83 -debug SELECTOR,
 84 -db SELECTOR
 85   selects a debugging function.  -debug may be given more that once
 86   to select several functions; or once with several SELECTORs
 87   separated by commas.
 88 
 89 
 90 List of rule areas:
 91    The -rules AREA operand may be any of the following.
 92 all, a
 93   displays all rules and guidelines used by verify_info. (default)
 94 file, f
 95   displays guidelines for supported file structures (allowed order of
 96   :Info: :[Info]: :Entry: and :hcom: block divider lines within an
 97   info segment).
 98 block, bk
 99   displays rules used to determine the kind of each info block
100   (e.g., command or active function, subroutine, subsystem request,
101   etc.).
102 
103 
104 section, scn
105   displays Multics standard info segment section titles, and a list of
106   obsolete or deprecated titles with a preferred replacement.
107 KIND_OF_INFO_BLOCK
108   displays section titles typical for a particular kind of info block
109   including the usual order of appearance within the block of each
110   title.  See "List of info block kinds" below.
111 
112 
113 List of info block kinds:
114   The -rules KIND_OF_INFO_BLOCK value may be any of the following.
115 all_kinds, ak
116   display section titles typical of all of the following block kinds.
117 command, cmd
118   display section titles used in info blocks describing commands
119   and/or active functions.
120 general_info, gi
121   display section titles used in info blocks describing general
122   information.
123 
124 
125 subsystem, ss
126   display section titles used in info blocks describing subsystem
127   requests and/or active requests; subsystem request summary; or other
128   subsystem topic.
129 request, req
130   display section titles used in info blocks describing subsystem
131   requests and/or active requests.
132 topics, topic
133   display section titles used in info blocks describing subsystem
134   topics (information not a request description or summary of
135   requests).
136 
137 
138 subroutine, subr
139   display section titles used in info blocks describing a subroutine
140   or function.  This includes a subroutine introduction block, and
141   blocks describing a subroutine entry point.
142 io_module, io
143   display section titles used in info blocks describing an I/O module;
144   or one of its setup operations (open_file, close_file, or detach);
145   or one of its control orders.
146 
147 
148 List of debug selectors:
149 file, f
150   display names, plus a specification line containing:
151     - file structure case number
152     - specification string giving block cardinality and block
153       type constraints
154     - count of each type of info block divider:
155        N:  first info block of segment, having no :Info: divider.
156        E:  a subroutine :Entry: divider.
157        I:  an :Info: divider.
158       [I]: an :[Info]: divider.
159        H:  an :hcom: history comment divider.
160 
161 
162 block, bk
163   displays block divider and header details.
164 section, scn
165   displays items found in Syntax... sections.
166 list, ls
167   displays item names found in Arguments, Control arguments, and
168   List of... sections.
169 
170 
171 Notes on verification:
172 The verify_info (vi) command verifies the format, section titles, and
173 names of an info segment.  For more details on info segment format,
174 type:  help info_seg.gi
175 
176 
177 List of error message severities:
178   Error messages printed by verify_info are of five severity levels:
179 Severity 5
180   structural errors preventing parsing of the info segment into
181   blocks, sections, paragraphs, and lines.
182 Severity 4
183   errors that should be corrected before installing the info segment.
184 Severity 3
185   errors in following info segment guidelines, a few of which may
186   qualify as valid exceptions.
187 Severity 2
188   even less important errors.
189 Severity 1
190   warnings of expected situations, such as use of an non-typical
191   section title.
192 
193 
194 :hcom:
195 /****^  HISTORY COMMENTS:
196   1) change(2020-06-12,GDixon), approve(2021-02-23,MCR10089),
197      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
198       A) Initial version of this info segment.
199   2) change(2020-10-31,GDixon), approve(2021-02-23,MCR10089),
200      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
201       A) Remove incorrect ellipsis usage.
202       B) Correct references to info block divider tokens:
203             :Info:  :[Info]:  :Entry:  :hcom:
204   3) change(2020-11-25,GDixon), approve(2021-02-23,MCR10089),
205      audit(2021-03-31,Swenson), install(2021-03-31,MR12.6g-0053):
206       A) Revise for use of verify_info_data.incl.pl1 include file,
207          and its simplification of the verify_info user interface.
208                                                    END HISTORY COMMENTS */