How To Use the Topic Management Dialog

Introduction

The Topic Management Dialog aggregates three tool windows that are available in Visual Studio Standard and higher: Topic Explorer, Topic Filters and Topic Editor. The dialog is available as a project option in Visual Studio and the DocProject External UI.

Topic Explorer provides a tree view for creating the table of contents (TOC), creating and managing conceptual documentation and choosing the topics that will be built by Sandcastle.

Topic Filters provides the ability to include or exclude topics using regular expressions, categorical filters and even custom filters.

Topic Editor provides the ability to create external XML documentation for the project, namespaces and API elements in source mode and design mode.

Finding the Dialog

The dialog can be accessed by clicking a button on the Sandcastle toolbar (Figure 1) when using the DocProject External UI. In Visual Studio Standard or higher this button will open Topic Explorer instead, from which the other tool windows can be opened.

To open the Topic Filters window from Topic Explorer, click the toolbar button with a filter icon Topic Explorer - Topic Filters Button.
To open the Topic Editor window from Topic Explorer, double-click an auto-generated reference topic or right-mouse click and select Edit. Note that conceptual topics will open in Visual Studio's built-in XML editor instead.

Finding Topic Explorer and the Topic Management dialog - Sandcastle Toolbar
Figure 1: Finding Topic Explorer and the Topic Management Dialog - Sandcastle Toolbar

The dialog can also be opened in the DocProject Properties window and the DocProject External UI (Figure 2) by clicking the ellipses button of the Content > Topic Management property.

Finding the Topic Management Dialog - DocProject Properties
Figure 2: Finding the Topic Management Dialog - DocProject Properties

The MRefBuilder Configuration File Name property in the Active Projects page specifies the name of the configuration file, located in the Help\Presentation\Style\Configuration directory, that is to be managed by the dialog and used with the Sandcastle MRefBuilder program.

Where are my topics?

The source assemblies have to be present in order for Topic Explorer to display their topics. It does not automatically build all of the source projects so you must build the projects before using it. If you build a source project and then close and reopen Visual Studio the assembly will still exist, so you won't need to build the project again to use Topic Explorer for that source project.

If you only build some of the source projects then Topic Explorer will only display the API topics for the assemblies that you have built. If you clean the solution or otherwise delete any of the output assemblies from the source projects then the corresponding API topics will not be displayed.

Topic Explorer

Topic Explorer displays the table of contents (TOC) as it will be built by DocProject. The tool bar and a context menu provide various functions for working with topics and accessing other tool windows.

Topic Explorer toolbar
Figure 3: Topic Explorer toolbar

Topic Management dialog toolbar
Figure 4: Topic Management dialog toolbar

Conceptual Topics

You can use the Topic Explorer tool bar (Figure 3 and Figure 4) to insert and import conceptual topics and raw HTML topics. Once added, you can drag & drop topics to create the table of contents (TOC).

Conceptual documentation is built when at least one conceptual topic is added. If auto-generated reference documentation is also built, DocProject will merge them together automatically to create a single documentation set.

Conceptual topics must be written in the XML-based Microsoft Assistance Markup Language (MAML). The files are stored in the project's Help\Topics folder with an .aml extension and a friendly file name, which is not used for any purpose other than making it easier to find coneptual topic files on disc. Each conceptual topic also has an XML companion file, with a .cmp extension, that stores metadata for the topic. Metadata includes the TOC title and the display title, Help 2.x attributes like DocSet and TargetOS, as well as index keywords.

Note: Visual Basic projects do not show dependent files by default. To see the companion files you must use the Show All Files command in Solution Explorer.

You can manage a conceptual topic's metadata by manually editing its companion file using Visual Studio's XML editor or you can use the Topic Properties window by right-mouse clicking the topic in Topic Explorer and selecting Properties. Changes are committed when the Save All command is executed in Visual Studio or when the Save command is executed in the DocProject External UI.

For more information about Sandcastle's support for conceptual documentation using MAML, see Sandcastle Help, MAML.

Important: Renaming Topic Files
Renaming conceptual topic files is not currently supported so it's recommended that you choose appropriate file names when topics are created.

