Creating Help Systems with Help & Manual

Abstract

Help & Manual is a help system author tool from EC Software. It’s actually more than just a help system tool. Help & Manual is a single-source help authoring and technical writing product that you can use to create online and offline help, interactive and hardcopy documentation, and many other types of written or online material. In other words, write once, publish in multiple formats, and include some or all of your writing in the documentation.

This article provides an overview of Help & Manual features. It also describes using Help & Manual to create a rights-sensitive help system for an online application written in Delphi for .NET. What help screens are displayed by the online help is controlled by the Delphi application, since the help varies depending on the currently logged on user’s assigned privileges.

Help & Manual description

Help & Manual was written in Delphi 2007. (EC software is currently using Delphi 2009 for upgrades to Help & Manual). The Standard version of Help & Manual allows for the creation of extensive help systems and documentation. There is also a Professional version which allows you to also work with and save files in uncompressed xml, includes multi-user functionality which allows for concurrent multi-author editing, integrates with version control software, and provides capabilities for project help system translations and localization. There is also a Premium pack of 14 configurable skins for your help systems which is available as an optional add-on for purchase with both the Standard and Pro versions.

Help & Manual makes it easy to create self-contained help systems

Help & Manual makes it easy to create self-contained help systems that include a multi-level table of contents, topic details, a navigational bar for moving forwards and backwards through topics, search capabilities, and indexes. You can start with one of the project templates, or you can create your own template. In addition, the skins in the Premium pack allow you to easily try out a variety of professional looks for your help system.

You can import existing text into Help & Manual from a variety of formats including HTML and text files, RTF documents (saving Word files as RTFs), complied HTML help files (.CHM), compiled WinHelp files (.HLP), WinHelp source files (.HPI), and RoboHelp for HTML project files.

Help & Manual’s main screen is shown figure 1.

Fig. 1

In Help & Manual you work with projects, and these are displayed in the Project Explorer. Help & Manual projects contain your individual topic files and baggage files for files that are used repeatedly such as icons used in the help display, and the like. For images you use in your help, you will most likely want to keep them organized in one or more folders. You simply configure your project properties to include the paths to search to let Help & Manual know where to find these files.

The topics displayed in the Project Explorer contain your text (shown in the Editor). Topics form your table of contents entries in your help system. You can easily create, edit, rearrange, and delete topics within the Project Explorer.

The Ribbon toolbar contains the tools you use for working with projects, writing, working with tables, viewing and selecting other Help & Manual program options, and accessing Help for Help & Manual.

The wysiwyg Editor (a true wysiwyg xml editor) is where you do the bulk of your writing. The Editor has all of the word processing and formatting features that you want and need, plus all the help system tools to add and define links, insert images, insert and define tables, and include other objects like movies, horizontal (sizable) lines, special characters and symbols, hyphens, and page breaks for printed manuals. Your links can link to other topics in your help, anchors in your help, images, files, movies, URLs, and the like.

From the Editor, you can add additional features to your help. For example, you can add expanding/collapsing text, insert topic anchors, insert HTML code objects, and insert or link snippets of text from other topics or other files. Using snippets, you can build a library of reusable content that updates automatically in your projects if you edit the source snippets, provided you use linked snippets. You can also insert OLE objects, add and define image hotspots, insert WinHelp macros, and insert dynamic HTML or JavaScript code to extend the features needed in your Help system, and add comments for future reference.

You can also insert OLE objects, add and define image hotspots, insert WinHelp macros, etc

You can publish (compile) your documentation in a variety of different formats including:

• HTML help (.CHM)
• WebHelp, a browser-independent HTML format for a self-contained Web site
• Adobe PDFs for either creating pdfs with interactive table of contents and hyperlinks
• Adobe PDFs for printing documentation
• WinHelp (.HLP)
• Microsoft Word RTFs
• A proprietary e-book .exe file with the content and a viewer to display the help content
• EPUB, a cross-platform e-book standard containing XHTML and XML files

In addition, you can integrate your Help file into the Microsoft Visual Studio .NET Help documentation (MS Help 2.0) in order to document third-party programming components designed for integration into VS.NET.

You can also create context-sensitive Help. For example, you can simply create a popup window that displays a small amount of information when a user clicks on a link or presses F1. More frequently in an application, you want your context-sensitive help to also include access to the rest of the help system. In this case, you make a call from your application or a link from HTML to the particular help topic.

