1 :Info: info_seg.gi: info_seg:  2019-05-28  Info Segment Standards
  2 
  3 Introduction:
  4 An info segment (info seg) is a specially formatted online help file
  5 intended to offer brief information on, not instruction in, the use of
  6 Multics.
  7 
  8 The following topics are addressed in the discussion that follows:
  9 
 10    types of info segs
 11    basic info seg format
 12    organization of each info seg type
 13    naming conventions of each info seg type
 14 
 15 
 16 Notes: Type "help vis" for information on the validate_info_seg
 17 command, which checks for proper info seg syntax and names.
 18 
 19 
 20 Types of info segs:
 21 Command info seg
 22    describes usage of a command that performs some action for a user,
 23    e.g., >doc>info>add_name.info
 24 Command/Active function info seg
 25    describe usage of a command that may also be used as an active
 26    function, e.g., >doc>info>mail.info
 27 Subroutine info seg
 28    documents a subroutine and its entry points, e.g.,
 29    >doc>info>command_query_
 30 General information info seg
 31    contains information on a particular subject, e.g.
 32    >doc>info>info_seg.gi.info
 33 
 34 
 35 Basic info seg format:
 36 When writing an info seg, use the following guidelines--
 37    1. Be clear, concise, and definite.
 38    2. Use concrete, specific, direct language.
 39    3. Use the active voice and the present tense.
 40    4. Omit unnecessary words.
 41    5. Put statements in positive form.
 42    6. Assume the reader has some knowledge and experience.
 43    7. Provide only essential facts; reference manuals for details.
 44    8. Avoid tabs, underlining, and control characters; keep spacing and
 45       indentation to a minimum; don't end lines with blanks.
 46 
 47 
 48 Paragraphs:
 49 Make paragraphs no more than 15 lines long and separate them by two
 50 blank lines.  (For each paragraph the help command queries whether to
 51 continue printing.  Groups of text containing single blank lines are
 52 printed as a unit.) Make lines no more than 71 characters long (not
 53 counting newline), with no backspaces (overstriking, underlining) or
 54 non-ASCII characters.  Indent paragraph lines only to emphasize an
 55 example line, to list items in a table, etc.
 56 
 57 
 58 Header line:
 59 An info seg begins with a header line, consisting of a date on which
 60 it was last modified and a brief title.
 61 
 62 Change the date whenever you alter any part of the info seg.  The date
 63 is in iso_date format.  Type "date_time_$format -ca iso_date" for a
 64 description of this format, or see sample header lines below.
 65 
 66 Follow the date with two spaces and the long (and short, if any)
 67 name of the module being described; for example,
 68 
 69    1985-10-10  validate_info_seg, vis
 70    1985-09-23  ioa_
 71 
 72 The header is separated from the first section by a single blank line.
 73 
 74 
 75 The header line of a general information (.gi) info seg is the date
 76 followed by a general title; for example, the header line for
 77 star_equal.gi.info reads:
 78 
 79    1986-07-30  Star and Equal Conventions (general information)
 80 
 81 
 82 Sections:
 83 A section begins with a section title describing the contents of the
 84 paragraphs which follow.  Any number of paragraphs can comprise a
 85 section.
 86 
 87 Section titles:
 88 Put the section title in the first line of the first paragraph of the
 89 section.  Capitalize the first word of the title, and make other title
 90 words lowercase.  The title can be up to 70 characters long followed
 91 by a colon.  (The colon is a special character that the help command
 92 uses as a delimiter for section titles.) The last colon in the line
 93 ends the section title.  In GI info segs, section titles are not
 94 predefined.  In command, active function and subroutine info segs,
 95 standard section titles are used, as describe below.
 96 
 97 
 98 Using help:
 99 Information, from the info segs, can be displayed via help in
