Enquire Manual - In HyperText

This is a HyperText rendition of Tim Berners-Lee's original ENQUIRE V 1.1 manual from October 1980, painstakingly copied out by hand from scans of the original manual. See additional notes at the bottom of this document.

[Later note: Thanks for the hard work in converting this, Sean. This is a copy of Sean's original translation. - TimBL]

EUROPEAN ORGANISATION FOR NUCLEAR RESEARCH









                                           October 1980





                          The ENQUIRE System
                          Short Description


                              T.J.Berners-Lee

   For the description of modular systems.

                                               Iss 1.1





     (text formatting by REPORT program)
                              Contents


1. Introduction                                                     1

2. Scope                                                            1

3. Modular Structure in General: Circles and Arrows                 2

4. Objectives                                                       3

   4.1. Documentation                                               3

   4.2. Analysis                                                    3

   4.3. Control                                                     3

   4.4. Reminder                                                    3

5. Using ENQUIRE-WITHIN                                             4

   5.1. Implementation under SINTRAN III                            4

   5.2. Display format                                              6

   5.3. Commands                                                    7

   5.4. Edit Mode                                                   8

   5.5. User Input                                                  8

   5.6. Languages                                                   9

   5.7. Possible extensions                                        10
                                 -1-




1. Introduction

    ENQUIRE is a method of documenting a system.   It concentrates  on
the  way the system  is composed  of parts,  and how these  parts  are
interrelated.

   This  information  about  a  system  is  difficult  to  store,  and
particularly  to update, using paper documents,  so ENQUIRE stores its
information on a computer.  The ENQUIRE-WITHIN program allows a person
to create and edit the data, so that others can later extract it as it
is relevant to them.

2. Scope

   The  ENQUIRE  system  is designed  to fill  a gap  in many  current
documentation  systems.    A person finding himself faced with a piece
"xxx" of a system should be able to ask ENQUIRE, for example

       What is xxx part of?

       What is xxx composed of?

       What must I alter if I change xxx?

       What facilities does xx use?

       Where do I find out more about xxx?

       Who or what produced xxx?

ENQUIRE does not aim to answer such questions as

       How does xxx work?

       What format is xxx in, exactly?

       Why was xxx created?

       What is the format of the interface between xxx and yyy?

The  answers   to  these  questions   are  normally  covered  by  the
descriptions  and specifications  of xxx.    ENQUIRE may be of use in
helping a user to find such documents, but it does not reckon to store
them.
                                 -2-




3. Modular Structure in general: Circles and Arrows

   The  assumption  is made  that  the system  to be described  can be
broken up into "modules".    It is generally  accepted  that this is a
necessity  for  any  modifyable   or  maintainable   system  involving
computers.   No assumptions are made about how the breaking up is done
-- ENQUIRE imposes no constraints on the high level design.

   A similar way of describing  a structure  is to draw, on a piece of
paper, circles with arrows in between.   The circles ("modules") could
be programs or pieces of hardware,  for instance, and the arrows could
mean "passes  data to", "is composed  of", or "is started  by".   This
method,  with  a variety  of different  shaped  boxes,  and  different
coloured  arrows,  is useful, clear, and commonly  used.   The ENQUIRE
system allows a more complicated system to be described than would fit
on a piece of paper.    It than allows an interactive  user to explore
the system in search of the information  he requires,  seeing only the
parts which are of interest.

   ENQUIRE  divides  both  the  modules  (circles)  and  relationships
(arrows) into broad categories.    This makes it easier to analyse the
structure  you end up with.   For instance the realtionships  "is part
of" and "includes" show the division of a module into smaller modules.
Also, when altering  one part of the system,  it is useful  to know by
which  other parts it is used.   These are generalised  reletionships,
just as Document, Program, Machine are generalised types of module.

   The modules may be all sorts of things.  They are referred to below
as  "nodes",  because  of  the  role  they  take  in  the  network  of
interrelationships within the system.
                                 - 3 -




4. Objectives



  4.1. Documentation

     The  primary  objective  of  ENQUIRE  is  to store  and  retreive
  information about the structure of a system.   This is done with the
  aid of the interactive ENQUIRE-WITHIN program.   As a side-effect to
  this, those people defining the structure  of a system using ENQUIRE
  may find themselves thinking about it, and with luck a proliferation
  of interdependancies may be avoided.
  
  4.2. Analysis
  
     As a second  stage,  the  data  produced  may  be interesting  to
  investigate.  This may show
  
      (a)  whether  the eventual  structure  of the system matches its
           design goals;

      (b)  when changes are required,  what sort of changes would make
           the system  cleaner  and more manageable,  rather than less
           so.

     Whether this form of analysis is useful is yet to be determined.

  4.3. Control

     When  a system  is expanding  rapidly,  some control  is normally
  required  over the way it is allowed to expand.   If rules are made,
  it may be that ENQUIRE provides  a way of checking  that these rules
  are adhered  to, and that  aspects  of the structure  have  not been
  introduced  which will degrade  the system  in the long term.   (The
  topic of project  control for complex systems is a large one, and is
  not discussed here).

  4.4 Reminder

     It must be emphasised  that the ENQUIRE system is not intended to
  replace  other  forms  of  documentation,  and  is designed  to work
  alongside other indexing systems and retrieval systems.
                                 - 4 -



5. Using ENQUIRE-WITHIN

   The following  is an outline of the facilities  available  from the
interactive editor.   Note that the program assumes a VDU with a speed
of at least 1200 baud which accepts the backspace character.

  5.1. Implementation under SINTRAN III

     The   ENQUIRE    program    is   currently    stored    on   file
  (GUEST)ENQUIRE-WITHIN:PROG  on the  PRDEV  computer  on the CERN  PS
  control system.  Log in to any of the interactive VDU terminals.  At
  SINTRAN III command level, type

         @(GUEST)ENQUIRE <params>

  and the system should respond

         Enquire V x.x
         Hello!

  The only  <param>  which  is acceptable  at present  (Oct 80) is the
  keyword  EDIT.    If this is present,  you will be allowed  to alter
  those  files  to which  you have write  access  under  the operating
  system.

     The  database  is stored  on various  "continuous"  files  called
  xxxxxxxxxxxx-V1:ENQR.    The 12 characters xxxxxxxxxxxx  include the
  user name under which the file is stored,  and part of the filename.
  Seperate  files  are used for storing  information  about  different
  parts  of systems,  but an object  in one file may freely  refer  to
  objects in other files.
                                      - 5 -



@ENQUIRE
Enquire V 1.1

Hello!
Opening file (PSK-PCP)VAC-V1:ENQR...

PSB Vacuum Control System                    (concept)  <   O>
--- ------ ------- ------

 [ 1] described-by: Enquiry System
      An experimental system fo which this is a test.

 [ 2] includes: Vacuum History System
      Records and displays slow changes in pressure.

 [ 3] includes: Vacuum equipment modules
      Perform all the hardware interface

 [ 4] includes: Control and status applications programs
      Provide operator interaction from the consoles.

 [ 5] described-by: Controle du System a Vide du Booster 11-2-80
      Operational specification of the software

 [ 6] includes: PSB Pump Surveillance System         PCP 228
      Allows rapid monitoring of pressure changes

[number      ]

Fig.1 (above) The PSB Vacuum Control node in the file (PSK-PCP)VAC-V1:ENQR. The [prompt] is shown on the last line. Fig.2 (below) shows a "circle and arrow" representation of the same information.
[figure 2]
                                      - 6 -



5.2. Display Format

   On entry into ENQUIRE,  and at various points during its use, the
user  is  presented  with  a page  much  like  fig  1.   This  gives
information  about one of the "nodes", and the relationship  between
it and other nodes.   The corresponding  circle and arrow diagram is
shown in fig.2.

Information displayed is as follows:

   For each node,

       1. Name:     Name of the node, filename if it represents a file
       2. Sort:     Category into which the thing described is placed
       3. Comment   Any further text considered relevant by the
                    last editor.

   For each related node,

       1. Number:   Allows one of the nodes refered to to be selected.
       2. Name:     The name of the related node.
       3. Relationship: Generalised relationship between the two
                    nodes.
       4. Comment:  A description of the node refered to. This
                    text describes the way it is relevant to the
                    node being listed.


   The following  "sorts" of node are currently  (Oct80) chosen from
the following set:

hardware     -   a piece of equipment
text-file    -   readable ASCII information stored on computer.
report-file  -   text information accessable by computer, best read
                 after being processed by the REPORT program.
code-file    -   information stored on computer, nto human-readable.
paper-docum. -   a human readable document not stored on computer.
concept      -   an abstract idea, anything without a physical form.
person       -   those strange unreliable beings on which all systems
                 eventually depend.

The type of relationship is currently one of the following set:

uses         }   Complementary. Reflect that one node relies on the
used-by      }            existence of the other.

includes     }   Complementary. One module is a sub-module to the
part-of      }            other.

made         }   Complementary. One module, program or person,
made-by      }            was responsible for the other.

describes    }   Complementary. Useful for linking documentation.
                                      - 7 -



described-by }            to that to which it is relevant.

background   }   Link different documents together
detail       }

similar-to   }   If none of the specific relationships above hold,
other        }            one of these is chosen.

5.3. Commands

   On entry, the user is in the outer command level of ENQUIRE.   He
is prompted  by two brackets,  and may insert a command word between
them.   The following  commands are available at this level to allow
interrogation of the data.   Commands marked * also allow alteration
of the data.

  1,2,3 etc.   Select one of the nodes refered to by this one.  Move
               on to that node, and display its relevant data.

     Retrace   Return to a previous node.  The user is prompted with
               a list of nodes previously encountered.    He selects
               one of them, by number.

        Mark   "Remember  this node".    The user marks  nodes which
               interest  him.   A list of up to 16 such marked nodes
               is maintained.    This list is displayed  after  each
               "mark" command.

      Unmark   The last node marked as interesting  is removed  from
               the list.

        List   List all the references and comment about this node.

        Quit   Leave the ENQUIRE program.

    Create *   Make a new enquiry data file.   The file must already
               exist  under  SINTRAN  III  as a continuous  file  of
               suitable size.

    Extend *   Add another node to this file.

      Edit *   Go into EDIT MODE,  to alter  information  about this
               mode.

      French   Load new vocabulary (See Section 5.6)

                  Note:  The commands marked * are only available if
               the user has write  access  to the file, and gave the
               EDIT parameter  when originally  invoking the ENQUIRE
               program.  (See Sect 5.1)
                                      - 8 -