Help & Manual includes tools for creating context-sensitive help when you want to include your entire help system, since how you create the links varies depending on your programming language and the format of your Help system. There are also online tutorials and references for help with integrating your help systems with applications written in Delphi, C++, Visual Basic 6, Visual Basic.NET (Visual Studio.NET), Microsoft Access, Visual Objects, Visual FoxPro, Clairon, APL, and REALbasic for Windows.

The 14 configurable skins available as an add-on for both the Standard and Pro versions are professionally designed layouts that make it very easy to test out different HTML designs to apply to your help projects. The skins work for Internet Explorer 6 & 7, Google Chrome, and other standards-compliant browsers. You can modify the JavaScript, CSS styles, and HTML in these skins. However, if you do configure or create your own skins, you do need to test in all browsers. For instance, you need to use equivalent CSS styles and HTML in case the user has JavaScript disabled on their browser.

Help & Manual's files are encoded in Unicode, making it possible to publish (compile) your projects in a variety of languages

Help & Manual's files are encoded in Unicode, making it possible to publish (compile) your projects in a variety of languages. Although Help & Manual makes creating help projects for Unicode languages straightforward, there are some additional setup issues that need to be dealt with for Microsoft help compilers that are not Unicode enabled. You will also need to be running the Windows-based version for the language you are compiling to in order to test your help system's functionality like the table of contents, search features, and hyperlinks.

Other Help & Manual features of note:

• Allows you to create very large help projects
• Images in help can be expanded easily (i.e. view larger image type feature)
• Allows you to work directly with map files
• Allows for conditional text and conditional variables in the help
• Referral checks, allowing you to find incoming and outgoing referrers to specific topics
• A reporting tool for checking topic captions, topic IDs, help context descriptions, build inclusions, and dates modified
• A project synchronization tool to manage and update translated versions of your projects

Help & Manual also comes with three very useful tools:

1. Screen capture software;
2. IMPICT Screenshot Editor, an easy-to-use, nice tool for adding special elements, such as the callouts in figure 1;
3. Print Manual Designer, which allows you to further customize pdfs and printed pdf output.

And I guess we shouldn't be surprised that a company that creates help system software has outstanding help documentation about their product, both with the product and online. The Help & Manual help is extensive, and well-written. In addition, tips on good design practices, organization, and other such essential topics are included throughout.

An example of using Help & Manual to build a web-based help system

The Help system described in this article is end-user Web-based help for one part of an access-controlled Internet application that was written in Delphi for .NET. This Help system used the WebHelp format in Help & Manual, creating a self-contained HTML-based Help system with a table of contents, navigation capabilities, and a searchable index.

The help system actually included several different online help systems since the help information displayed differed depending on the employee’s individual access rights

The help system actually included several different online help systems since the help information displayed differed depending on the employee’s individual access rights. For example, a supervisor needs to be able to see the same help that their employees are able to see, but also see more specific information about features of the application only available to supervisors.

Special considerations/requirements for this system included:

• Text needs to be easy to read, with lower reading level assumed for parts of target audience
• Application code controls display of help because of different levels of user access required:
  • Some topics, all users have access to
  • Some topics, a subset of users have access to
  • Some topics, different users see identical help but with some variations, depending on their access level
• Application code controls links to context-sensitive help
• Help needs to display quickly, include a table of contents and index, and be searchable
• Help needs to be able to be downloaded to a local machine if the user wanted
• Parts of help need to be in a printed format for learning or desk reference documentation

Creating the help project

I started by writing in Word, and then imported documents into Help & Manual. But after my initial writing, it soon became apparent that Help & Manual was up to the task and became my primary help writing tool. The wsywig editor, along with the breath of word-processing and formatting tools, made writing in Help & Manual as easy as writing in Word.

Another reason why I preferred writing in Help & Manual is because some tasks can only be done with Help & Manual. These tasks include setting up global properties for the help project, defining topics, assigning unique topic IDs used to link to a page directly from another page or from a link in the application, organize topic structure, defining index items, defining links between items and topics, defining conditional variables, and defining links to external files.

As you can see in figure 2, you are able to have multiple levels within your table of contents. You right-click on an entry in your table of contents to add or delete topics, and define properties such as including or excluding topics in various builds (output formats).

You use the Topic Options tab to define unique topic IDs and define keywords that will appear in a help index and link to this topic. You can also insert HTML topic variables like <%DATE%> as well as define your own conditional variables. You can redefine variables on a per-topic basis. This is especially useful for HTML code variables, allowing you to vary the code in the template part of your topic page (i.e. outside the <BODY> section generated by the topic in the editor) on a per-topic basis, for example, for fine-tuned search engine optimization.

