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-.tar.gz where 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= 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: