Linking from reference to MAML and vice versa

Jul 25, 2008 at 11:27 AM
Hi,

I am looking for a way to link from reference documenation to MAML content and from MAML content to reference documentation. Is there a possibility to do this?

Of course I might use an external link, but this is quite annoying ... e.g., I would like to be able to link from MAML to reference documentation using something like link="T:Foo.Bar.MyMethod" or from reference to MAML using MAML's topic IDs ...

Is this possible?

Cheerio,


Golo
Jul 25, 2008 at 12:46 PM
Edited Jul 25, 2008 at 1:02 PM
>>Golo: Is this possible?

For  Conceptual to Reference use the <codeEntityReference>, with the following examples

1. For method use
<codeEntityReference>M:Foo.Bar.MyMethod</codeEntityReference>
you can use Overload:Foo.Bar.MyMethod if you want to to link to the overloaded page

2. For interfaces, classes, structure
<codeEntityReference>T:Foo.Bar</codeEntityReference>

3. For namespaces use
<codeEntityReference>N:Foo</codeEntityReference>

For the Reference to the Conceptual, use the <see> tag, with the MAML conceptual help topic ids.
NOTE: This last method is not robust, since it depends on the file extension of the MAML output file. But if you plan to generate only *.htm files this should not be a problem. Otherwise, we hope to provide a better way in the Sandcastle Assist Project effort with a new link component - not available yet.

Edited: I mean codeEntityReference not codeReference - sorry.

Best regards,
Paul.

Jul 25, 2008 at 5:16 PM
Hi Golo,

Check out the MAML guide for more information: 

http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=14068

- Dave
Jul 25, 2008 at 11:55 PM
Thanks for your replies :-)
Aug 11, 2008 at 6:23 AM
Is there a way to refer not to the namespace summary page, but to the root of the namespaces page?
Aug 11, 2008 at 9:43 AM

>>rhelliwellIs there a way to refer not to the namespace summary page, but to the root of the namespaces page?

If you mean the root container, then 

<codeEntityReference>R:Project</codeEntityReference> is not supported, I do not know if there is a work around
other than a adding it to the link component, ResolveReferenceLinksComponent2.
In  particular, the TargetCollection and LinkTextResolver, which has the NamespaceTarget, TypeTarget and MemberTarget
for resolving the namespaces, types and members.

Best regards,
Paul.

Aug 11, 2008 at 11:26 AM

Hi rhlliwell,

You can use an external link:

A link to the <externalLink>
  <linkText>Namespaces</linkText>
  <linkUri>d4648875-d41a-783b-d5f4-638df39ee413.htm</linkUri>
</externalLink> topic.

The GUID for the R:Project node never changes (and neither does any other topic GUID for that matter) so use the exact linkUri specified in my example.  (If you're not using GUID file names then you'll have to find the correct file name and use that instead.)

If you've applied the Sandcastle Styles patch an external link has the side effect of opening in a new window, but you can explicitly change that behavior using a linkTarget element: 

A link to the <externalLink>
  <linkText>Namespaces</linkText>
  <linkUri>d4648875-d41a-783b-d5f4-638df39ee413.htm</linkUri>
<linkTarget>_self</linkTarget> </externalLink> topic.

- Dave

Aug 11, 2008 at 6:28 PM
Thanks Dave. Yep that's exactly what I was after.
Roger