You click the XML Source tab to directly edit the xml.

Fig. 2

Modular help projects with master/child relationships

We needed to account for five different levels of user access for our subset of applications, and we didn’t want to have to repeat some of the same help information over again in the Help documentation for every user access level.

With Help & Manual, you can set up a modular help system, using master/child relationships so you can keep your unique help documentation in separate files for easy reuse and more accurate help information. This way, you only need to edit or update particular help topics once. You can then set up master help files and include entries for the child projects files where they should appear in your table of contents. Furthermore, you can nest modules so that these child projects also contain their own child project entries.

Figure 3 shows an example of modular help, including two different master projects, MasterHelpSC.hmxz and MasterHelpE.hmxz, and one child project ToolHelp.hmxz. This child project contains help information common to all users of the application, and was included in each of the master files as the first item, Table of Contents in (ToolHelp). Besides using master projects to organize the child projects, you can also include topics directly in these files, and child projects can be included anywhere within the master project’s table of contents.

Fig. 3

You can then publish (compile) your master help file, which merges all the module files it contains in the order shown into one complete Help system. Publishing also converts and references your image files for the help system.

You can test your help system in a browser locally. Once you are satisfied, you upload all the help system files, including image and other files, to the server from which the online help will be served.

An example of testing the published online help (Webhelp format, using the default skin) in Internet Explorer is shown in figure 4.

Fig. 4

Figure 5 shows the same help using a different skin. The Index tab is selected here, showing the keywords we set up to link to particular topics. Users can also click the Search tab and search for text, and are given information on the number of matches and scores on relevancy.

Fig. 5

Usability Side Note: You may notice “The Tool Help” name in the help title and the Internet Explorer title bar. Despite whatever the application developers or management named the application(s), the end-users referred to the application simply as “The Tool,” as in, “I booked the vehicle in The Tool.” So, the name stuck as the whole point of the application was to make sure the users used, and took ownership of, the application.

As mentioned earlier, Help & Manual allows you to define conditions for publishing output for different formats. You can specify whether to include or exclude child projects, and include or exclude topics on a topic-by-topic basis. For example, you can include all information for online help, but exclude some topics for a printed pdf version. In addition, you can set up either compile time merging of modules (as shown here) or runtime merging which maintains separate help files that are merged, if present, at runtime.

Using Delphi and a database to control which help screens are displayed

We controlled user access to the help display from a Delphi for .NET ASP.NET Web application. The application itself employs access control on a number of levels. Each time a user requests a page of the application, a special class confirms that the user has already logged into the system, and that their session has not timed out. If the user has not yet logged into the system, or they have been idle too long, the application redirected them to a login page where they can enter their username and password.

Following this initial validation, a special class, called UserSession, reads a list of privileges specific to the logged in user. These privileges are then used to configure any ASP.NET Hyperlink controls that appear on the requested page. Zero or more Hyperlink controls may appear on a given page, and each of these may be associated with a different page or bookmark on a page.

The association between a Web page of an application, the help links that appear on that page, and a users privileges are table driven, permitting links targets to be updated by editing the database

The association between a Web page of an application, the help links that appear on that page, and a users privileges are table driven, permitting links targets to be updated by editing the database. The two tables in the underlying database that are used to associate help system links on specific pages of the application with a collection of user privileges are shown in figure 6.

The top table shown in figure 6 depicts the HelpBaseLinks table. This table contains the base URL of the help system for each of the available applications, based on user privileges. These entries are sequenced in order to provide the particular user with the help system associated with the highest-level privilege that the logged in user possesses. A single user may have many privilege levels. (Note that the the URLs shown in the BaseHelpURL field are not valid URLs, and are included here for descriptive purposes only.)

Here is how the process works. Once a user is validated for a page, a method named LinkHelpControls is called, passing it a single parameter containing a pointer to the current Web Page. LinkHelpControls queries the HelpBaseLinks for the application name (which is determined from the SCRIPT_NAME cgi variable) for the base help system reference associated with the user’s highest privilege. If there is no base help system defined, all Hyperlink controls configured on the current page have their visibility property set to False, and the process is over.

If a help system reference is found for the particular application/privilege combination, the HelpLinks table is queried for all of the named links expected on the current page, using the application name/page name as a key. This query returns not only the link name, but also the specific page or page/bookmark that each Hyperlink should link to.

