Level: Introductory Martha Andrews (mandrew@us.ibm.com), Staff Software Engineer, IBM
15 Feb 2005
Updated 15 Feb 2005 When a user chooses a design pattern, he or she may need documentation about how to apply and use the pattern. Authors of design patterns can provide such information via the Eclipse online help. This article describes how pattern authors can create documentation for their patterns and display it as part of the standard online help in IBM Rational Software Architect.
Introduction
IBM® Rational® Software Architect allows you to generate help for the patterns that you create. This article describes the help generation feature that you can use to add documentation about patterns to Rational Software Architect's online help. In addition, this article outlines the steps to follow to add documentation without using the help generation feature.
This article is intended for Java developers who are creating pattern libraries with Rational Software Architect. It will be beneficial if you are familiar with the Eclipse online help system and help anchors. For information about design patterns in Rational Software Architect, refer to the online help provided in the product. For information about developing online help plug-ins and using anchors with the help system, you may find the following article helpful, Help -- Part 1: Contributing a Little Help (Revised for 2.0), listed in the Resources section at the end of this article.
This article refers to the Reusable Asset Specification (RAS) files that provide a standard structure and organization for patterns and pattern libraries. For more information on RAS and patterns, see the Rational Software Architect online help.
The MyPatterns project
To assist in describing the directory structure and generated files used in the online help, this article refers to a project example. The project is a pattern library that contains two patterns: Pattern1 and Pattern2. Each pattern has one parameter.
This article focuses on the files that are in the PatternFiles directory tree. These files are observable in the Package Explorer view during pattern design. Listing 1 shows the PatternFiles directory structure for the project example immediately after the example is created and the patterns are added:
PatternFiles/
Pattern1/
Pattern1.emx
Pattern1.rmd
Pattern2/
Pattern2.emx
Pattern2.rmd
MyPatterns.rmd
|
Listing 1. PatternFiles directory structure
Generated help files
You can generate help for a pattern library by invoking the Generate Help Files command from the pattern library's context menu (right-click in the Pattern Authoring View). This causes the following to occur:
- Creates an HTML file using information in the pattern library RAS descriptor
- Creates a table of contents file for the pattern library
- Creates multiple HTML files for each pattern in the library using information in the pattern RAS descriptor
- Creates a table of contents file for each pattern
- Adds references to the table of contents files to the plugin.xml for the library
After generating help, Listing 2 shows the PatternFiles section of MyPatterns:
PatternFiles/
Pattern1/
Pattern1.em
Pattern1.rmd
PatternHelp/
Pattern1Description.html
Pattern1Overview.html
Pattern1Parameters.html
Pattern1ToC.xml
Pattern2/
Pattern2.emx
Pattern2.rmd
PatternHelp/
Pattern2Description.html
Pattern2Overview.html
Pattern2Parameters.html
Pattern2ToC.xml
PatternHelp/
MyPatterns.html
MyPatternsToC.xml
MyPatterns.rmd
|
Listing 2. PatternFiles section
As you can see, generating help created three directories and several files. The following sections explain each of the generated files in detail.
The pattern library help content file
The pattern library help content file is an HTML file that contains information from the library's RAS manifest file. In the example project, MyPatterns.rmd is the RAS manifest file for the pattern library.
The pattern library help content file contains information such as the short description, the version and ID of the library, and a list of patterns in the library. The help content file is stored in the PatternHelp directory owned by the PatternFiles directory and has the same name as the library. In the example project, MyPatterns.html is the pattern library help file.
The pattern library table of contents file
The pattern library table of contents file is an XML file that follows the format for toc files in Eclipse. This file provides three services:
- It links the library's generated help files to the Rational Software Architect Pattern online help
- It describes the help topic for the library
- It provides an anchor so that patterns in the library can insert help
The pattern library table of contents file is stored in the PatternHelp directory, and it takes the name of the pattern library appended with ToC.xml. In your example project, the pattern library table of contents file is MyPatternsToC.xml. Because the table of contents is so important, let's look at it in more detail. Listing 3 shows the content of the MyPatternsToC.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="MyPatterns"
link_to="/com.ibm.xtools.pttrn.user.doc/applypattern_TOC.xml
#morePatterns" topic="/MyPatterns/PatternFiles/PatternHelp/MyPatterns.html">
<topic
href="/MyPatterns/PatternFiles/PatternHelp/MyPatterns.html"
label="MyPatterns">
<anchor id="specificPatterns"/>
</topic>
</toc>
|
Listing 3. MyPatternsToC.xml file
The generated table of contents file for a pattern library specifies a topic named for the pattern library. The pattern library topic points to the generated pattern library help content file. Within the pattern library topic, the table of contents defines its own anchor point.
The toc element contains a link_to attribute. This attribute displays help for the MyPatterns library under the help for the Patterns feature in Rational Software Architect. The pattern's online help provides an anchor called morePatterns in a standard online help toc file. All pattern libraries can link to this anchor, so that all installed patterns are displayed together in the same online help container (or book). The result is that all of the pattern's information and related online help are consolidated in the same location.
The pattern help content files
For each pattern, three content files are created with information from the pattern's RAS manifest file. The RAS manifest for a pattern is in the directory named for the pattern, and contains information about the pattern and its parameters. In the example project, Pattern1.rmd and Pattern2.rmd are the RAS manifest files for Pattern1 and Pattern2, respectively.
All of the content files are found in the PatternHelp directory owned by the directory named for the pattern. The following is a short description of the files:
- Overview content file: This file is populated with general information about the pattern, such as the short description, version, author, and a list of groups to which the pattern belongs. The overview file is displayed when the pattern applier invokes the Show Pattern Documentation command for the pattern in the Pattern explorer or the Apply Pattern wizard. Its file name is created by appending the pattern name with Overview.html. In the example project, Pattern1Overview.html and Pattern2Overview.html are the overview files for Pattern1 and Pattern2, respectively.
- Description content file: This file allows you to provide a detailed description of how to apply the pattern. If you did not use the Import Description File context menu command in the Pattern Authoring view to import a description, this page will contain only the name of the pattern. The name of this file is created by appending the pattern name with Description.html. Pattern1Description.html and Pattern2Description.html are the description files in the example project.
- Parameter content file: This file is populated with information about the parameters of the pattern. The file is divided into sections, one section for each parameter. Each section contains the type, visibility, multiplicity, ID, and a description of a parameter. If you did not use the Import Description File context menu command to import a description, the description area will be blank. The name of this file is created by appending the pattern name with Parameters.html. In the example project, the parameter content files are Pattern1Parameters.html and Pattern2Parameters.html.
The pattern table of contents file
The pattern table of contents file is an XML file that follows the format for toc files in Eclipse. The file links to the anchor defined in the pattern library table of contents file. It contains a topic named for the pattern, as well as a subtopic for each of the three generated help content files described in the previous section.
Let's look at the table of contents for Pattern1 so that you can see how the topics are arranged. Listing 4 shows the contents of the Pattern1ToC.xml file:
<?xml version="1.0" encoding="UTF-8"?> <?NLS
TYPE="org.eclipse.help.toc"?>
<toc label="Pattern1"
link_to="PatternFiles/PatternHelp/Oct19PattLIbToC.xml#speci
ficPatterns" topic="Pattern1Overview.html">
<topic
href="PatternFiles/Pattern1/PatternHelp/Pattern1Overv
iew.html" label="Pattern1">
<topic
href="PatternFiles/Pattern1/PatternHelp/Pattern1Parameters.
html" label="Parameters"/>
<topic
href="PatternFiles/Pattern1/PatternHelp/Pattern1Description
.html" label="Description"/>
<topic
href="PatternFiles/Pattern1/PatternHelp/Pattern1Overview.ht
ml" label="Overview"/>
</topic>
</toc>
|
Listing 4. Contents of the Pattern1ToC.xml file
Notice that the toc element contains a link_to attribute that points back to the anchor point defined in the pattern library table of contents. Therefore, the help for Pattern1 is nested in the pattern library book in the Eclipse help system.
References to table of contents files in the plugin.xml
The plugin.xml file for the pattern library plug-in must contain toc elements for each pattern's table of contents file. The help generation process adds a toc element whenever it creates a table of contents file.
Manually integrating with online help
If you prefer not to use the automatic help generation, you can provide help files and link to the Patterns Help anchor so that your online help will appear in the same part of the table of contents as the generated help files. This section describes the steps you should take to link help for your pattern to the Patterns online Help in Rational Software Architect.
This section refers to the MyPatterns example project. To review, Listing 5 shows what the PatternFiles directory tree looks like before any help is added:
PatternFiles/
Pattern1/
Pattern1.emx
Pattern1.rmd
Pattern2/
Pattern2.emx
Pattern2.rmd
MyPatterns.rmd
|
Listing 5. PatternFiles directory tree
The following steps describe how to add directories and files to the project so that help is available for Pattern1.
Anyone applying your pattern can access help on a specific pattern by selecting it in the Pattern Explorer view and choosing Show Pattern Documentation from the context menu. The pattern user interface opens the online Help, displaying the overview page for the pattern with the pattern topic selected in the table of contents pane.
To provide this capability without using the built-in help generation, you must supply a file named for your pattern with Overview.html appended so that the application interface can display help. This file must be in the expected directory structure: a directory named for your pattern, a subdirectory named PatternHelp. To enable your patterns to appear as part of the Table of Contents in the online Help window, you must link to the anchor that the Patterns Help provides.
Follow these steps to hook into the help:
- Create an HTML file that will be displayed as the main help page for you pattern. This file should be named for the pattern name, with Overview.htmlappended.
- Put the page in the directory structure described above: a directory with the same name as the pattern, with a subdirectory named PatternHelp.
- Create an XML toc file with a
link_to attribute that points to /com.ibm.xtools.pttrn.user.doc/applypattern_TOC.xml#morePatterns
- Add topic elements to the XML toc file for any topics that you want to include. Make sure you include a topic for the overview file you created in Step 1.
- Add a reference to the table of contents file to your plugin.xml file. You can do this by opening the plugin.xml file in Eclipse, clicking on the Extensions tab, selecting the org.eclipse.help.toc extension, and using the context menu to add a new toc element.
The MyPatterns example project would look like what is shown in Listing 6, after the steps for providing help for Pattern1 have been followed:
PatternFiles/
Pattern1/
PatternHelp/
Pattern1Overview.html
MyTableOfContents.xml
Pattern1.emx
Pattern1.rmd
Pattern2/
Pattern2.emx
Pattern2.rmd
MyPatterns.rmd
|
Listing 6. MyPatterns example project
The MyTableOfContents.xml file should look like Listing 7:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Pattern1"
link_to="/com.ibm.xtools.pttrn.user.doc/applypattern_TOC.xml#morePatter
ns"
topic="/MyPatterns/PatternFiles/Pattern1/PatternHelp/Pattern1Overview.h
tml">
<topic
href="/MyPatterns/PatternFiles/Pattern1/PatternHelp/Pattern1Overview.ht
ml" label="MyPatterns">
</topic>
</toc>
|
Listing 7. MyTableOfContents.xml file
The topic listing for Pattern1 in the Eclipse Help table of contents will appear at the same level as the listings for libraries that have used the help generation feature. This is because the link_to attribute points to the anchor point defined by the Rational Software Architect Patterns feature. If you prefer to mimic the structure of the generated help, you can provide a help content (HTML) file for your library and use the link_to attribute to put it "under" the patterns feature Help. Then, you can define a topic for your pattern under the topic for your library using the standard Eclipse help toc syntax.
To test your Help, run a debug workbench from Rational Software Architect. Right-click your pattern in the Pattern Explorer view and select Show Pattern Documentation. An Eclipse Help window should open with your file in the right panel and the topic for your file selected in the left panel. If the file shows up on the right but the topic is not selected on the left, there may be a problem with your table of contents file. If you see a message that there is no help for the pattern, it means that the Patterns user interface could not find your overview file; check that you have created it in the expected directory and named it as described in Step 1 earlier.
Conclusion
This article described how you can generate online help for patterns and pattern libraries, and how the generated help is linked to the standard online help. Then, it showed how you can provide your own help content for patterns by defining a similar structure.
Resources -
The article Help -- Part 1: Contributing a Little Help (Revised for 2.0) provides information about developing online help plug-ins and using anchors with the help system.
- Get the evaluation version of Rational Software Architect from the Trials and betas page.
- For technical resources about Rational's products, visit the developerWorks Rational content area
. You'll find technical documentation, how-to articles,education, downloads, product information, and more. For specific information about Rational Software Architect, visit the RSA technical resources page.
- Find more product related information by visiting the Rational Software Architect product page.
- For details and more information about the Eclipse 3.0 platform, visit the Eclipse home page.
- Get involved in the developerWorks community by participating in
developerWorks
blogs.
- Ask questions about Rational Software Architect in
the Rational Software Architect, Software Modeler, Application Developer and Web Developer forum.
- Purchase Rational books at discounted prices in the Rational section of the Developer Bookstore.
About the author  | | | Martha Andrews is a software engineer working on the user interface for patterns in Rational Architect. She has experience working with most Rational tools and Eclipse. |
Rate this page
| 
