Reusing Reference Content

In This Topic

If you are authoring content for reference documentation items, you may find that the same content is usable in several places. There are several ways in which you can minimize duplication by re-using content associated with reference documentation items:

For .NET method or property overrides, use the content from the base member

If you have an overriden member for which the base documentation content is valid, you can tell Document! X and HelpStudio to use the base member content rather than duplicating the content.

To automatically use the base member content for all overriden members that don't have any specific content defined:

Open the Build Profile Editor;
Select the .NET Source Comments page;
Tick the For overriden members without content, use the content from the base member option;
When you build your documentation, overriden members without any specific content will automatically use the content from the base member.

To use the base member content just for a specific overriden member:

In the Content File Editor, select the override member;
Select the Content From Content Item Type (either from the toolbar or page menu on the right hand side of the Content File Editor);
Click the New toolbar button to create a new Content From item;
Leave the Copy content from field blank - Document! X and HelpStudio will automatically use the content from the member in the base type.

You can also do this for specific override members in a .NET Xml source comment by using an <inheritdoc/> or <contentfrom/> comment. An <inheritdoc/> comment applied to a type will apply this behavior to all overrides in that type.

For .NET documentation, automatically use the content from inherited members

For members inherited from types that are contained in assemblies within the current project, Document! X and HelpStudio will automatically use the content defined for the inherited member in the base type - that behavior is always enabled.

For members inherited from types that are contained in assemblies that are not included in the current project, including .NET Framework assemblies, Document! X and HelpStudio can use the content (contained in xml comment files) from the member as defined in the base type by enabling a specific option in the Build Profile Editor.

To enable using content from other assemblies for inherited members:

Open the Build Profile Editor;
Select the .NET Source Comments page;
Tick the Find and integrate XML Documentation for members inherited from other assemblies option;

Use the Content From Content Item Type to use content from another item in the project

You can use the Content From Content Item Type to specifically identify another item from which you would like to use the content when the generated documentation is built.

In the Content File Editor, select the item in which you would like to re-use another items content;
Select the Content From Content Item Type (either from the toolbar or page menu on the right hand side of the Content File Editor);
Click the New toolbar button to create a new Content From item;
Click the Build button and identify the source item that contains the content you would like to re-use.

When the documentation is built (or when you Preview in the Content File Editor) the content from the identified source item will be used.

You can use the Filter list in the Content From editor to specific particular parts of the content to re-use. For example you might want to use just the summary content, or just the Examples.

Define a Project Property for short pieces of common content

If you have a short phrase or description that you want to make use of in several locations, you can define a Project Property to contain the text so that you can avoid duplication and are able to manage that text in one place.

To create a Project Property:

Click the Project Settings button on the Project Ribbon Tab;
Select the Project Properties page;
Click the New toolbar button to create a new Project Property;
Give the Project Property a name and optionally a description. You will use this name to reference the Project Property in your content;
Click Ok to save the new Project Property;
Click the ... button next to the newly created Property Property to define the value associated with the Project Property (e.g. the text you want to use in multiple locations in your content);
You can now reference the Project Property anywhere in the content editors by surrounding the Project Property name with %% symbols - e.g. %%MyProjectProperty%%. The placeholder will be replaced with the Project Property when you Preview a page or build the project.

If you are generating multiple outputs, you can define different values for your Project Property in each Build Profile using the Project Properties page in the Build Profile Editor.

Create a Content Snippet containing content you want to use in several places

Content Snippets are named chunks of Html content that are defined in one place and included in many places in your project content.

Content Snippets are a good alternative to using Project Properties if your re-usable content contains Html as the Content Snippet editor provides all of the functionality of the Topic Editor, including Widgets, Table Editing, Link designer etc.

To create and use a Content Snippet:

In the Content Snippets window, right click the root Content Snippets node;
Select New Content Snippet from the context menu;
When prompted, define a Name for the new Content Snippet;
The new Content Snippet will be opened for edit and will appear in the Content Snippets list;
Open the Topic or Content File into which you would like the Content Snippet included;
Right click in the content editor at the position you wish to insert the Content Snippet and select Insert Content Snippet from the context menu.

Applying content to multiple items automatically by creating an AutoDoc file

AutoDoc is a powerful Document! X feature that allows you to author content that is used in the generated output according to rules that you define. For example you might want to author some specific remarks for inclusion in every method with a particular name in order to prevent duplicating the same content in many places.

See the AutoDoc Topic for more information on creating and using AutoDoc files.