MAML: How to link to a top identifier in a <para> element?

Topics: Sandcastle
Jun 19, 2008 at 12:21 PM
In a <para> element, how do you link to a topic identifier? None of the intellisense options that pop up seem to be applicable, in particular <link> which would seem to be an obvious candidate.

Thanks,

Mike
Jun 19, 2008 at 1:45 PM
Hi Mike,

Most of the MAML temlpates that DocProject provides (when you use Topic Explorer to create a new topic) have link examples in the relatedTopics section.

You can generate links to other topics automatically by right-mouse clicking the target topic in Topic Explorer and selecting Copy as conceptual link.  Then simply paste the link into your topic.

If you want to link to another conceptual topic you must use the link element as follows (this is what Copy as conceptual link generates): 

<

link xlink:href="2BFD9215-1216-403d-8C46-8420A4D01B83"/>

where the value for the xlink:href attribute is the GUID for the target topic.

FYI, here's the info that's provided in the templates: 

<!-- Supported Link Types

   All of the following linking mechanisms may be used in the topic's content 
   as well as in the related topics section.

Linking to API reference documentation: 

  <codeEntityReference>API reference ID</codeEntityReference>

Linking to external resources and custom HTML topics: 

  <externalLink>
    <linkText>  Required hyperlink text  </linkText>
    <linkAlternateText>  Optional link title  </linkAlternateText>
    <linkUri>  Required URI  </linkUri>
  </externalLink>

Linking to other conceptual topics: 

  <link xlink:href="GUID topic name (without file extension)" />
  
Linking to named references:

  (Refer to the project's Help\Settings\links.xml file for more information)

  <link xref="id"> Optional link text </link>
  <link vref="id or URI"> Optional link text </link>
  
-->

<!-- Example Usage -->

<codeEntityReference>T:MyNamespace.MyClass</codeEntityReference>
<codeEntityReference>P:MyNamespace.MyClass.MyProp</codeEntityReference>
<codeEntityReference>M:System.IO.File.OpenText(System.String)</codeEntityReference>

<externalLink>
  <linkText>Sandcastle Styles</linkText>
  <linkAlternateText>Sandcastle Styles on CodePlex</linkAlternateText>
  <linkUri>http://www.codeplex.com/SandcastleStyles</linkUri>
</externalLink>

<externalLink>
  <linkText>Change Log</linkText>
  <linkUri>ChangeLog.html</linkUri>
</externalLink>

<link xlink:href="2BFD9215-1216-403d-8C46-8420A4D01B83"/>

<link xref="home">Our Home Page</link>
<link vref="/controls/design.aspx">Control Architecture</link>

- Dave

Jun 19, 2008 at 2:56 PM
Thanks.
Jun 25, 2008 at 12:50 PM
Hi, Dave.

How to make a link in a conceptual topic pointing to a section in another conceptual topic?

Thanks for your time.

[]'s,

Sérgio Ciglione
Jun 25, 2008 at 2:43 PM
Hi Sergio,

You need to set a value for the address attribute on the section element (or any other element that supports address) and a bookmark anchor will be generated automatically.  Then you can link to the topic and its bookmark using the externalLink element by appending #value of address to the end of the linkUri value.

Alternatively, I think Eric Woodruff has created a custom ResolveConceptualLinksComponent that allows you to use #value of address in typical link elements instead, which you may find better than using externalLink.  His custom component may be available as a seperate download from SHFB (Sandcastle Standalone Build Components), along with a few other custom components, but I'm not sure.  (I haven't tried using it myself but I know that others have had success with Eric's components in DocProject.)  See the following article for help.
 
How to Use Third-Party Build Components in DocProject
http://www.codeplex.com/DocProject/Wiki/View.aspx?title=How%20To%20Use%20Third-Party%20Build%20Components%20in%20DocProject

- Dave
Jun 25, 2008 at 6:48 PM
Thanks, Dave.