xhelp hld

[twoducks <twoducks@globalserve.net>]

Here is a brief document I recently wrote concerning the xhelp
high level design. Any comments, corrections, additions, and or
abuse, are appreciated. Well. Not abuse.

The main reason of the document was so that new members of
SEUL or other projects could quickly understand the premises
being used in the creation of xhelp.

*********************************************
xhelp High Level Design

1.0 Introduction
-------------------------
  Every help system is composed of at least two
  components: the help documents and the browser
  which is used to view them. For example: manual
  pages have man and xman, html has html browser,
  text documents have many methods of viewing (vi,
  emacs, more, cat), postscript has ghostview ...

  The problem is that there are so many formats
  in use, and many more are being created all the
  time, that users are forced to have many different
  browsers for their help. There is no unified method
  of viewing help files. There is no unified method
  of searching help files. There is no easy way for
  a user to find the help they need quickly and
  easily, even if the documents do exist.

  A fully developed help system should address these
  problems, among others. The following document
  discusses one such system which is currently under
  development.

2.0 Design Goals
-----------------------
  2.1 Purpose statement.

    To develop a help system which provides a uniform
    interface to users no matter what document type they
    are browsing, and to provide a single source for
    viewing and searching for documentation.

  2.2 Component Interchangability

    A major design goal is to allow for various
    components of the help system to be interchanged
    with others, to allow for improvements in the
    software and to provide choise for the user in
    terms of needed functionality.

3.0 High Level Design
-----------------------
  3.1 Help system components
    Following is a brief description of the various
    components of the help system.

    o Help viewer components
        The help viewer is the element of the system
 that actualy loads and displays the help documents.

    o Search engine components
        The search engine reads through various
 documents and builds the database which is used
 to perform a document search.

    o Database components
        The database is the actual component that stores
 the search data. An interface is provided which
 allows for interchanging different databases
 while keeping the programs which access them
 the same.

    o Optional Components
        Several components may be provided which allow
 for easier access to help.

  3.2 Help viewer components

    o Help Viewer Interface
        This interface allows other programs to easily
 access the help viewer. If the help viewer
 itself is changed, the interface itself stays
 the same.

    o Document viewer frame
        The document viewer frame provides a common help
 viewer frame, independent of the actual format of
 the document being displayed.

    o Display module interface
        This is the interface the viewer frame uses to
 control the display modules.

    o Document display modules
        Display modules are provided to load and display
 the documents of a particular type.

  3.3 Search engine components

    o Search Interface
        The search interface allows programs to easily
 contol the loading and unloading of document
 data into the database by the search engine.

    o Main search engine
        This component controls the importing of pertinent
 data from the supplied documents and the
 placement of this data in a database.

    o Search module interface
        This interface is used so the main search engine
 can communicate with any of the various document
 formats.

    o Document search modules
        The search modules are the components which
 actually parse the documents of various formats
 to provide the data the main search engine
 places in the database.

  3.4 Database components

    o Database interface
        This interface is proided so that the search
 engine and querying programs may access any
 database that is provided for use with the
 help system.

    o Database implementations

  3.5 Optional components

    o Help browser
        This component allows for simpler browsing of help topics. It
 uses the file metaphor to allow the user to choose a successively
 more detailed topic until a document is actually chosen.

    o Search gui
        Uses the search interface to search the database for help
topics.