 | Linking to Namespace Content |
The additional content help text may need to link to other topics in the help file such as help pages for a namespace, class, method, property, etc. To provide this ability, the help file builder will scan each HTML additional content file for XML comment style <see> tags. If found, an attempt is made to convert the tag to a link that takes you to the related help page for the indicated item. Some examples are shown below.
 Caution |
|---|
Deprecated The additional content model of adding extra content to a help file has been deprecated. While it will continue to be supported and will not be removed, it will not receive any more features or updates. Going forward, conceptual content is the preferred method of adding non-reference content to the help file. The additional content feature can still be used to override stock content and add supporting files to the help file. |
For a list of all classes, see the <see cref="N:SandcastleBuilder.Utils">SandcastleBuilder.Utils Namespace</see> topic. See the help for <see cref="SomeClass.DoesNotExist"/> for more information.
In this help file, these are rendered as:
For a list of all classes, see the SandcastleBuilder.Utils topic.
See the help for SomeClass.DoesNotExist for more information.
The first example uses the supplied inner text as the text for the hyperlink. The second example will use the cref value for the text of the hyperlink. The cref value can be a full or partial identifier for an item in any documented namespace as it appears in the reflection.xml file created by Sandcastle. The page names for the namespace items are generated at build time so the help file builder attempts to match the identifier with an entry in the reflection information XML file in order to obtain the correct filename as the target of the hyperlink. If a prefix is supplied on the identifier such as N: (namespace), T: (type), M: (method), etc. as shown in the first example, an attempt is made to find an entry starting with the identifier. If no prefix is supplied, as shown in the second example, an attempt is made to find a match that ends with the identifier. If neither of those returns a match, it searches for any entry that contains the identifier.
Messages are written to the log file indicating how the link was resolved. If no matches are found, a message appears in the log stating that the identifier could not be found and it will be rendered in bold rather than as a link in the help file as is the case with the second example. If a single best match is found, the log message indicates the fully qualified name that was matched and the tag is converted to a link to the associated page in the help file. If multiple matches are found, the log will include a list of all fully qualified names that contained the identifier and the first entry found will be used as the target of the hyperlink.
If a cref attribute appears in any other HTML tag, it will also be resolved and converted to an href attribute. For example, if you have an image map of a class, you could use cref attributes on the area tags to have them resolve to links to the classes represented by the image areas as in the following example.
<img src="images/TestClass.jpg" width="300" height="300" alt="TestClass" usemap="#TestClass" /> <map id="TestClass" name="TestClass"> <area shape="rect" coords="10,10,10,20" cref="TestClass.Method1" alt="Method1" /> <area shape="rect" coords="20,20,20,20" cref="TestClass.Method2" alt="Method2" /> <area shape="rect" coords="30,30,30,30" cref="TestClass.Method3" alt="Method3" /> </map>
See Also