 20 Apr 82                                                            
  
  
  
  
                     Hierarchical Information Files
  
  
  
       Hierarchical   Information   Files  may  be  used  to  organize
  information  into  a  hierarchical  structure  so  that  it  may  be
  displayed or  searched  like  the  table of contents of a book.  The
  hierarchy format is extremely useful for several purposes.    Source
  programs  may  be documented by files representing Structured Design
  charts, nested subroutine calls, and  multi-level  data  structures.
  Online  help  files  can  be  created  to display multiple levels of
  detailed help information which may be searched at  random.    Also,
  disk   files   can   be  documented  by  index  files  formatted  as
  hierarchical information files. 
  
  
 PURPOSE of Info Files
  
       Hierarchical Information Files are used to organize information
  into a hierarchy of nested levels of detail which may be searched at
  random. 
  
  
 HANDLING of Info Files
  
       Hierarchical Information Files may be searched or displayed  by
  the new  VAX  command  "INFO"  (defined  by  "@[UTIL]Symbols").  The
  "INFO" command allows retrieved information to be displayed  a  page
  at a  time  or  stored  in a disk file for later use.  Other command
  options control the output page length or the number  of  sub-levels
  of detail displayed. 
  
       Information  Files  may  be  stored  either  in normal Files-11
  format or in FORTRAN direct-file form.  Files which  are  stored  in
  Files-11 format  may  be  created or edited by any text editor.  The
  FORTRAN direct-file form requires  a  record  length  of  85  bytes.
  Direct files use slightly more than twice the disk space of those in
  Files-11  format,  but  are  faster for very frequent usage (several
  times a day). 
  
  
 STRUCTURE of Info Files
  
       Hierarchical Information Files are encoded by nested groups  of
  parentheses.   A branch of a hierarchy may be coded in either of two
  forms, a multi-line form or a one-line form. 
  
       MULTI-LINE BRANCH - In the  multi-line  form,  a  branch  of  a
  hierarchy  is  opened  by  a  line  which  contains a left (opening)
  parenthesis in the first column of  the  line,  and  the  branch  is
  closed  by  a  line which begins with a right (closing) parenthesis.
  For example: 
  
  
  
  
  
  
  
 Reference Guide                                         Info Files  1
  
 20 Apr 82                                                            
  
       ( This begins a branch of the hierarchy....
           ...a line contained in the branch...
           ...a line contained in the branch...
       ) This ends a branch of the hierarchy.
  
  Any words which appear on the opening line of a branch (words  which
  follow  1  space  past  the  left parenthesis) are treated as search
  words and may be used as search-topic  words  or  prefixes  for  the
  "INFO" command  to  retrieve  information.    On the other hand, any
  words which appear on the closing  line  of  a  branch  are  totally
  ignored and  function  essentially as comments.  The lines contained
  within the branch are displayed as contents of the branch, but  they
  are  not  searched  unless  they, in turn, start a nested sub-branch
  (begin with a left parenthesis). 
  
       Any lines which precede the start of the first hierarchy branch
  in a file are  ignored  by  the  "INFO"  command  and  will  not  be
  displayed: 
  
           ...this line is ignored...
           ...this line is ignored...
       ( This line will be searched for topic keywords....
           ...a line contained in the branch...
       ( This sub-branch line will be searched for topic keywords....
       ) This line ends the sub-branch.
           ...a line contained in the branch...
       ) This ends a branch of the hierarchy.
  
  
       ONE-LINE BRANCH -  In  the one-line form of a hierarchy branch,
  the entire branch is defined on a single line which  begins  with  a
  left  parenthesis in the first column and ends with an at-sign ("@")
  followed by a right parenthesis: 
  
       ( This is a one-line branch of the hierarchy.@)
  
  The "@)" pair must appear before column 80 to  be  recognized  as  a
  branch terminator  (80-character  line length).  Comments may follow
  after the closing right parenthesis. 
  
  
 EXAMPLES of Info Files
  
       Several  examples  of  Hierarchical   Information   Files   are
  currently in  use  on  the VAX.  These files are used by the new VAX
  commands "INFO", "NEWS" and "WHERE". 
  
       The general information displayed  by  the  "INFO"  command  is
  stored as an Info File of several hundred entries. 
  
       The  "NEWS" command stores the index of published news articles
  as an Info File arranged by the month of the publishing date.    The
  option  "-I"  for  the  "NEWS"  command  will  allow the index to be
  searched or  displayed  in  its  hierarchical  arrangement.     News
  articles  on  any particular topic, or combination of topics, can be
  quickly located. 
  
       The new VAX command "WHERE" uses the file  named  "WHERE.;"  in
  the default  directory  to  store  the  title of the directory.  The
  remainder of the "WHERE" file may be used to  store  notes  or  file
  
  
 Reference Guide                                         Info Files  2
  
 20 Apr 82                                                            
  
  descriptions using  the  Hierarchical-Information-File  format.  The
  option "-I" for the "WHERE" command will allow the information to be
  searched or displayed in its hierarchical arrangement. 
  
  
 SAMPLE Info Files
  
       The following sample Info File describes a SORT  routine  which
  calls the two routines COMPARE_KEYS and SWAP_RECORDS: 
  
     ( SORT      - SORT RECORDS BY ALPHA KEY FIELD
     ( *BUFCOM   - COMMON DATA AREA FOR SORT BUFFER@)
     ( COMPARE_KEYS - COMPARE KEY FIELDS OF RECORDS
     ) COMPARE_KEYS
     ( SWAP_RECORDS - SWAP CONTENTS OF RECORDS IN FILE
     ( *BUFCOM   - COMMON DATA AREA FOR SORT BUFFER@)
     ) SWAP_RECORDS
     ) SORT
  
  When  displayed  by  the  "INFO"  command, this file would appear as
  follows: 
  
      SORT      - SORT RECORDS BY ALPHA KEY FIELD
      . *BUFCOM   - COMMON DATA AREA FOR SORT BUFFER
      . COMPARE_KEYS - COMPARE KEY FIELDS OF RECORDS
      . SWAP_RECORDS - SWAP CONTENTS OF RECORDS IN FILE
      . . *BUFCOM   - COMMON DATA AREA FOR SORT BUFFER
  
  Each nested branch is indicated by leading dots indenting  the  left
  margin.    The  number  of  leading  dots  designates  the  relative
  sub-level. 
  
       The module "BUFCOM" is a common data area, such  as  a  FORTRAN
  COMMON  BLOCK,  and is preceded by an asterisk (*) to distinguish it
  from modules containing procedural (executable) code. 