However, if you need to change a toipc's file name then follow these steps:
  1. Change the file name of the conceptual topic in the Help\Topics folder.
  2. Update the name of its XML companion file so that it has the same base file name as the topic, but with a .cmp extension.
    1. Note: Visual Studio may not let you do this in Solution Explorer. The only alternative is to unload the project file, edit it manually and then reload the project.
  3. Update the Help\Settings\topics.xml file to use the new topic name.
Note: The file attribute on topic elements in the topics.xml file supports a relative path from the Help\Topics folder, so you can move conceptual topic files into subfolders of Help\Topics but you must update the path in the topics.xml file manually. Then click the Refresh toolbar button in Topic Explorer to load the updated topics.xml file.

Auto-Generated Reference Topics

Reference topics that will be automatically generated by Sandcastle for project references and external sources appear under the root Namespaces topic in Topic Explorer if at least one source is configured. The root node can be dragged freely around the TOC so that it may be placed beneath conceptual topics; however, individual topics for each API cannot currently be rearranged.

Topic Explorer also provides information about the API that each topic node represents and the ability to filter nodes using Sandcastle's API filter (see Filtering Topics below).

The API type (e.g., namespace, module, class, structure, interface, enum, delegate, method, property, field or event) and the API accessibility (e.g., public, protected, internal or private) is shown by a topic node's icon and tooltip. This information is used by the Category topic filter (see below).
Pseudo Topics
Topics such as All Members, Fields, Properties and Methods, are provided by the documentation model of the selected Sandcastle presentation style, so they might not appear depending upon the selected presentation. These topics cannot be excluded by simply unchecking them in the tree, however, unchecking them will recursively uncheck all of their child topics, effectively filtering the parent pseudo topics as well.

Filtering Topics

The following image shows the Category Topic Filter tab. See the other tabs here.

Topic Management Dialog - Category Topic Filter
Figure 5: Topic Management Dialog - Category Topic Filter

A topic is included by checking its check box node in the tree view control and excluded by unchecking it. All of the API topics are included (checked) by default if the apiFilter configuration section hasn't been used.

You can also use the topic filters on the right side of the dialog to include or exclude multiple topics at the same time.

Search Options

A few options are provided for controlling the behavior of the topic filters.

Find/Apply next match only
Checked by default, this setting changes the behavior of the Find and Apply buttons so that only the next match will be located instead of all matches.

Show matching topics
Enable this option (default) to display matching topics in the tree as soon as they are found. Each parent node will be expanded to ensure that a matching node is visible. Disabled, the tree will not be changed and the matching items may or may not be visible.

Include matching topics
This setting indicates the checked state of matching topics when they are found by the Apply button. When checked, matching topics will be checked. When unchecked, matching topics will be unchecked.

Regular Expression Filter

Use the regular expression filter to include, exclude or locate topics by name using a managed-style regular expression. A link to an MSDN help reference on regular expressions is provided next to a link that pops-up a regular expression quick-help guide, which includes a few examples. You can also choose the regular expression's options.

The Find button will locate all matching topics by highlighting them.

The Apply button will locate all matching topics, highlight each of them, and ensure that the state of each check box matches the state of the Include matching topics check box.

An icon will appear next to the Find button after either of the buttons is clicked. The icon's tooltip displays the number of matching topics. The tooltip is automatically displayed for one and a half seconds after the search has completed. Clicking the icon repeatedly will cycle through all of the matching topics, selecting the current node and expanding nodes when necessary. The highlighted color and the icon's appearance differ depending upon whether you have clicked Find or Apply. Find was clicked in Figure 5 and the blue highlights in the tree are the matching topics.

Clicking the icon to cycle through the matching topics can be useful. Use the space bar to toggle (check or uncheck) a matching topic and click the icon to cycle to the next match. Using the icon and the Find button, instead of the Apply button, will allow you to manually choose the topics that should be toggled, one at a time.

Category Filter

Use the category filter to include or exclude topics by API category. For instance, to include all interfaces you would first check the Interfaces check box and ensure that no other category is checked. Then make sure that the Include matching topics check box is checked to include matching topics (unchecking it will exclude matching topics). Press the Apply button to apply the changes.

Like the Regular Expression Filter, an icon will appear next to the Apply button after it's clicked. The icon's tooltip displays the number of matching topics. The tooltip is automatically displayed for one and a half seconds after the search has completed. Clicking the icon repeatedly will cycle through all of the matching topics, selecting the current node and expanding nodes when necessary.

Filtering by accessibility
By checking a combination of Accessibility and API Types you can filter on categories such as, public or protected classes and structures, or internal fields and delegates, for example.

If nothing is checked under Accessibility then it is simply not taken into account when matching. In other words, any access type is a match. This is the same as if all access types are checked.

You can also choose an access level without choosing an API type and it will match all APIs with the selected access level. Choosing more than one access level is an OR operation, just like with API types.

To match protected internal members you must check protected and internal since it's treated as a distinct access type. In other words, DocProject does not treat protected internal members as just being protected or internal. One caveat is that searching for protected internal members will also explicitly match protected-only and internal-only members as well.

Saved Filters

The Saved Filters tab allows you to save Regular Expression and Category filters so they can be loaded and applied quickly in the future or, more importantly, applied automatically during each build.

Saving Filters
Filters can be added into the list by clicking the Save button that appears on each of the filter tabs (see Figure 5 above). Alternatively, you can directly edit the XML file in which they are saved, located at Help\Settings\dynamicFilters.xml. The file does not exist until you add a filter using the dialog and then click OK, but you can create the file yourself if you want.

The Include column indicates whether matching topics are included or excluded for each filter. When a filter is first saved, the value of this column matches the value of the Include matching topics search option.

Adding Custom Filters
You can create custom filters that apply to the Topic Explorer window and also during builds (dynamic filters). A working example of a custom dynamic filter is included in the DocProject Extensibility Samples 1.0 release.

To add filters to the list click the Add button Add Filter Button and use the dialog to browse to your custom filters.

Inheritance Filter
A custom dynamic filter that removes inheritance information is built-in to DocProject. You can add the filter to the list by clicking the Add button, as indicated above, and then configure it using its custom editor.

Importing Filters
Filters can also be imported from a dynamic filters XML file using the Import... button. Imported filters are appended to the list and do not replace any existing filters.

Editing Filters
The Memo column is a place to comment on filters. You can edit the memo directly in the list after you save a filter and it will be persisted along with the filter list when the changes are saved by the Topic Management dialog.

To change the other properties of the filter you can use the Edit button.

Note: Custom filters can provide their own editor.

Applying Filters
Clicking the Load button on a filter will load it into the appropriate filter tab (i.e., Regular Expression or Categories) and will then show the tab and apply the value of the Include column to the Include matching topics search option. The filter will not be applied, however.

The Apply button will immediately apply the filter to the topic tree using the current Search Options and the value in the Include column, but will not load the filter first.

The Apply All button will apply all filters to the tree view immediately, top-down. It will not prompt you first, so use this feature with caution.

Dynamic Filters
All filters that have a check mark in the Build column are applied in order, top-down, during a help build. The Apply all filters during builds option will either check or uncheck the Build column for all filters so that they have the same value as the option, and each other.

The arrows are used to order the filters, which is important because it allows for the scenario where a particular topic is excluded by one filter, but then brought back in by another, subsequent filter. The filter that re-includes the topic must appear after the filters that exclude it or else it will remain excluded.

Note: Dynamic filters do not apply to topics that have already been excluded by Sandcastle's API filter; e.g., if you uncheck a topic in the topic tree then a dynamic filter cannot be used to re-include the topic.

Creating XML Documentation

To create external XML documentation, select a topic in the topic tree, focus the Xml Comments tab, and select a particular section to be documented. Then use the XML Documentation Editor to author the documentation.

Topic Management Dialog - XML Documentation Editor
Figure 6: Topic Management Dialog - XML Documentation Editor

Sections

The list of available XML documentation sections (e.g., summary, remarks, typesafety) is based on the type of topic that is selected, generated automatically from the information in DocProject's configuration file. The list is also merged with the actual elements found in the existing external XML documentation files, even if the section is unknown to DocProject.

Multi-Instance Sections

