04/12/85  Info Segment Standards

Introduction:
An info segment (info seg) is a specially formatted online help file
intended to offer brief information on, not instruction in, the use of
Multics.

The following topics are addressed in the discussion that follows:

   types of info segs
   basic info seg format
   organization of each info seg type
   naming conventions of each info seg type

Notes: Type "help vis" for information on the validate_info_seg
command, which checks for proper info seg syntax and names.


Types of info segs:
Command info seg
   describes usage of a command that performs some action for a user,
   e.g., >doc>info>add_name.info
Command/Active function info seg
   describe usage of a command that may also be used as an active
   function, e.g., >doc>info>mail.info
Subroutine info seg
   documents a subroutine and its entry points, e.g.,
   >doc>info>command_query_
General information info seg
   contains information on a particular subject, e.g.
   >doc>info>info_seg.gi.info


Basic info seg format:
When writing an info seg, use the following guidelines--
   1. Be clear, concise, and definite.
   2. Use concrete, specific, direct language.
   3. Use the active voice and the present tense.
   4. Omit unnecessary words.
   5. Put statements in positive form.
   6. Assume the reader has some knowledge and experience.
   7. Provide only essential facts; reference manuals for details.
   8. Avoid tabs, underlining, and control characters; keep spacing and
      indentation to a minimum; don't end lines with blanks.


Paragraphs:
Make paragraphs no more than 15 lines long and separate them by two
blank lines.  (For each paragraph the help command queries whether to
continue printing.  Groups of text containing single blank lines are
printed as a unit.) Make lines no more than 71 characters long (not
counting newline), with no backspaces (overstriking, underlining) or
non-ASCII characters.  Indent paragraph lines only to emphasize an
example line, to list items in a table, etc.


Header line:
An info seg begins with a heading line, consisting of a date on which
it was last modified and a brief title.  Change the date whenever you
alter any part of the info seg; the format of the date is mm/dd/yy.
Follow it with two spaces and the long (and short, if any) name of the
module being described; for example,
   07/17/84 working_dir, wd
The header is separated from the first section by a single blank line.

The header line on a general information (GI, gi) info seg is the date
followed by a general title; for example, the header line for
star_equal.gi.info reads:
   07/20/84  The Multics Star and Equal Conventions.


Sections:
A section begins with a section title describing the contents of the
paragraphs which follow.  Any number of paragraphs can comprise a 
section.

Section titles:
Put the section title in the first line of the first paragraph of the
section.  Capitalize the first word of the title, and make other title
words lowercase.  The title can be up to 70 characters long followed
by a colon.  (The colon is a special character that the help command
uses as a delimiter for section titles.) The last colon in the line
ends the section title.  In GI info segs, section titles are not
predefined.  In command, active function and subroutine info segs,
standard section titles are used, as describe below.


Using help:
Information, from the info segs, can be displayed via help in 
different formats.  Some of these include:

   print entire info
   print a brief summary of command active function or subroutine info
   print brief heading with info
   print description of requested arguments
   print only heading line
   print section titles

Refer to >doc>info>help.info for more information on the specific uses
of help.  In order to display the data obtained in a meaningful 
manner some suggested organizational techniques and some rules for 
constructing different types of info segments will follow.


List of info seg organization techniques:
standard section titles
   makes titles in command, active function and subroutine info segs
   predictable, so the user can find information more easily.
multiple info writeups
   separates information on multi-function commands such as an archive
   and io_call by operations to allow individual descriptions of each
   operation.
subroutine entry points
   separates information for subroutine entrypoints to allow 
   individual descriptions for each entry point, plus a common
   description of the subroutine as a whole.


Using standard section titles:
The following paragraphs on command/active function info segs
illustrate the usage of standard section titles.

Command/active function info segs:
Info segs describing commands/active functions have a strict format,
designed to work in a special way with the help command.  Normally
one command/active function is described in a single info seg;
however, you can invoke some commands with a variety of operations.
In such cases each operation can best be described in its own info
seg (see "Multiple-entry info segs" below).


List of standard headings for commands/active functions:
   Give the headings exactly in the order shown below.  Avoid, where
   possible, nonstandard headings.

Syntax as a command (required for commands only)
   shows how the program is invoked.  It has the format
      short_name arguments -control_args
   optional arguments and control arguments are given in the Syntax 
   line.  Control arguments are represented in the Syntax line by
   {-control_args} with the actual names of the arguments enclosed in
   braces {}).  The actual names of arguments and control arguments 
   are listed in the "Arguments" and "Control arguments" sections.


   If the command line syntax is too long to fit with the syntax
   heading, put the command line on the next line, indented three
   spaces:

      Syntax as a command:  comp paths {-control args}

   Write multiple ways of calling thus:

      Syntax as a command:  ml path User1...{UserN} {-control_args}
                       or:  ml {destination} {-control_args}


Syntax as an active function (when appropriate)
   shows how the program is invoked as an active function.  It has the
   format [short_name arguments -control_args].

      [where >doc>info>mail.info -a]

Syntax (for requests only)
   shows how the request is invoked; for example, the dial answering
   service request has the format
      d dial_id {User_id} {-control_args}


Function (required)
   gives a brief description of what the command/active function does.
   For example mail:

     Function: sends a message to another user or prints messages in any
     mailbox to which you have sufficient access.


