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

.
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.
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.
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.
Figure 3: Topic Explorer 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 FilesRenaming 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:
- Change the file name of the conceptual topic in the Help\Topics folder.
- 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.
- 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.
- 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.
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 onlyChecked 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 topicsEnable 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 topicsThis 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 accessibilityBy 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 FiltersFilters 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 FiltersYou 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

and use the dialog to browse to your custom filters.
Inheritance FilterA 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 FiltersFilters 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 FiltersThe
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 FiltersClicking 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 FiltersAll 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.
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.
TOCThe 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.
FiltersDynamic 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 openedWhen 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.