Trailing-Edge - PDP-10 Archives - decuslib10-11 - 43,50535/phi.phi
There are no other files named phi.phi in the archive.
0.PHI - Program for Hierarchical Information~
1.Brief description for beginners~
2.Purpose of program^
  PHI is a program which provides a means of setting up hierarchically
organised files, examining them online, and printing them out (either
in their entirety or as selected sections).
  This 'brief description for beginners' only describes the use of PHI
in the 'PHI documentation system' (i.e. for getting help on system
features and programs). You can also quite easily set up your own
documentation files - for details see the section 'full details
of program'.
  On-line interrogation using PHI is done by selection of sub-sections
from a multi-level structure, enabling the required information to be
speedily found. It is also possible to search for the occurence
of a specified string of characters throughout the text.
  The program outputs messages to guide the user and so can
be used to examine existing PHI type documentation files without
any previous knowledge of the program.~
2.How to use the 'PHI documentation system'^
The 'PHI documentation system' is designed to enable users to obtain information
on various system features, programs etc.
To run the system type one of the following monitor command lines:

.PHI		This command is best for 'browsing' through available
  information. Just follow the instructions typed by the program.

.PHI <name>	will type info about the subject <name> (if available)

.PHI'<string>   where <string> is a string of characters. Titles in the
  system will be searched until one is found which contains the
  specified string. Thus you do not have to know the exact subject name.
     e.g. .PHI'EDIT       for information on editors

To get a lineprinter listing of a subject run PHI as described above,
then when you have got to the subject you want, type the command line
(the O gets you to the top of the subject if not already there, the P/LPT
prints the entire subject to the lineprinter).~
2.Basic concepts^
A 'subject' is stored on one file, and consists of one or more
sections arranged in a hierarchical 'tree' structure.
There is one top-level section , all other sections being descendants of
it. (The tree is an upside down tree, i.e. the root is at the top and the
branches hang down!)
Each section has a title and (usually) text associated with it.
Subjects may be linked together to form a 'tree' of subjects - this
is how the 'PHI documentation system' works.
When PHI is run, if a subject name has been specified, you will go
in at the top of that subject. If just 'PHI' was typed however, you
will go in at the top of the documentation system and can then move
down to any of the other subjects.
Once in a subject you can move around from section to section, listing
the text in sections as desired. You can also move back up the tree
to higher level subjects, but can never move above the point at which
you 'came in'.~
2.The most commonly used commands^
PHI will type a  *  on the terminal as a prompt when it expects
you to type in a command.
The most important commands you need to start with are listed below.
(The words in brackets after each command letter are just an aid to
memory - only the single command letter should be typed).