Some sections may appear multiple times in the documentation for a particular API topic. For example, the exception section may be added multiple times, one for each Exception that the API may throw. To add an exception section to an API, select exception from the drop-down list that appears above the section list and it will be added to the section list. (If a section doesn't appear in the drop-down list then its association to the API type of the currently selected topic hasn't been specified in DocProject's configuration file.)

Custom Sections

To add a custom section to the list, simply enter its name in the text box above the sections list and press Enter on the keyboard. The new section will appear in the list.

Editing Features

The XML documentation editor supports tags such as <see>, <c> and <code> in both source mode and design mode. Sandcastle uses these tags when it builds your documentation to apply special formatting or to link to other topics.

A <see> link will be created automatically when a topic node is dragged from the topic tree and dropped into the editor, in both source and design modes.

Presentation

The editor uses the style sheets of the selected Sandcastle presentation style, with additional rules for formatting XML documentation tags such as, <see>, <c> and <code>, for example. The designer style sheet is located in your presentation's Style folder, which is commonly Help\Styles\TopicDesigner.css.

Persistence

XML documentation that you create on the Xml Comments tab is saved in individual XML files in the Help\Comments folder. One XML file is created for each source assembly and one project.xml file is created to contain the project and namespace summaries. If you prefer you can edit these files using Visual Studio's XML editor.

If you haven't edited any API elements for a particular assembly then its XML file will not exist in the Help\Comments folder, but you can create it yourself. The name of an assembly's XML documentation file must be the display name of the assembly with .xml appended to the end or else DocProject will not be able to merge your documentation with the XML documentation files generated by the compiler.

Merging

XML documentation that appears in your code using the triple-slash comments (or triple-apostrophe comments in Visual Basic) are not shown in this dialog.

By default, comments created in the dialog overwrite code comments, on a section by section basis; e.g., summary, remarks or example. But you can change this setting to give code comments precedence instead of being overwritten by selecting KeepSource for the Merge XML documentation setting found in Tools > Options > DocProject > Active Projects > Content.

For more information, see How To Configure DocProject.

How It Works

The filtering and TOC-related capabilities of the dialog are based on multiple files in your project, some of which are generated on-demand.

TOC
The overall layout of the TOC is stored in the Help\Settings\topics.xml file. This file does not exist until a conceptual topic is created or imported into the TOC and the changes are saved. You can create this file manually if necessary. It contains a hierarchy of topic elements that each specify a unique ID, whether the topic should be excluded, and the path to the topic's file, which is relative to the Help\Topics folder. A placeholder for the auto-generated reference TOC may also be included as an stoc element.

Filters
Dynamic filters on the Saved Filters tab are stored in the Help\Settings\dynamicFilters.xml file. This file does not exist until a filter is added or imported and the changes are saved. You can create this file manually if necessary, but letting the UI create it is recommended.

The checked state of auto-generated reference topics corresopnds to the apiFilter configuration element in Sandcastle's MRefBuilder.config file, which is included as a project item in the Presentation\Style\Configuration folder. You can also edit the configuration file manually if necessary.

When the dialog is opened
When you open the dialog it may take some time to fill the auto-generated reference topics under the Namespaces node, so a temporary placeholder exists and the dialog remains responsive to user interaction. In the background, DocProject is using the Sandcastle build engine to build the TOC and filling the tree with topic nodes.

Note: Auto-generated reference topics are only available when the project has one or more sources, which can be external or project references. Without sources the Namespaces node will not be shown.

Basically, all of the steps up to the Build Assembler are executed in the background. The toc.xml and reflection.xml files that are created by the Sandcastle build steps are then parsed into the tree nodes. The toc.xml file is used for the layout of the tree and the reflection.xml file provides most of the information used to construct each topic node. And for each topic node a look-up into the existing apiFilter configuration section of the MRefBuilder.config file is performed to discover whether the topic should be included or excluded, by default.

Creating the nodes and populating the tree can take a while for large projects, so please be patient.

Saving the Changes

Clicking OK on the Topic Management dialog doesn't apply the changes, it only commits them to memory. This allows you to edit the Topic Management dialog multiple times before you finally save your changes to disc. If you open the Topic Management dialog again after clicking OK, but click Cancel instead, then you will only cancel the changes that you just made and not the changes for which you already clicked OK. Finally, clicking OK on the Options dialog will commit your changes to the project level, but they still will not be persisted to disc until the DocProject or DocSite is saved by clicking Visual Studio's Save All tool bar button or menu item.

DocProject writes directly to the MRefBuilder.config file, overwriting any existing configuration of the apiFilter element. Other elements and content in the configuration file remain unmodified.

The dialog attempts to serialize as little as possible to the MRefBuilder.config file by determining whether child topics will automatically inherit visibility from their parent topic and uses the expose attribute appropriately.

Last edited Jun 11, 2008 at 2:46 AM by davedev, version 6

Comments

No comments yet.