~4Dgifts/toolbox/utilities/sgihelp_dev README
the SGI Help Developer's Kit
changes to v4.2 sgihelp_dev:
1) now shipping fulltext.pv print stylesheet so user's can print from help
2) fixed a bug in libhelpmsg.a so heavily loaded CPU's can contact the
help server
3) removal of iivBroker.h and libiivmsg.a - obsolete tools never used
4) bug fixes in XHELP stylesheets
5) updated SGIDOC DTD - includes RefPages
6) new beta stylesheets for SGIDOC books (not used by XHELP books)
By now you have seen IRIS InSight and the SGIHelp system that released
on IRIX 5.2. You've probably played around with some of the apps and
pulled down that "Help" menu that sits on the far right side of the
application and seen the help that is available. You probably said
"Cool!!! this is great!" and now you want to add that same functionality
to your own apps. Well look no further cuz now you can. Simply install
the sgihelp_dev images on your machine, add the few library calls to
your application, and build the help book for your application. Then
you just need to give your app and the inst images of the help book that
gets created to your customers and now you have SGIHelp integrated into
your application. To begin this adventure follow the steps below to
install the tools and look at an example application that demonstrates
the complete process for integrating help with an application and
creating inst images of the help and application.
What does SGIHelp give me, you might ask. Well for one it integrates
context sensitive help and task based help into your application in
a seamless manner that makes your app look like any other SGI application.
In your help you can have lots of different organizational constructs
like ordered lists, notes warnings, figures, and a slew of other
structures. All these structures are supported via SGML (Standard
Generalized Markup Language) which increases document portability since it
is an ISO standard known around the world. There are also other viewers
on other platforms that can view this same SGML content - so when you port
your application to another platform you don't have to rewrite all your
help any more.
To extract the images off the CD issue the following command:
inst -f ~4Dgifts/toolbox/utilities/sgihelp_dev
or
inst -f /CDROM/utilities/sgihelp_dev
or
inst -f /cdrom/utilities/sgihelp_dev
etc.
The image installs a little over 2M of data and executables onto your
disk. Contained in this are two samples - one is an example program
that has help integrated into it, and the other is a sample of the
various structures you can create in the help content for your
application.
OK, now that you've extracted the files off the CD, what do you do
next. We have included three sample examples in this developer package.
The first example shows a complete X11/Motif application that
integrates the library calls and helpmap file with the SGML help file.
This example is in /usr/share/Insight/XHELP/samples/exampleApp.
This would be a good place for you to begin. Tools have been provided
that will allow you to completely build and test this example. To
perform that operation, do the following:
% cd /usr/tmp
% cp -r /usr/share/Insight/XHELP/samples .
% cd samples/exampleApp
% make
// This will build the application, and the help book
% make images
// This will build the inst images for the application,
// and the help book
% su
# inst -f images
# exit
// This will install the inst image in the proper
// location on the disk
% ./exampleAppXm
// This will run the example application, try items off
// the help menu...the SGIHelp server should start up
// and render help cards relating to this application
// from the help book that was created/installed in
// the previous steps.
The second example demonstrates the various SGML structures that are
valid when constructing a SGML instance of the XHELP DTD. This sample
file is in /usr/share/Insight/XHELP/samples/sampleDoc. When preparing
your help book it may be useful to examine this file, and cut & paste
desired elements from the sample into your own text, modifying content
where needed.
The third example happens to be a document that describes the elements
available in the XHELP DTD, using the XHELP DTD. When preparing your
help book this document may be useful to determine which tags should
be used at which parts of the document structure. This document
can also help you fix errors in your document when you encounter
illegal structures.
There is a document called HELPDEV.txt in /usr/share/Insight/XHELP that
discusses how to integrate help with your application in more detail.
Please read that file to begin your adventure of integrating SGIHelp
into your application.
Good luck and welcome to the world of SGIHelp.
Documentation
Data
OR, ...