Referring a content topic by GUID from C# XML comment

Topics: User Forum
May 28, 2010 at 11:52 AM

Hello,

I wonder what's the equivalent of the following MAML tag in C# XML comment:

<link xlink:href="10023a1a-c4c1-4d1a-b307-f49a2e39cdb0"/>

I am looking for a construct that would be auto completed by the topic name, as is the case with the <link/> tag.

Thank you.

-gael fraiteur

Coordinator
May 28, 2010 at 7:45 PM

There isn't any support for linking to a MAML topic from XML comments right now.  However, you can use a regular HTML anchor tag in the XML comments.  Since reference topics end up in the same folder as the conceptual topics, all you need for the href is the conceptual topic's GUID with a ".htm" extension:

/// For more information see <a href="10023a1a-c4c1-4d1a-b307-f49a2e39cdb0.htm">the conceptual topic</a>.

In theory, I suppose its possible that you could include the necessary component to resolve such links as long as the data files for the content were present.  I'll look into it if I get some time.

Eric

 

Jun 1, 2010 at 7:23 AM

Thank you.

Jul 9, 2010 at 12:00 AM

Eric,

Your suggestion for linking from C# XML comment to MAML content doesn't work in MS Help Viewer help files (but it works for HTML Help 1).  Is there a way to link that works for both HTML Help 1 and MS Help Viewer?

Thanks,

hugues

Coordinator
Jul 9, 2010 at 2:19 AM

The two formats use distinct link styles.  MS Help Viewer needs the ms-xhelp style links.  Without using the resolve conceptual links component I don't think there's a way to get them to work for both help file formats.

Eric

 

Jul 9, 2010 at 6:43 PM

I'm afraid I'm gonna need some help setting up the resolve conceptual links component.  I've tried the following, which does NOT work:

In the SandcastleBuilder.components file, Under

<component id="Resolve Conceptual Links">

after

<insertConceptual placement="replace" type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent" />

I have inserted
<insert placement="after" type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2" />

and my xml comments in my documented assembly look like this:

/// <summary>
/// My summary text.
/// </summary>
/// <remarks>
/// Here's a link that only works in .chm: <a href="d8da653d-64e4-4a0f-bee5-130050afa00a.htm">LINK 1</a>.
/// Here's a link to another type in the same assembly: <see cref="T:MyNamespace.MyType"/>.
/// Here's a link that shows up as text <link xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="d8da653d-64e4-4a0f-bee5-130050afa00a">LINK 3</link>.  
/// </remarks>

The "LINK 3" is displayed as regular text.  I know the guid is correct (in fact it works for link 1 for .chm).  If I omit the namespace declarations, I lose both the summary and the remarks.  I've tried scheduling "before", but that didn't help.

 

Coordinator
Jul 9, 2010 at 7:23 PM
Edited Jul 9, 2010 at 7:24 PM

That particular component is already built into the SHFB conceptual configuration so it's hidden from the project's ComponentConfigurations property.  Since it isn't currently used in the presentation style configuration files, it would have to be added manually to those configuration templates.  However, since it typically isn't used in a reference build, I can't say for sure whether or not it actually works.  I'd need to do some testing first.

Eric

 

Jul 9, 2010 at 8:00 PM

Thanks.  I'll look forward to that.  Linking from reference to conceptual is pretty important to us.

Mar 31, 2011 at 1:46 PM

I'm using the technique described in this thread to link from API -> Conceptual topic content, and after testing my first MS Help Viewer build, I have the same problem as huguesy (the links don't work because they don't have the correct preamble stuff:

The source XML includes links like this:

<a href="3b98d745-226d-417c-ac82-cf2fcda8df72.htm">scoring function</a>

The generated MS Help Viewer page includes a link like this:

http://127.0.0.1:47873/help/1-3840/3b98d745-226d-417c-ac82-cf2fcda8df72.htm

When it needs to look like this:

http://127.0.0.1:47873/help/1-3840/ms.help?method=page&id=3B98D745-226D-417C-AC82-CF2FCDA8DF72&topicversion=100&topiclocale=EN-US&SQM=1&product=VS&productVersion=100&locale=EN-US

Is there a method that will enable this type of link to work in all build types? 

Thanks as always!

Ed

Coordinator
Apr 8, 2012 at 1:23 AM

In case anyone comes across this topic in the future, the next release of SHFB (v1.9.4.0) and Sandcastle (2.7.0.0) will support the use of <conceptualLink> elements within XML comments to link to MAML topics from API topics.  By using <conceptualLink> elements, the links will work properly regardless of the help file format.  Here's an example:

/// <remarks>For more information, see the <conceptualLink target="041d7ee8-1698-4256-aa9b-507c1b366cf6" /> topic.
/// This link has <conceptualLink target="4e92303d-66ad-4a5d-9a03-94f316a0dd38">inner text</conceptualLink>.</remarks>

 

Eric

 

Apr 9, 2012 at 12:31 PM

Excellent! Looking forward to the update.

Thanks!

Ed