100 different formats.  Some of these include:
101 
102    print entire info
103    print a brief summary of command active function or subroutine info
104    print brief heading with info
105    print description of requested arguments
106    print only heading line
107    print section titles
108 
109 Refer to >doc>info>help.info for more information on the specific uses
110 of help.  In order to display the data obtained in a meaningful
111 manner some suggested organizational techniques and some rules for
112 constructing different types of info segments will follow.
113 
114 
115 List of info seg organization techniques:
116 standard section titles
117    makes titles in command, active function and subroutine info segs
118    predictable, so the user can find information more easily.
119 multiple info writeups
120    separates information on multi-function commands such as an archive
121    and io_call by operations to allow individual descriptions of each
122    operation.
123 subroutine entry points
124    separates information for subroutine entrypoints to allow
125    individual descriptions for each entry point, plus a common
126    description of the subroutine as a whole.
127 
128 
129 Using standard section titles:
130 The following paragraphs on command/active function info segs
131 illustrate the usage of standard section titles.
132 
133 Command/active function info segs:
134 Info segs describing commands/active functions have a strict format,
135 designed to work in a special way with the help command.  Normally
136 one command/active function is described in a single info seg;
137 however, you can invoke some commands with a variety of operations.
138 In such cases each operation can best be described in its own info
139 seg (see "Multiple-entry info segs" below).
140 
141 
142 List of standard headings for commands/active functions:
143    Give the headings exactly in the order shown below.  Avoid, where
144    possible, nonstandard headings.
145 
146 Syntax as a command (required for commands only)
147    shows how the program is invoked.  It has the format
148       short_name arguments -control_args
149    optional arguments and control arguments are given in the Syntax
150    line.  Control arguments are represented in the Syntax line by
151    {-control_args} with the actual names of the arguments enclosed in
152    braces {}).  The actual names of arguments and control arguments
153    are listed in the "Arguments" and "Control arguments" sections.
154 
155 
156    If the command line syntax is too long to fit with the syntax
157    heading, put the command line on the next line, indented three
158    spaces:
159 
160       Syntax as a command:  comp paths {-control args}
161 
162    Write multiple ways of calling thus:
163 
164       Syntax as a command:  ml path User1...{UserN} {-control_args}
165                        or:  ml {destination} {-control_args}
166 
167 
168 Syntax as an active function (when appropriate)
169    shows how the program is invoked as an active function.  It has the
170    format [short_name arguments -control_args].
171 
172       [where >doc>info>mail.info -a]
173 
174 Syntax (for requests only)
175    shows how the request is invoked; for example, the dial answering
176    service request has the format
177       d dial_id {User_id} {-control_args}
178 
179 
180 Function (required)
181    gives a brief description of what the command/active function does.
182    For example mail:
183 
184      Function: sends a message to another user or prints messages in
185      any mailbox to which you have sufficient access.
186 
187 
188 Arguments and control arguments sections (when appropriate)
189    give brief descriptions of each argument or control argument.  Put
190    section titles on lines by themselves; the titles are plural even
191    if only one item is described.  Names of arguments and control
192    arguments begin at the left margin on lines by themselves.  The
193    names may appear on successive lines but must begin at the left
194    margin.  Descriptions, if present, should follow on subsequent
195    lines and be indented three spaces.
196 
197 
198    The -brief control argument to the help command takes every line it
199    finds at the left margin in these sections and displays them in a
200    formatted list; therefore it is important to only have lines
201    containing the argument or control argument names begin at the left
202    margin.  For the -brief control argument the following lines would
203    be valid.
204 
205    -brief, -bf
206 
207    -brief,
208    -bf
209 
210    -brief
211    -bf
212 
213 
214    Indicate default values for control arguments by the string
215    "(Default)" or (Default: 5) at the end of the description.  If an
216    argument has a lengthy description, cross-reference it to the
217    "Notes" section and put the long explanation there.  Alphabetize
218    the arguments and control arguments.  If there are many control
219    arguments, organize them by function (with pertinent titles) and
220    alphabetize them within each function; for example,
221       Control arguments (queuing):
222       -brief, -bf
223       -force, -fc
224       ......
225       Control arguments (processing):
226       -copy N, -cp N
227       -destination {-control_args} STR, -ds {-control_args} STR
228       ......
229 
230 
231 List of...(when appropriate)
232    used whenever the command has modes, operations, requests, etc.
233    Thus write, "List of modes:" instead of "Modes:".  Format the
234    description of each list item as described above for arguments, so
235    that help -brief can list these items.  For example:
236 
237    List of examples:
238     new_call get_line_length_ "", -out
239     nc iox_$control incl iox_$look_iocb tape, -out null {}, -cd,
240        retention, -addr 4, -cd
241     nc hcs_$status_ >udd>m>gd, seg,1, -addr -unspec 0,0,0,0 -octal,
242        null{}, -cd
243     nc get_group_id_ -expect "foo.Multics.a"
244 
245 
246 Access required (when appropriate)
247    used if the command requires you to have special access or
248    permission; for instance,
249       Access required (for the list_iacl_seg command)
250       You need status permission on the containing directory.
251 
252 Notes (when appropriate)
253    gives comments, clarifications, or any special-case information.
254    Avoid giving tutorial notes.
255 
256 Notes on...(when appropriate)
257    used whenever you think that a particular subject--either because
258    of its importance or length--requires a section of its own.  Thus
259    write, "Notes on formatting:" instead of "Formatting:".
260 
261 
262 Using multiple info writeups:
263 The following paragraphs on Multiple-entry info segs illustrate how
264 to separate information on multi-function commands.
265 
266 
267 Multiple-entry info segs:
268 Some commands implement a variety of operations or keywords, each of
269 which uses a unique syntax and choice of arguments.  In this case you
270 can apply the following convention, which is a way of logically
271 splitting one info seg into many, with one info per operation.  Split
272 info segs have special header lines of the form
273    :Info: <long_name>: <short_name>: <iso_date>  <title>
274 Precede this line by two blank lines; leave two spaces after
275 <iso_date>.  The <long_name> and short_name> names are also add names
276 on the segment itself, with a suffix of info; the info suffix does not
277 appear in the header line.  When you invoke help with one of these
278 names, the name is searched for inside the segment until it is found
279 on an "Info" line, at which point the information on this request or
280 keyword is displayed.  Refer to >doc>info>io_call.info for an example
281 of a multiple-entry info seg.
282 
283 
284 Using subroutine entry points:
285 The following paragraphs on subroutine infos illustrate how to
286 construct a subroutine type info seg.
287 
288 
289 Subroutine infos:
290 Info segs documenting a subroutine and its entry points are formatted
291 differently.  The description starts with a header line like that in
292 command info segs, with the exception that subroutines do not have
293 short names and their names always end in an underscore; for example,
294    1984-07-20  command_query_
295 The heading is followed by a paragraph or two of general description,
296 then the following:
297    <two blank lines>
298    Entry points in command_query_:
299    (List is generated by the help command)
300    <two blank lines>
301    :Entry: command_query_: 1984-07-20  command_query_$command_query_
302 
303 
304 The "Entry" line marks the beginning of each entry point.  The entry
305 point name is not an add name on the info seg.  The line "Entry
306 points in..." acts as a trigger for the help command, which, when
307 encountered, displays the names of each entry point in a list, getting
308 its information from the "Entry" lines.
309 
310 
311 List of standard headings for subroutines:
312 Function
313    describes the overall function performed by the subroutine or entry
314    point.  The heading is optional, the description is not.
315 Syntax
316    consists of a declare statement showing how the entry point is to
317    be declared and a call statement showing the list of arguments to be
318    passed when called.
319 Arguments
320    is a list of the arguments shown in the call statement, in the
321    order they appear there, along with a brief description and a
322    notation of whether the argument being described is Input, Output,
323    or Input/Output.
324 Notes
325    are general notes that apply to the entry point.
326 
327 
328 Adding a history comment to an info seg: A history comment may be
329 added to most info segments using the command:
330    hcom add INFO_SEG_NAME.info
331 
332 
333 Info naming conventions:
334 Info segs for Multics commands, active functions and subroutines are
335 given the name of the particular system module with a suffix of
336 ".info".  For example, the info describing the pl1 compiler command is
337 called pl1.info.  If a command/active function also has a short name,
338 then make <short_name>.info an add name on <command_long_name>.info;
339 short names are not acceptable as primary names.
340 
341 Information about changes made to a command or active function from one
342 release to the next are given the name of the particular system module
343 with a suffix of ".changes.info".  For example, changes to the fortran
344 compiler are described in fortran.changes.info.
345 
346 
347 General information describing features or use of the system is
348 included in info segs whose names end with a suffix of "gi.info".  For
349 example, acl_matching.gi.info describes how Access Control List entries
350 are matched with User_ids in access control commands such as set_acl.
351 GI info segs can have added names like foo.info to make them easier to
352 find, but normally a foo.info name is reserved for a command/active
353 function or subroutine info seg.
354 
355 
356 :hcom:
357 /****^  HISTORY COMMENTS:
358   1) change(1985-04-12,GDixon), approve(), audit(), install():
359       Written by Gary Dixon.
360   2) change(2019-05-29,GDixon), approve(2019-05-29,MCR10065),
361      audit(2019-09-20,Swenson), install(2019-09-20,MR12.6g-0030):
362      Add first history comment, when hcom began supporting info segs.
363   3) change(2021-06-09,GDixon), approve(2021-06-09,MCR10089a),
364      audit(2021-06-09,Swenson), install(2021-06-09,MR12.6g-0059):
365      Change info_seg.hcom to describe the newer :hcom: divider that replaces
366      the obsolete :Internal: divider in prior versions of this info segment.
367   4) change(2021-11-13,GDixon), approve(2021-12-07,MCR10105),
368      audit(2021-12-10,Swenson), install(2021-12-10,MR12.8-1014):
369      A) Remove references to info_seg.hcom.info now that the history_comment
370         command can add the first history comment to an :hcom: block in the
371         info segment.
372      B) Delete the block info_seg.hcom from this info segment.
373                                                    END HISTORY COMMENTS */