Adding help to an application.

Help can be added quite simply. If you create a help file (very simple XML) and register it with your CLI, you can supply your users with online help and examples. Here is the DTD for the help file:

    <!DOCTYPE help [
            <!ELEMENT help (entry)*>
            <!ELEMENT entry (body|example)*>
            <!ATTLIST entry
                    alt CDATA #IMPLIED
                    id CDATA #REQUIRED>
            <!ELEMENT body (example|entry)*>
            <!ELEMENT example (#PCDATA)>
            ]>

If you add a help entry, you set the id (this is the user enters to see the entry) and a main entry. If you add an example element, the user will be able to display examples. Sample help document:

    <?xml version='1.0' encoding='utf-8'?>
    <help>
        <entry id="abs">
            <body>
     <![CDATA[abs(arg) - find the absolute value of a number or stem.]]>
            </body>
            <example>
    <![CDATA[abs(-2) yields 2.]]>
            </example>
        </entry>
    </help>

You may have as many help entries as you like. Examples are optional.

Loading help in your application.

Since there is built in help, you just need to

  • Create your help file in the src/main/resources directory
  • In the constructor to your Command class, issue a call to the HelpUtil to load it, e.g. if you have extended the StoreCommands class, there is a method called bootstrap that will load the standard help for stores. You want to call super, then add yours. Note that my-help.xml must reside in the resources directory. 
            public void bootstrap() throws Throwable {
            super.bootstrap();
            getHelpUtil().load("/my-help.xml");
        }

The net result is that your help is not available with the /help command. Note that if you make the id of the help more than one word, users will have to put quotes around it to find it.