Internal Document
=================

Herbert Melenk, Sep 29, 1993



Structure of REDUCE help system
===============================

A subdirectory $reduce/help contains all material and references
for the help system. Two formats are supported:

  H    the full help format: these are files which are
       generated from the REDUCE reference files;
       under UNIX these are kept in GNU info format;
       under DOS/Windows these are available in GNU info format
       and Windows Help format.

  B    bare Ascii files for browsing, using system services
       like MORE.

A directory file "helpdir.info"in $reduce/help links REDUCE packages 
to help data files. This directory has one entry per line in LISP item
syntax, e.g.:

h "REDUCE reference"            redref    "help/redref.info"
h "Groebner package"            groebner  "help/groebner.info"
b "Algebraic number package"    anum      "doc/anum.doc"
b "Source code Optimizer"       scope     "doc/scope.tex"

item 1:  type  h or b
item 2:  full package name (string)
item 3:  package id
item 4:  help file: string to be prefixed by "$reduce/" at run time.

For Windows a second directory file "helpdir" is maintained
which defines the pathes to the windows help files correspondingly
(under DOS the .HLP files must coexist with the .INF files).
 
Asking for help 
===============

Under XR or Windows the HELP button is used.

Under bare DOS or if REDUCE runs in an Xterm a REDUCE command
"help" is supported, with source in $reduce/help/help.red.

      help; 
   or help <package>;
   or help <topic>;
   or help <topic>,<package>;

If the graphical frontend (Windows, XR) does not organize the
data display directly, the following servers are invoked:

  UNIX:  
   if a help.rc file exists, this is loaded and the command
     in the variable help_command is executed by the function
     system with file name and (if given) topic appended.

   otherwise: we try to execute one of
      xinfo             (gnu info for X)
      info              (gnu info for standard terminal)
      $reduce/help/help (compiled from help.c in $reduce/help).

  DOS
   we execute $reduce/help/help.exe (compiled from help.c in $reduce/help).

Under DOS help.exe needs a VGA set and ANSI.SYS services. If
these are not available help.exe should be replaced by help0.exe
which has been compiled without these features.
      
Generating REDUCE help files from REDUCE reference files
========================================================

comphelp.red       compiling REDUCE help system, part 1:
                   syntax analysis, make structure, driver
                   for part 2

helpwin.red        write a help file in MS Windows help format.
                   This file is in RTF form and must be post processed
                   by the MS help compiler.

helpunx.red        write a help file in GNU INFO format.
                   This file has to be post processed by the
                   GNU info formatter.

                   The source information must have REDUCE
                   reference manual form, which is a LATEX subset;
                   \include and \input statements are allowed
                   for combining parts to a larger volume.

mkhelpw <pack>     script for running comphelp with helpwin
mkhelpu <pack>     script for running comphelp with helpunx
 
         <pack>:  name of the package for which a help file should
                  be generated. The input is expected as
                     packages/<pack>.tex

                  if omitted, the REDUCE reference help file is
                  processed, which is expected as
                     redref/redref.tex

mkhelpu.sed        auxilary file for mkhelpu

mkgnu              convert output of mkhelpu to final format

mkhelp.bat         compile output of mkhelpw by MS help compiler
                   (must run under DOS or NT).
mkhelp.dat         auxiliary file for mkhelp.

other files in the help system
==============================

help.c             simple interface to help files in GNU format

help.red           REDUCE driver for help information in non-
                   graphic environments.
