libhelp - a html based help system for osf/motif applications
-------------------------------------------------------------

    welcome to libhelp 1.8.1 (Jun 28. 95)

    this Readme details compilation steps  for libhelp.  more complete
    information  and documentation on libhelp is  available as part of
    the online  help system it implements.   see section "getting more
    help"  for getting more information.  this is  $Revision: 1.11 $ of
    the Readme file.

about
-----

    libhelp is a comprehensive hypertext-help-system for OSF/Motif(tm)
    applications which uses    the html widget  from   NCSA Mosaic(tm)
    version 2.4. the help  browser provides hypertext links, different
    fonts, inlined images  and a lot of more  elements  known from www
    (world wide web)     browsers.  it has  a   document   history and
    implements buffer and image cache methods.

    libhelp  provides  two interface functions   for  getting help and
    setting resources.  it eases  the task of writing  the application
    help. menu and context  sensitive   help are supported.   Lowlevel
    Motif and X stuff is hidden from the application developer (and of
    course the user too). libhelp works with (at least) ansi-c and c++
    applications.

    a  simple (but impressive)    standalone help browser `xmhelp'  is
    included in the libhelp distribution.

    an alternative implementation  for  the  libhelp interface  (named
    `libhlpclient')  provides     client-server help.  this    library
    transparently starts and controlls a help server (currently xmhelp
    or NCSA Mosaic(tm)) for the applications help requests.

contents
--------

    the libhelp distribution contains the following directories

    libhelp       - help browser library implementation
    libhlpclient  - library for client-server help
    xmhelp        - sample standalone help browser

    libButtFace   - the Button Face library 1.0 by Harald Albrecht
    libXpm        - the X pixmap library by Arnaud Le Hors.
    libhtmlw      - the html widget library from NCSA Mosaic(tm) 2.4

    help          - the online help documents and images for libhelp
    pixmaps       - pixmaps used for colored buttons and the icon. 
    emacs         - example emacs lisp code concerning html. 

    and files:

    History Readme Imakefile Licence 
    
copyright
---------

    copyright (c) 1995 ipvr stuttgart and thomas harrer.

    ipvr = institute of parallel and distributed high-performace
    systems. university of stuttgart.

    libhelp  needs  3 libraries  (which are shipped  with  the libhelp
    distribution: the HTML widget library,  the ButtonFace library and
    the Xpm library).    see  the file  "Licence" for    licencing and
    copyright details for them.

    If you use libhelp and like it, please send a  postcard to us. See
    the online documentation for the postcard address.

source
------

    future versions of libhelp can be obtained by anonymous ftp from  

      ftp.informatik.uni-stuttgart.de:/pub/libhelp/libhelp-<ver>.tar.gz

    where <ver> denotes the version number. 

    note: libhelp  will be officially released  in august 95. if there
    is nothing on ftp.informatik.uni-stuttgart.de write me for a copy.
    	
platforms
---------

    libhelp   is  known  to   compile on  the  following  platforms  (in
    alphabetical order):

	hp    (hp/ux A.09.03 A 9000/730 with c89, x11r5 and motif 1.2)
	ibm   (aix 3.2.5 with cc, ibm x11r5 and motif-1.2).
	pc    (linux 1.x with gcc, x11r5 and motif-1.2).
	sgi   (irix 5.1.x).
	sun 4 (sunos 4.1.x with gcc, x11r5 and motif 1.2).
	sun 5 (solaris 1.2 with gcc, x11r5 and motif 1.2).

compilation instructions
------------------------

    libhelp sources  are written in ansi-c.   you  will need a working
    ansi-c compiler (e. g.   gcc) to compile libhelp. libhelp requires
    x11 and osf/motif(tm). we use x11r5 and motif-1.2.  we don't know,
    if it compiles with x11r4 and motif-1.1, but there will be a great
    chance that it will.

    in order to compile  libhelp and the standalone helpbrowser xmhelp
    you will need a  working imake.  the  global Imakefile defines the
    variable LIBDIRS to 'libhelp libButtFace  libhtmlw'.  if you don't
    have the xpm library (version 3.4) you will need  to add libXpm to
    LIBDIRS to use the xpm library that is shipped with libhelp.

    to build libhelp, type:

	xmkmf
        make Makefiles
	make 
    
    if you want to use a different compiler than gcc type 

	make CC=<compiler>

    in the last step.

    you can add additional include dirs in INCS, optimisation flags in
    COPT, additional  libraries  for  your host   in  LIBS  and  other
    makefile definitions in DEFS. for example

	make CC=cc LIBS='-lbsd -lregexp' INCS='-I/usr/bsdinclude' \
             COPT='-g' DEFS='-DDEBUG -Wall'

    you can hardcode the search path for helpfiles and images with the
    preprocession macro HELP_PATH. per default, it is set to

	"/usr/local/help:../help:help:../images:images:."

    but you can compile in your local help directories, for example

	make DEFS='-DHELP_PATH=\"/usr/help:/usr/images\"'

    if  you want `/usr/help'  and `/usr/images'  be  searched for help
    files and images. at runtime, you can add entries to the help path
    via the environment variable LIBHELPPATH.

    supposed there are no compilation  errors this results in a single
    executable   file    xmhelp/xmhelp    and   the    library   files
    libhelp/libhelp.a,  libButtFace/libButtFace.a  libhtmlw/libhtmlw.a
    and if choosen libXpm/libXpm.a.

    to link libhelp to other applications you  should include the file
    libhelp/help.h into   the  sources. link   the libraries  in   the
    following order:

	-lhelp -lButtface -lXpm -lXm -lXmu -lXt -lX11 ...

    if  you don't want   the help browser to  be   linked in, you  can
    alternatively use the libhlpclient  library. for more information,
    see the Readme file in the libhlpclient directory.

minimum installation
--------------------

    in order to have the right icons in the history page, you'll need
    to copy at least the images

	icon-history.gif icon-index.gif libhelp-bar.gif

    from the help/ directory to a place pointed by the LIBHELPPATH (or
    internal HELP_PATH). To use  the libhelp documentation as part  of
    your help system, you need  to copy all files  ending in .html and
    .gif to such a directory. 

    additionally, you can place libhelp.a and help.h in a global place
    where compiler and linker will find them. On my systems, libhelp.a
    is  in /usr/local/lib, help.h   is in /usr/local/include. Also you
    you   might  want to   move  xmhelp to a   directory  in your PATH
    (necessary for using xmhelp as help server).

    i use libhelp as a shared  library. for example, my xmhelp browser
    is just about 10 kbytes. if you try to create shared libraries for
    your system,   please send me  information   about it. it   may be
    distributed in further releases.

X default resources
-------------------

    `xmhelp'  includes a  set of fallback   X  resources that  provide
    reasonable screen display properties for color displays.

    the   default resource class   name  for  the  libhelp library  is
    `Libhelp'.   your application  can  override this  class name by a
    interface funtion    (e.g.  giving it  the  class  name   of  your
    application).

getting more help
-----------------

    libhelp provides a  comprehensive help system. it  offers a set of
    example help files and  images documenting itself. the  help texts
    are written in the html  (hypertext markup language) language.  

    the  libhelp-index.html document is  designed  to be added to your
    application as a "help for help" entry. feel free  to add the help
    documents to  your application. (or  contribute if you have better
    ones (e.g. more elaborate english).

    if you  have built libhelp   successfully you can view the  online
    help  files  with the  standalone browser  `xmhelp'.  probably you
    need to set the environment  variable LIBHELPPATH to the directory
    "help" in the libhelp distribution.

    at any   time (before you've  compiled libhelp  or if  it  was not
    possible  to do so) you can  view the online  help  any www client
    which can  display html files e.g. NCSA  Mosaic(tm). change to the
    directory "help/" and start your www client on the index file

	libhelp-index.html.

bug reports and comments
------------------------

    bug reports and other comments can be sent to 
	
	mache@informatik.uni-stuttgart.de

    if you  find libhelp useful   or particularly interesting,  please
    also send  us  a note.  user  feedback can  be very important  for
    further support and developement of libhelp.

--------------
    cheers,

        thomas harrer
    	Thomas.Harrer@rus.uni-stuttgart.de

--- i love gnu emacs: -----------------------------------------
--  local variables:	
--  mode:		text
--  tab-stop-list:	(4 8 12)
--  fill-prefix:	"    "
--  End:


