It is increasingly common for commercial development tools and components to make available in several different editions. This poses a challenge to the technical writer in highlighting which members are available in different editions of an SDK.
The information in this article outlines how to customize a Document! X Template and create a new content type to allow members to be identified as specific to a particular edition of an SDK (in this example, an Express edition) and have those members indicated by an icon in the members list in the generated documentation and Content Editors. This process can also be adapted for tracking and highlighting other attributes of members (e.g. deprecated, platform).
Modifying the Template
Note: If you have not done so already, create a custom Template for your modifications. Consult the Document! X online help for information on creating custom Templates.
To modify your template:
- In the Template editor, select the Other Files page menu item;
- Right-click the packages folder and select Open in Windows Explorer context menu option. From there, you need to create a new folder named "Custom" and then a new folder in that directory named "dotnetimages";
- Copy the icon image you want to use into the new dotnetimages sub-folder (e.g. express.gif);
- In the Template Editor, right-click on the newly created dotnetimages folder and select the Add Existing Other File context menu option - from there, navigate into the "templates/packages/Custom/dotnetimages" directory and select the express.gif file you added to that folder in the previous step;
- In the Template Editor, switch to the Scraps page and edit the Scrap named "_MEMBER_LIST_BODY" by inserting the following HTML at the end of the existing image cell (e.g. just before the closing </TD>):
%%TaggedComment:source=Item, id=##EXPRESS, Format="<IMG alt='Available in Express Edition' align=left SRC=/templates/packages/custom/dotnetimages/express.gif>"%%
- Click OK to save your changes to the template.
Defining the new Content Type
- Select the Content Item Types page in the Document! X configuration editor
- Click the New toolbar button
- Type "Express" in the Identifier and Caption fields
- Type "General Description" in the Group field
- Select the desired Icon that will be used to identify this new content type in the Document! X content editors
- Type "express" in the XML tag name field. This will allow you to use an XML comment to identify members as "express edition" in the source code (e.g. /// <express/>)
- Tick Method, Property, Field and Event from the Can be associated with list
- Click OK to save the new content type
Marking members as applicable to the Express Edition
You can now use the Content File editor to mark members as being applicable to the Express edition as follows:
- Select the member you want to mark as express
- Click on the icon in the Content File Editor toolbar for the Express content type
- Type some text (any text will do - e.g. "Yes")
When you now build your documentation an additional icon will be included in the member list for members you have marked with the Express content type.
You could also choose to include a TaggedComment page element with some static text in the member page layouts to highlight the Express edition membership. Example:
<!--DXMETADATA start type="TaggedComment" source="Item" id="##EXPRESS" format="<p>This member is only available in the Express Edition</p>" --><!--DXMETADATA end -->