Arguments and control arguments sections (when appropriate)
   give brief descriptions of each argument or control argument.  Put
   section titles on lines by themselves; the titles are plural even
   if only one item is described.  Names of arguments and control
   arguments begin at the left margin on lines by themselves.  The
   names may appear on successive lines but must begin at the left
   margin.  Descriptions, if present, should follow on subsequent
   lines and be indented three spaces.


   The -brief control argument to the help command takes every line it
   finds at the left margin in these sections and displays them in a
   formatted list; therefore it is important to only have lines
   containing the argument or control argument names begin at the left
   margin.  For the -brief control argument the following lines would
   be valid.
   
   -brief, -bf
   
   -brief,
   -bf 
   
   -brief
   -bf


   Indicate default values for control arguments by the string
   "(Default)" or (Default: 5) at the end of the description.  If an
   argument has a lengthy description, cross-reference it to the 
   "Notes" section and put the long explanation there.  Alphabetize
   the arguments and control arguments.  If there are many control
   arguments, organize them by function (with pertinent titles) and
   alphabetize them within each function; for example,
      Control arguments (queuing):
      -brief, -bf
      -force, -fc
      ......
      Control arguments (processing):
      -copy N, -cp N
      -destination {-control_args} STR, -ds {-control_args} STR
      ......


List of...(when appropriate)
   used whenever the command has modes, operations, requests, etc.
   Thus write, "List of modes:" instead of "Modes:".  Format the
   description of each list item as described above for arguments, so
   that help -brief can list these items.  For example:

   List of examples:
    new_call get_line_length_ "", -out
    nc iox_$control incl iox_$look_iocb tape, -out null {}, -cd,
       retention, -addr 4, -cd
    nc hcs_$status_ >udd>m>gd, seg,1, -addr -unspec 0,0,0,0 -octal,
       null{}, -cd
    nc get_group_id_ -expect "foo.Multics.a"


Access required (when appropriate)
   used if the command requires you to have special access or
   permission; for instance,
      Access required (for the list_iacl_seg command)
      You need status permission on the containing directory.

Notes (when appropriate)
   gives comments, clarifications, or any special-case information.
   Avoid giving tutorial notes.

Notes on...(when appropriate)
   used whenever you think that a particular subject--either because
   of its importance or length--requires a section of its own.  Thus
   write, "Notes on formatting:" instead of "Formatting:".


Using multiple info writeups:
The following paragraphs on Multiple-entry info segs illustrate how
to separate information on multi-function commands.


Multiple-entry info segs:
Some commands implement a variety of operations or keywords, each of
which uses a unique syntax and choice of arguments.  In this case you
can apply the following convention, which is a way of logically
splitting one info seg into many, with one info per operation.  Split
info segs have special header lines of the form
   :Info: <long_name>: <short_name>: <date>  <title>
Precede this line by two blank lines; leave two spaces after <date>.
The <long_name> and short_name> names are also add names on the
segment itself, with a suffix of info; the info suffix does not
appear in the header line.  When you invoke help with one of these
names, the name is searched for inside the segment until it is found
on an "Info" line, at which point the information on this request or
keyword is displayed.  Refer to >doc>info>io_call.info for an example
of a multiple-entry info seg.


Using subroutine entry points:
The following paragraphs on subroutine infos illustrate how to
construct a subroutine type info seg.


Subroutine infos:
Info segs documenting a subroutine and its entry points are formatted
differently.  The description starts with a header line like that in
command info segs, with the exception that subroutines do not have
short names and their names always end in an underscore; for example,
   07/20/84  command_query_
The heading is followed by a paragraph or two of general description,
then the following:
   <two blank lines>
   Entry points in command_query_:
   (List is generated by the help command)
   <two blank lines>
   :Entry: command_query_: 07/20/84  command_query_$command_query_


The "Entry" line marks the beginning of each entry point.  The entry
point name is not an add name on the info seg.  The line "Entry
points in..." acts as a trigger for the help command, which, when
encountered, displays the names of each entry point in a list, getting
its information from the "Entry" lines.


List of standard headings for subroutines:
Function
   describes the overall function performed by the subroutine or entry
   point.  The heading is optional, the description is not.
Syntax
   consists of a declare statement showing how the entry point is to
   be declared and a call statement showing the list of arguments to be
   passed when called.
Arguments
   is a list of the arguments shown in the call statement, in the
   order they appear there, along with a brief description and a
   notation of whether the argument being described is Input, Output,
   or Input/Output.
Notes
   are general notes that apply to the entry point.


Info naming conventions:
Info segs for Multics commands, active functions and subroutines are
given the name of the particular system module with a suffix of
".info".  For example, the info describing the pl1 compiler command is
called pl1.info.  If a command/active function also has a short name,
then make <short_name>.info an add name on <command_long_name>.info;
short names are not acceptable as primary names.

Information about changes made to a command or active function from one
release to the next are given the name of the particular system module
with a suffix of ".changes.info".  For example, changes to the fortran
compiler are described in fortran.changes.info.


General information describing features or use of the system is
included in info segs whose names end with a suffix of "gi.info".  For
example, acl_matching.gi.info describes how Access Control List entries
are matched with User_ids in access control commands such as set_acl.
GI info segs can have added names like foo.info to make them easier to
find, but normally a foo.info name is reserved for a command/active
function or subroutine info seg.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved