Customizing the help system

The core help system is based on the Crash Magic documentation.  However an end user administrator may add additional content to any help keyword by editing the helpreference attribute and adding a help topic for that keyword.

The structure of the helpreference attribute is an xml document like this:

<pdroot>

 <HelpReferenceTable>

         <General>

                 <BaseURL>/files/Help/HTML</BaseURL>

         </General>

         <HelpItems>

                 <!-- ********* Analysis side help keywords ********** -->

                 <HelpItem Keyword="cmMainForm">

                         <Title>Crash Magic Online</Title>

                         <Description>Basic information about Crash Magic</Description>

                         <URL>IntroductionOverview.htm</URL>

                         <OtherKeywords>

                                 <Keyword>CurrentWebManual</Keyword>

                                 <Keyword>PDFManual</Keyword>

                                 <Keyword>Tutorial</Keyword>

                                 <Keyword>PSROverview</Keyword>

                         </OtherKeywords>

                 </HelpItem>

                 <HelpItem Keyword="cmDefaultPanel">

                         <Title>Home Page</Title>

                         <Description>Home page</Description>

                         <URL>Homepagepanel.htm</URL>

                 </HelpItem>

...

                           <HelpItem Keyword="cmAdminPSRattrPanel">

                         <Title>Attributes information</Title>

                         <Description>Generic attributes panel information</Description>

                         <URL>Attributes.htm</URL>

                 </HelpItem>

                           <HelpItem Keyword="cmAdminPSRattrPanel">

                         <Title>Attributes information</Title>

                         <Description>Generic attributes panel information</Description>

                         <URL>Attributes.htm</URL>

                 </HelpItem>

                 <!-- ********* User-defined help keywords ********** -->

                 <HelpItem Keyword="UserDefined">

                         <Title>User-specific help topic</Title>

                         <Description>Base level user defined help link</Description>

                         <URL>help_system_description.htm</URL>

                 </HelpItem>

         </HelpItems>

 </HelpReferenceTable>

 <Settings/>

</pdroot>

The BaseURL tag defines where to look for a URL if the URL isn't already fully qualified.  This makes it possible to direct an installation to point to the Pd' Programming server and have up to date help all the time, or to host the help files on any other server.  The default is /files/Help/HTML which points to the help system installed with the application.

Each HelpItem is referenced by a "Keyword" that is specified by the application.  That is, the application adds keywords to the help list as the program runs, and when help is called for, this list is searched for a HelpItem that specifies that Keyword.  It then displays the "Title" in the help box and links it to the "URL" specified.

For every case where a Keyword is added to the help list, that keyword is also added with a "_Custom" as well.  This makes it possible to create end-user defined help and have it appear from within the same help system as the built-in help.  In this case, the URL will probably be fully qualified and point to a user-maintained html or other document.

Rather than edit the "Default" helpreference in the .master/.shared attribute list, the preferred method is to create another "Default" helpreference in the appropriate User Group / .shared attribute list.  (copy/paste is an easy way to do this)  Then simply add _Custom to any item you wish to add additional help to.  When the help system looks for a help keyword, it first looks in the User's attributes, then the group's .shared attributes and finally in the .master/.shared attributes.  It displays the first help it finds.