5.4. Edit Mode

   Edit Mode allows the user to alter the details  about the current
node.   He is prompted for an edit mode sub-command  by a different,
distinctive prompt:

                         >> edit object [           ]
       or                >> edit reference [            ]  , etc.

The prompt shows what part of the data he is dealing with.   The set
of actions possible  in EDIT mode differ from those possible  at the
outer  command  level  (Section  5.3).   Some of these have the same
keywords  as those  at the outer command  level,  but should  not be
confused with them.

      create   Create a new reference,  from this node to one of the
               ones  marked  as interesting.    The user is prompted
               with a list of such nodes, and selects one.   He then
               supplies a few details about the node selected,  from
               the  particular  point  of  view  of the  node  he is
               editing.

        list   List the bit of data I am currently dealing with.

        edit   Edit the bit of data I am currently dealing with.

      extend   Add a new bit of comment  immediately  after this bit
               of data.  If there is already some comment tagged on,
               more may only be added to the end of last line.

               The following  sub-commands  affct which bit of data
               is to be dealt with next:

      object   Deal with the name of the node and its sort.

   reference   Deal with the next reference.

    comment    Deal with the next line of comment.

        quit   Leave edit mode, return to the outer command level of
               ENQUIRE.

5.5. User Input

   After giving a command  or sub-command,  the user may be prompted
for further imput.   The prompts should be self-explanatory.    When
entering any information,  the following  control characters  may be
used.

   Control/D   means "accept the line as it is currently displayed"

      Return   means "accept  the line  to the left of the cursor",
               unless the cursor is under the first character of the
                                      - 9 -


               line,  in which  case the meaning  is the same as for
               Control/D.

                  Answering   Return  to  a  question   immediately,
               therefore,  will  give  the  default  answer  if  one
               exists.  Also,

   Backspace   moves back (left) one character (also Control/H)

      Delete   means "delete last character" (also Control/A)

   Control/S   means "delete next character"

   Control/Q   means "delete line" (Also Control/U)

   Control/Y   means "move to begining of line"

   Control/B   means "move to end of line"

   When a keyword is required,

     a)  a default  keyword  is always  available,  if Control.D  is
         typed

     b)  entering  garbage will produce a list of keywords which are
         valid in context;

     c) UPPER and lower case letters are treated identically.

     d) Any abbreviation may be used which is unique in context.

   Commands,  sorts of node, types of relationship  are examples  of
keywords.

5.6. Languages

   The vocabulary  used by ENQUIRE,  and the keywords  it accepts as
input,  are loaded  from a special  file on disk.    It is therefore
possible  to alter  the language  the program  uses,  or the mood it
communicates  in.   This is only of limited  effect,  as the program
cannot,  unfortunately,   translate   the  entire  database  into  a
different language.

   To use a different  vocabulary,  use one of the allowed  langauge
names as a command at the outer level of ENQUIRE.
Example:
             [French      ]
             Bonjour!

             [Anglais     ]
             Hello!
(User input is between [brackets] )
                                      - 10 -


5.7. Possible extensions

   The  following  are extensions  which  could  be provided  to the
system:

   Sophisticated key searches of node names

   Automatic generation of index files from ENQUIRE data

   Automatic tracing of all dependant modules, component modules, or
required modules for any node;

   Various forms of hard-copy printout

   A file tidying  and garbage  collecting  facility  for shortening
files;

   Global editing  facilities  for making many related  changes to a
file or set of files.

Originals:-

What is ENQUIRE?

ENQUIRE was the first program that TimBL wrote that had any Web like qualities. It was one of the main inspirations behind the WWW. You can find out more about ENQUIRE from TimBLs book, Weaving The Web.

The name "ENQUIRE" comes from a book "Enquire Within Upon Everything" that TimBL read in his childhood. There is an etext of "Enquire Within Upon Everything" now available on the WWW (ironically).

Editors Notes

Any mistakes I made are my own. I tried as much as possible to maintain the formatting of the original. Apparently, the typesetting program used (called "REPORT") was written by Robert Cailliau, who later worked with TimBL on the WWW.

Copyright

Sean B. Palmer, Feburary/March 2001