This result set is then scanned, using each link name to call the FindControl method of the Web page. If FindControl does not return nil, the Hyperlink control is configured to reference the base Help URL plus the specific page or page/bookmark resource.

If the HelpLinks table contains an entry for a Hyperlink, but does not supply an associated page or page/bookmark value, it is assumed that this link should be suppressed on this page for this type of user. Under these circumstances, again the Hyperlink’s Visible property is set to False.

Fig. 6

The code for LinkHelpControls is shown below.

procedure TUserSession.LinkHelpControls(
  WebPage: System.Web.UI.Page);
var
  Connection: AdsConnection;
  Command: AdsCommand;
  DataReader: AdsDataReader;
  AppName: String;
  PageName: String;
  PrivilegeString: String;
  BaseURL: String;
  sa: array of String;
  LinkName: String;
  LinkTarget: String;
  LinkObject: HyperLink;
begin
  //Note: GetConnection, ReleaseConnection,
  //  and GetStringField
  // are utility methods,
  //  and are not part of the .NET framework

  //Parse the application name and Web page name
  AppName := WebPage.Request.ServerVariables.
    Item['SCRIPT_NAME'];
  sa := AppName.Split(['/']);
  PageName := sa[2];
  PageName := PageName.SubString(0,Length(PageName)-5);
  AppName := sa[1];
  Connection := GetConnection;
  try
    //Determine the Help system BaseURL
    // for this user’s privilege level
    Command := Connection.CreateCommand;
    Command.CommandText :=
      'SELECT PrivilegeStringList, BaseHelpURL ' +
      'FROM HELPBASELINKS WHERE ApplicationName = ''' +
      AppName + ''' ORDER BY SEQUENCE';
    DataReader := Command.ExecuteReader;
    while DataReader.Read do
      if Self.HasAtLeastOnePrivilege(GetStringField(
        'PrivilegeStringList', DataReader)) then
      begin
        //The BaseURL for the highest privilege
        BaseURL := GetStringField('BaseHelpURL',
          DataReader);
        Break;
      end;
    DataReader.Close;

    if BaseURL = '' then  //Bad news. No help
    begin
     //Make all help controls not visible
     Command.CommandText :=
       'SELECT LinkName, LinkURL FROM HELPLINKS '+
       'WHERE PageName = ''' + AppName + PageName + '''';
      DataReader := Command.ExecuteReader;
      try
        while DataReader.Read do
        begin
          LinkName := GetStringField('LinkName',
            DataReader);
          if WebPage.FindControl(LinkName) <> nil then
          begin
            HyperLink(WebPage.FindControl(LinkName)).
              Visible := False;
          end;
        end;
      finally
        DataReader.Close;
      end;
      Exit;
    end;

    //Get names of Hyperlink controls configured
    //  for this page
    Command.CommandText :=
      'SELECT LinkName, LinkURL FROM HELPLINKS '+
       'WHERE PageName = ''' + AppName + PageName + '''';
     DataReader := Command.ExecuteReader;
     try
       //For each Hyperlink control
       while DataReader.Read do
       begin
         LinkName := GetStringField('LinkName',DataReader);
         //Find the associated control
         if  WebPage.FindControl(LinkName) <> nil then
         begin
           //Got it. Configure this control
           LinkObject := HyperLink(WebPage.
             FindControl(LinkName));
           LinkTarget := GetStringField('LinkURL',
             DataReader);
           if LinkTarget <> '' then
           begin
           LinkObject.NavigateURL := BaseURL + '?' +
             LinkTarget;
           LinkObject.Target := '_blank';
           LinkObject.ToolTip := 'Click for help';
           end
           else
           begin
             //Oops. No Help. Make Hyperlink not visible
             LinkObject.Visible := False;
           end;
         end;
       end;
     finally
       DataReader.Close;
     end;
  finally
    ReleaseConnection;
  end;
end;

Conclusion

Help & Manual makes it easy to create full-featured help systems and other documentation for all current types of help systems. With Help and Manual, you can create a single source of material, and then customize the output for various formats from that same source as well as use conditional output. In addition, Help and Manual allows you to control your help documents programmatically, inserting your own HTML code, or working with the XML source directly to extend your help systems and documentation to get the exact results you need.

De sources die bij dit artikel horen kun je downloaden via anderson_creatinghelpsystems_SRC.zip.