link to a source topic from conceptual topic

Topics: Conceptual Topics, General Questions
Nov 18, 2008 at 6:17 AM
How do I link from a conceptual html topic to a source code documentation topic (such as a class, a member or a namespace) ?
Coordinator
Nov 18, 2008 at 11:32 AM
Hi,

In MAML topics use the codeEntityReference element.  For example:

    <codeEntityReference>P:MyNamespace.MyClass.MyProp</codeEntityReference>

The quickest way to do this is to find the node in Topic Explorer, right-click and select Copy as conceptual link.  Then just paste it into your topic.

Additional usage examples are provided in the relatedTopics section of the MAML templates that ship with DocProject.  The templates are used when you add a new conceptual topic to the project via a button on the Topic Explorer toolbar.

For more information on MAML download the MAML guide from the Sandcastle Styles project.
To enable IntelliSense for MAML read How To Enable IntelliSense in Conceptual Topics.



In raw HTML conceptual topics, use an anchor and specify the target API topic's file name in the href atttribute.

    <a href="760ff14f-1f70-1a61-a18e-1619fb7245db.htm">MyProp</a>

The file name that you must use depends upon the Use friendly HTML file names setting.  When false, a pseudo-GUID is used to identify each topic (it's actually an MD5 hash of the full API name in GUID format, so it doesn't change between builds.  The XSLT can be found at [Sandcastle Install Path]\ProductionTransforms\AddGuidFilenames.xsl).  When true, a name that is similar to the full API name is used (ProductionTransforms\AddFriendlyFilenames.xsl).

Topic Explorer does not currently offer any equivalent to the Copy as conceptual link command that is used for MAML topics.

To get the file name you must build the documentation first and then either find the target file in the output folder (Help\html or buildhelp\assembler\Output\html) or find the corresponding node in the buildhelp\assembler\reflection.xml file that has an id value that is the target API name and look at its <file name="..." /> attribute, which was added by one of the XSLT files mentioned above.  Assume that the file name always ends with a .htm extension and don't forget to specify the extension in the href attribute.

- Dave