(1) Commands to move from one section to another:
  * O (Origin) - gets back up to the top of the subject
  * n - where n is a number, gets you to the n'th sub-section of
    the current section
  * U (Up) - gets you up to the next highest section, i.e. the
    section which 'contains' the current sub-section.
  * R (Restart) - gets you back to where you came in. (If you
    are still in the same subject then this command has the same
    effect as the 'O' command.

(2) Commands to type out to the TTY (or print to lineprinter):
  * Pressing 'RETURN' causes the title and text for the current
    section to be typed out, together with a list of the titles of
    all sub-sections (the immediate descendants of the current
  * Pressing the 'ESCAPE' (sometimes called 'ALTMODE') key has the
    same effect except that text for the current section is not typed.
  * L (List) - prints out the title of the current section
    together with the titles of all its sub-sections. Thus if
    this is done when at the top level, a complete list of the
    contents of the subject is produced. (L/LPT prints to the
  * P (Print) - prints the current section and all of its
    descendant sections. Thus if this is done at the top level the
    whole subject will be printed. (P/LPT prints to line-printer).

(3) Search commands:
  * 'string    where string is a string of characters, searches until
    it finds a section whose title contains the string specified.
    e.g. 'FRED  searches for a section which has 'FRED' in the title.
  * Fstring  is the same as above except that the text is searched
    as well as the titles.
    e.g. FFRED   searches for 'FRED' in titles and text.

You can always suppress output from the program by typing the CTRL/O
character, after which the program will be ready for the next command.
(Sometimes if you do this, the 'prompt' asterisk may not appear -
if nothing appears to happen after a couple of seconds, just press
linefeed to get the 'prompt', then the program will be ready for the
next command).

Commands may follow the subject name on the PHI monitor command line, e.g.
   to see if there is any news on PASCAL.

If you are looking at this section online and would like a lineprinter
copy for reference, type   P/LPT   when the asterisk appears.~
2.Hints on using the commands^
 (i) To re-type the section you have just been looking at, press RETURN.
 (ii) If you have just looked at, say, subsection 5 and then want to
      look at subsection 3, type U3. (The U gets you back up a level,
      then the 3 gets you down to subsection 3).
 (iii) Suppose you want to type out all the information on the PHI file
      for a given subject. Run PHI for that subject, then type the 'P'
      command. This command can also be used when you are positioned at
      any particular section, to type out that section and all its
1.Full details of program~
2.General notes and nomenclature^
Users are recommended to read the section 'basic concepts' before
reading about the details of the program.
Sections in a tree are also referred to sometimes in this documentation
as 'nodes'. The top level section in a subject is sometimes referred to
as the 'root node'.
Subjects are linked when an 'indirect file specification' appears
instead of text in one of the sections for a subject. Then when you
move to that section, the subject file specified will be read in
(except in modification mode).
The top level file in the 'PHI documentation system' has subject name
'0' and contains 'indirect file specifications' to all the other subjects.~
2.How to run PHI - the 'PHI' monitor command^
(i) To run the 'PHI documentation system':

    Type   PHI   (at monitor level) to get in at the top of the documentation
    system. You can then 'browse' around all the available information.

    Type  PHI <subject>     to examine a specified subject (if
    available),    e.g. PHI TECO
    Note that if there is no .PHI file with the specified subject name,
    the program will look for a .HLP file with that name.
    Any initial commands may follow the subject specification on the
    same line (if command starts with a letter or digit a blank should
    follow the subject name).

    PHI'<string>    where <string> is a string of characters will
    search through titles in the top level documentation file (the '0' subject
    described above) until it finds a title which contains that
    string. (What is really happening is that we are running PHI
    without a subject name, then giving it an initial command
    which is the search command '<string> ).
    e.g. PHI'EDIT   to find information on editors.

    PHI *   gives you a list of subjects which are in .PHI form
    (i.e. divided into sections).

(ii) To use PHI to examine a file you (or some other user) has
     set up:
     Type  PHI <subject>         e.g. PHI FRED
        <subject> may optionally be  followed by [path]  specification,
        and may optionally be preceeded by a device name to specify
        a disk, e.g. DSKB:
      - see the section 'Input and Output files' for full details.

(iii) To set up a personal subject file:
     Type   PHI <subject>/M        e.g. PHI JOE/M~
2.Commands to examine .PHI files~
If the tree has only one section, then after printing it PHI will
return to monitor level (unless /M has been specified), however
if there is more than one section, then PHI will print an asterisk
indicating that it is ready for a command.
Most commands are single letters, some have arguments.
Blanks and dots between commands are ignored.
Lower case letters are converted to upper case.
Usually any number of commands can appear on a line except that after
P, L or C commands the rest of the line is ignored (and any commands
typed ahead). Commands need not be separated by blanks except that if
two consecutive commands are numbers, a blank (or dot) is required to
separate them.

The asterisk character is used to prompt for further commands. 
Output from a command can always be suppressed by typing CTRL/O,
after which the program will be ready to accept the next command.
(Occasionally the 'prompt' will not be printed after doing a CTRL/O,
if this happens just press ESCAPE or linefeed to get the 'prompt').~
3.Miscellaneous commands^
  H - Help, prints list of available commands with one line description.
      Any further commands on the same line will be ignored.
  ? - "where am I?"
      Lets you know where you are in the tree by printing the
      titles of sections which are ancestors of the current section.
      It also prints the titles of sections which are just before and
      just after the current section, on the same level.
      It prints the commands (O, U, B, N) which are required  to reach
      these sections.
  E - Exit from program. Note that if edits have been done and the edited
         tree and text is to be saved, it will be necessary to type WE.~
3.Print commands^
Note that the switch setting commands /U, /I, /S, and /P can
be used to control the various printing options.
When 'paging' is in effect (it is on by default for VDU's - see the /P switch)
and a screenful of information has been typed, the program pauses and
prints a message. If you want to continue the listing type a blank.
Otherwise to abandon the listing type 'return' or type in any command
(followed if necessary by [CRLF] or [ESC]).

'RETURN' - pressing RETURN causes the title and text of the current
      section to be typed out, together with a list of the titles of any
      immediate descendant sections.
      (However, the RETURN pressed at the end of a line ending with a P, L
      or C command or a switch setting command, does not cause any type-out).
'ESC' - pressing 'ESCAPE' (or 'ALTMODE') has the same effect as 'RETURN'
      except that the text for the current section is not typed.
  P - Print, prints the current section and its descendant sections. 
      The form of the output depends on the settings of the T (Text) and
      S (Separation) switches, (described in the section "switch setting
      When text is being printed on the TTY or VDU the program splits
      any line which goes beyond column 73, at the next space character
      and continues on the next line (indented an appropriate ammount).
  P/DSK - as P but sends the printout to a .LST file on disc.
      This will overwrite anything already there, unless P/DSK/ADD
      is specified in which case it will be appended to any existing
      information. Note however that the filename is the subject name,
      so that different subjects write to different files.
  P/LPT - as P but sends the printout to the line printer (each successive
      P/LPT produces a separate line printer output)
  L - List, prints a list of the titles of the current section and
      all its descendant sections.
      This command can be used to get a summary of the whole file, and
      to produce a listing of a 'contents page'.
  L/DSK, L/LPT - have the same relation to L as P/DSK, P/LPT have to P.
  C - Current, prints title and text of current node.~
3.Move commands (number, O, R, U, N, B, J, +)^
These are commands to move around in the data tree. 
The section we are currently positioned at is called the 'current
section' (or 'current node').
It will initially be the top level section (or 'root node').

  n, where n is a number, moves to the n'th immediate descendant 
     of the current section.
     Note that since dots are ignored between commands, it is valid to
     type e.g. O2.5.3 to get to section 2.5.3 (regardless of where you
     are currently positioned).
  O (or 0) (Origin) - move to the top of the current subject
  R (Restart) - move to the top of the tree (i.e. where you came in).
     If you are still in the same subject as when you came in, this command
     will have the same effect as the 'O' command.
  U - Up to ancestor section
  N - Next, move to next section with same ancestor as current section
  B - Back, move back to previous section with same ancestor as
      current section.
  J (Jump up) - go to the top of the subject which is the ancestor of the
      current subject.
  + - Move to next section in tree. (The order of sections for this purpose
      is the order in which they would be printed in a P command).
      (If the next section contains an indirect file specification,
      the file specified is read in and you will be positioned at
      the top level section).~
3.Search commands (', F, G', GF)^
   '<string>   - start local search in titles:
      search for a section, within the current subject,  whose title
      contains the string specified.
      e.g. 'switch finds a section whoses title contains the string

   F<string>   - start local search in titles and text:
     this command is the same as '<string> except that the text
      is searched as well as the titles in trying to find a match,
      e.g. Fswitch

   G'<string>    - start global search in titles
     this is the same as '<string> except that a global search is
     done, i.e. it also looks through any subjects which are linked
     to the current one by indirect file specifications.

   GF<string>    - start global search in titles and text.

   '    - resume search (local or global), looking in titles
   F    - resume search (local or global), looking in titles and text

Further notes:
   (i)   If you are currently at the top of the tree, the whole tree will
      be searched until the section is found.
      If the command is used at a section which is not at the top of
      the tree, only that section and its sub-sections will be searched.
      (In this case resuming the search by just typing the single quote
      without the string will also only search within these sub-sections).
   (ii) When a section is found the title of the section is printed
       and you will be asked whether or not this is the section you want.
       If you type Y you will then be positioned in this section, otherwise
      the search will continue.
   (iii) whenever you resume a search it continues from where it last
      left off, even if you have moved your position in the meantime.
      Resuming a search after you get the message 'cant find <string>'
      causes it to start again at the section where you first started
      the search.
   (iv) The [CRLF] or [ESC] after the command is taken as the next
      command, i.e. causing the title and/or text to be printed in the
      normal way.
   (v)   Note that since commands can directly follow the subject name
      when the program is first entered, you can jump straight into
      any section by following the subject name with a 'string.
      e.g. if you want to look at the section in the PHI documentation
      about switch setting commands, you can type 
        PHI PHI'SWITCH  at monitor level.
   (vi) Whether a letter is upper or lower case is ignored when matching
      strings so upper case 'SWITCH' would match lower case 'switch'
      and vice versa.~
3.Switch changing and value setting commands^
(These switches may also appear directly after the subject specification
or directly after the word 'PHI' on the PHI command line, e.g.
4./G user guidance^
  /G - Guide user, changes a switch (initially on) to control
      user-guidance messages. These are messages that are
      printed after each verification (i.e. after section is printed
      in response to a [CRLF] or [ESC]) to tell the user what to
      do next.~
4./B bell in pause message^
/B - change a switch which determines the form of the 'pause' message (the
     message which comes after a screenful of information has been typed,
     when paging is on). The message will either be short without bell,
     or longer with bell (the default).~
4./S separation values for printing^
  /S - Separation, sets the separation of nodes on the printout.
      /Sa.b where a & b are integers greater than or equal to 0,
      sets the separation such that nodes of level less than or
      equal to 'a' will be preceeded by a formfeed. Note that
      the current node is regarded as having level number 0, its
      immediate descendants level number 1, etc.
      (Note however that if a section is printed which has no text,
      and the next section is an immediate descendant and would
      normally be preceeded by a formfeed, the formfeed will be
      suppressed and b+1 blank lines printed instead.)
      b is the number of linefeeds to be printed before each node
      of level a+1. Nodes of each subsequent higher level number
      (further down tree) will have one less linefeed, until no
      /S on its own just prints the current values.
      The default setting is /S1.2.
      Note that when printing to the TTY the values assumed are
      effectively /S0.b (i.e. no formfeeds are generated).~
4./I indentation^
  /I - Sets the indentation factor (initially 3) for printing.
     e.g. /I5 means that text is indented by 5 columns per level.
     /I0 means no indentation
     /I on its own just prints the current value.
     Note that when printing to the TTY (in P and L commands) no
     indentation is done (instead an extra blank line is printed just
     after the title).~
4./U title underlining^
  /U -  changes a switch (initially on) which causes titles to be
      underlined in a P command.~
4./H help on switch commands^
Prints a list of all switch changing and value setting commands
on the TTY.~
4./P page size^
/P<n>   where <n> is a number, defines number of lines on VDU screen.
     After printing this number of lines, PHI pauses and asks whether
     you want to continue or abandon the listing.
     The default value is /P22 for terminal types VDU and 7009.
     The default value for TTY's is /P0 which means paging is not in effect;
     note however that the system may not know that you are on a TTY unless
     you have typed the monitor command 'SET TTY TYPE TTY'.
/P   on its own types the current value.
/P0  means no limit, so paging will not be in effect.
/PL<n>  where <n> is a number, defines the page size for printing to
     LPT or DSK (in P or L command). A page throw will be generated
     after each page is printed.
     The default is /PL60.
/PL  on its own types the current value.
/PL0 means no limit (so no page throws).
(/PT is equivalent to /P).~
4./M switch on modification mode^
  /M - switches on modification mode (always switches on, never off).
      File updating comands only appear in the 'HELP' listing
      when modification mode is on.~
2.Creating and updating hierarchical files~
When creating a new subject file, the switch /M should be specified after
the subject name (and path if any)
   e.g.  .PHI FRED[,,SFD]/M
(or after 'PHI' on the command line, e.g.  .PHI/M FRED[,,SFD] )

The /M switch can also be specified when updating a file, but if it is
ommitted then the use of the /M command at any subsequent time
will have the same effect as if it had been specified, i.e. will
switch on "modification mode". File updating commands only appear in
the "Help" listing when modification mode is switched on.

To define title and text for a section use the "M" command.
To create a new sub-section use the "X" command.
User guidance messages from the program for the above two commands should
be self explanatory, but the commands are also described below.

There is also an "A" command which can be used to create several sub-sections
at once (i.e. define a sub-tree), but this is rather more difficult to
understand how to use. Usually the only time you will need to use the
"A" command is to re-insert a node which has been 'yanked' out of another
place using the "Y" command.

When typing in text for a section don't start any words after column 72
because when PHI is used to print the text at the terminal, lines will
be split at the first space character after column 72.
It is advisable not to use tab characters, as the indentation produced
when doing a P command may not be that which was intended.

Remember that no data is written to disk until a "W" command is done.
3.File updating commands (W, M, M/, DN, DT, X, Y, A)^
  W - write the .PHI file.
      (Any existing .PHI file will be renamed to .QHI)
      It is advisable to do this at regular intervals if doing a lot of
      updating in case the system crashes.
  M - "Modify". Defines title and text for current section. The program
      prompts separately for title and text. If just an ESC is typed,
      no change is made (useful if you type "M" by mistake).
  M/ - Edit the text for the current section - see "text editing".
  DN - Delete current section. Its descendant tree is brought
      up a level to be where the deleted section was.
  DT - Delete Tree, deletes the current section AND its descendant tree.
  X - Add an eXtra sub-section as an immediate descendant of the current
      If the current section already has sub-sections, the program
      will ask where you want to insert the new sub-section: type 0 for
      insertion before all the other sub-sections, a number, n, for
      insertion after the n'th sub-section, or press return for insertion
      after all the other sub-sections.
      The program prompts for title and text separately.
  Y - The Y command provides a way of changing the tree structure by
      moving sub-trees around in the tree. The Y command 'yanks' the
      current section out of the tree and stores it for later insertion.
      The yanked section (together with its entire descendant tree) can
      later be inserted at any desired position in the tree using
      the # (hash) symbol in the 'A' command.
      There can only be one yanked section in existence at any one time
      and if it is not re-inserted in the tree before exiting from the
      program it will be lost.
  A - Add a new sub-tree to the existing tree as a descendant of the
      current section. Useful when setting up a tree structure when
      there is not much text to be defined at this stage for each node,
      or when re-inserting a 'yanked' node.
      For details see under "adding new sub-trees".
3.Adding new sub-trees (The "A" command - not commonly used)~
4.Description of the "A" command^
The "A" command adds a new sub-tree as an immediate descendant of the
current node. The program asks where you want to insert it:
type 0, n or press return, as for the "X" command.

The tree specification then follows, starting on the next line:
 (optional items are shown in square brackets thus - [...] )

            tree spec
          where tree spec is:
            node[(tree spec)], node[(tree spec)], ....
          where node is:

note that if text is included it must be prefixed
by the circumflex character to separate it from the title;
it is usually best to follow the circumflex character
immediately by a [CRLF] so that text starts on a new line.
(The title and text may be of any length).
To specify an empty node, the quoted string can be ommitted,
 e.g.  "Fred",,(,"Joe")   defines 5 nodes of which 3 are empty.

Any number of blanks, [CRLF] or tab characters may appear
BEFORE a title/text specification in order to make the
input clearer.

Insertion of a "yanked node":
If title/text is replaced by the # (hash) symbol, the 'yanked node'
will be used at this point (see under Y command) - note that
once it has been inserted it no longer exists as a yanked node
and so cannot be inserted at another point in the tree.~
4.Example of the "A" command^
Suppose the current node has title "Animals" and that this
node has a single immediate descendant with title "Fish".
We want to add two further descendants with titles
"Wild" and "Domestic" after "Fish".
The commands to do this could be:
   "Wild"( "Lions", "Tigers", "Zebras"),
   "Domestic"( "Cats^
   woof woof")

If a P command is now done to display the descendant tree of the
current node we will now obtain the following output:

                3 Animals

                   3.1 Fish

                   3.2 Wild
                      3.2.1 Lions
                      3.2.2 Tigers
                      3.2.3 Zebras

                   3.3 Domestic
                      3.3.1 Cats
                      3.3.2 Dogs
                         woof woof

        (The node numbers are generated by the program).~
3.Text editing (The M/ command)^
The M/ command causes the program to enter text editing mode.~
Single letter or character commands are entered and these are
NOT echoed.
This facility is similar to the A command in SOS but the commands are
not identical and the same command may have different effects
in each so care must be taken.

The characters carriage return (CR) and linefeed (LF) in the text are
treated just as ordinary characters and so may be deleted and inserted.
This must be borne in mind when using the blank,D, or I commands.

Note that the "circumflex" character "^" is used by PHI to separate the
title of a section from its text. When editing with the M/ command, these
are just treated as ordinary characters. (Note that this character cannot
therefore appear within a title, but it can appear in the text).
The "tilde" character (ASCII value 176 octal)
must never be used in titles or text as it is used by PHI to separate
sections from each other in the text file. (This character follows
directly after the last character in the section, there is no need for
a CRLF before it).

Commands which are not recognised cause a bell character (as does typing
certain commands at the end of text).

A repeat count may preceed the blank, D, [CRLF], and E commands.(before
any other commands it will be ignored). e.g. 5D to delete 5 chars.
After a [CRLF], [LF] or E command (or one of these preceeded by a repeat
count) the next line in the text will be printed.~
        blank - copy a single character and print it on the terminal.
        D - delete a single character.
        backspace (or rubout or CTRL/H) - erase the last character
        written to the output string. (Multiple backspaces will
        erase successive characters).
        [LF] (linefeed)  - copy up to and including the next LF.
        [CRLF] (carriage return,linefeed) - as [LF] but characters are 
                printed as they are copied across.
        E - delete up to and including the next LF.
        Z - copy up to the end of text.
        I.....[ESC] - insert the specified characters at the current point.
           During the insertion the backspace or rubout keys can be used in
           the normal way to delete characters wrongly typed, and the 
           CTRL/U to delete a whole line wrongly typed.
        Q - abandon the edit.
        * - end the edit. Note that the output string will be terminated
                at the current point, so usually it will be necessary to
                type Z* to finish editing.~
3.Editing of .PHI files using SOS or TECO^
The text in a .PHI file can be edited using SOS or TECO. When doing
so you should be careful not to alter any of the level numbers or
special characters which terminate titles and text (see below),
unless you want to change the structure of the tree.
(There are also editing facilities available within PHI, by using the
M/ command. See the full documentation for details).
If you understand the structure of a .PHI file (described below) you
can also create .PHI files using SOS or TECO.

The .PHI file consists of the title and text for each section in the
order in which sections would be printed in a P command. (i.e. a section
is always directly followed by all of its descendant sections). The top
level section is always first and is regarded as level 0, its immediate
descendants as level 1, and so on down the tree.
For an example type out any of the .PHI files on the DOC: area.

Each section starts on a new line and has the following form:

where n is the section level number and, <tilde> is the tilde character,
ASCII value 176 octal, sometimes also known as the 'twiddle' character.
(This character is not available on some of the older teletypes, if you
are using such a teletype you will have to use TECO to insert the character
by giving its ASCII numeric value).

Blank lines and formfeeds (and any other control characters) are allowed
between sections (but will not be preserved when the file is written out
using the W command).

If there is no text for a section, it could have the form:
3.Indirect file specifications ('linked subjects')^
Each subject for PHI consists of a 'tree' of sections arranged in a
hierarchical form. Each subject is stored on a separate file.
It is possible to link subject files together into an overall tree
structure - any section (which does not have any sub-sections) can have
a pointer to another subject file instead of text.
This means that when moving through a subject file, if you move to a
section with such a pointer (also known as a 'virtual node'), the file
specified will be read in (unless in modification mode), and you may then
move around that subject.
Note however that a P command does not cause linked subjects to be read
in, instead the indirect file specification is printed just as it stands.

To set up a reference to another file from a section, the text for the section
should consist only of
e.g.   @DSKB:FRED.JOE[12345,6]
If the file extension is ommitted, .PHI is assumed. Other defaults and rules
are the same as if specifying a subject to PHI initially.
Note that a section containing an indirect file specification may not have
any descendants. Note also that the top level section (root node) may not
have an indirect file specification.

There is an on-line documentation system based on PHI which uses
this facility. This system is based on the file DOC:0.PHI which has links
to all .PHI and HELP files. The system enables the user to go in at the
top of the whole tree and work his way down to the information required
by selecting sub-sections in the usual way, thus making it much easier to
find information on a required topic without having to know the subject
It is also possible to do a 'global search' which looks for the
occurence of a specified string throughout the whole tree (i.e. through
all the subject files).
It is also possible to enter the system at any desired subject if required.~
3.Converting existing documentation to PHI form^
Existing documentation which is stored as a file on the computer can be
converted for use with the PHI program. This should only be done after
some familiarity has been gained with the use of the program.
The section 'Editing of .PHI files using SOS or TECO' should be read.
The method is as follows:

  (i) Looking at the documentation, decide the structure of it (in terms
        of sections and sub-sections etc.)
  (ii) Edit the documentation file to include the circumflex characters
        to divide titles from text, the tilde characters to end
        each section and the level numbers.
        The root node will be the first one on the file.
        Even if there is no title or text for a section, the tilde
        character must still be present.
  (iii) Convert tabs to spaces using COPY/W.~
2.Specifying input and output files - further details^
The data for a subject x is stored in a file x.PHI.

   (1) Input files:
If 'PHI x' is typed, where x is a subject name,
PHI will search for file x.PHI on the user's area
(in the current SFD if not at the top level). 
If the file is not found, then if the /M switch has been
specified, PHI assumes that this is a new subject name for which
a tree is being set up, otherwise PHI searches the default area DOC:.
If still not found it then searches the HLP: area - if it finds
such a file (HLP:subject.HLP) it will be read in and treated as a
single section file.

   If subject name is followed by a ppn/path specification,
or preceeded by a device name, the input file will be read from
the area specified.
If not found, and the /M switch has been specified, then PHI
assumes it is a new subject, otherwise an error message will

         ABC[123456,2]  reads the file for subject ABC from area
         DSKC:ABC[123456,2,FRED,JOE]  specifies the disk and SFD
                where the file is to be found.
         ABC[,,ALFRED]  reads the file from the user's own area, in
                        the SFD called ALFRED.
         ABC[]   reads the file from the top level of the users's own
         DOC:ABC  forces it to read from the DOC area (useful if you
                 have a file of the same name on your area as one
                 on the DOC area).
   The closing square bracket of the path specification can be ommitted
   if there is nothing else following on the line.

   (2) Output files:
If the W command is used, the data will be written to a file x.PHI.
If this file already exists it will be renamed
x.QHI (just as in SOS).
Note that the data is not  written to disc unless the W command
is used.
Printout directed to disc will be on the file x.LST on the user's area
(in the current path).
   If no ppn/path had been specified after the subject name, the W
command will write to the user's own area, and the current path.
If a ppn/path had been specified however, the program will write
to the ppn/path specified (though if the ppn is not the user's
own this will usually give a protection failure).~