Creating UltraScan III Help Pages

UltraScan III Help System

This document details the steps a developer must take in adding help for a new application for UltraScan III.

  1. Summary of Developer Steps

For a developer to add help for a new application (call it "newapp"), the following steps are needed. These are performed in the doc/manual subdirectory.

cd ~/ultrascan3/doc/manual
  1. Create an IMAGE file (image/newapp.png) showing a sample window, using a screen capture utility.
  2. Create a BODY file (newapp.body) with explanatory text and reference to the image file.
  3. Add entries for newapp to manual.qhp :
    • A <keyword> entry;
    • A set of <file> entries to <files>.
  4. Add an entry in the index.body file.
  5. Create target files with a make.
  6. After successful final test, commit modified and new files.
  1. Step Details
  1. IMAGE files
    • It may be necessary to produce more than one image file, if the GUI is somewhat complex.
    • If so, the base naming convention should be followed. For example,
      • image/newapp.png
      • image/newapp-control.png
      • image/newapp-loader.png
  2. BODY files
    • Similarly, there may be need for multiple .body files, with crosslinks.
    • The developer should only produce BODY files, not HTML file; the HTML files are produced at make time, with a standard header and footer produced.
    • The precise form of the HTML in a BODY file varies from application to application. A review of existing documentation would lead to a choice of a similar application on which to base the new BODY file.
  3. Entries to manual.qhp
    • In adding to manual.qhp's keywords section, the developer should add the new entry to the position where the new keyword name would fall naturally for name values arranged in alphabetical order. The id value should be unique, start with the single letter that the name starts with, and have a numeric part that reflects the order of the entry among entries with the same starting letter.
    • If a new entry would fall naturally between entries with id values of "s2" and "s3"; the new entry should be given an id value of "s3" and the old "s3" renamed "s4".
    • Additions to the files section should include all *.html and image/*.png files.
  4. Index additions
    • Often, INDEX entries for an application already exist, since the index.body file was based on existing US2 documentation.
  5. The MAKE
    • Running the make command from */ultrascan3/doc/manual should produce no errors; should produce new HTML files and a new manual.qch file.
  6. Tests and COMMIT
    • Before committing updated source, the developer should review documentation shown with the Help button of the application.
    • All links should work and all image files be present.
    • The commit involves adding BODY and PNG files through SVN; and setting appropriate propset values.
Last modified 9 years ago Last modified on Apr 22, 2011 9:54:28 PM