Linking to Overloads

Feb 18, 2008 at 12:51 AM
Is there a way of linking to overloads with Sandcastle?

Back in the days of NDOC, I could do something like this:

<see href="Test.Info.ProgressTracker.Increment_overloads.html">Increment</see>

where Test.Info.ProgressTracker.Increment is a method with overloads. When the user clicked the link that was generated in the help file, the page that showed all the overloads for the method was shown. With Sandcastle, this doe not work, unless there is something additional I need to do. The reason appears to be that, unlike with NDoc, the HTML page that Sandcastle generates for the overloads has an arbitrary and unpredictable name, such as c2723e13-7a4b-c01c-0314-5ba748bc6c82.htm.

If there is not currently a workaround for this, might I suggest that a good future enhancement might be to revert to the naming convention for overloads pages that was used in NDOC?

Thanks.
Simon
Feb 18, 2008 at 1:07 AM
Hi Simon,

If you enable friendly HTML file names then your example will work. How to do that depends upon the tool you're using.

Note that the GUID file names are not arbitrary. They remain the same for a particular topic regardless of how many times you build. So technically, you could reference the overloads page with GUID file names too - you'd just have to figure out the GUID file name of the topic that you want.

Another way to reference an overloads page is to use the member ID without specifying any signature. For example:

<see cref="M:Test.Info.ProgressTracker.Increment" />
Note that it must be a cref link instead of href.

- Dave
Feb 18, 2008 at 1:23 AM
Hi Simon,

Sorry, but my last example wasn't correct. Instead of the M: prefix you'd have to use Overload:, although that doesn't work either because the C# compiler changes it. (I didn't try with VB though.)

I thought that it used to work like in my original example. Is this a regression bug or am I just dreaming?

- Dave
Feb 18, 2008 at 5:51 PM
Based upon this https://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1452885&SiteID=1 posting, I was able to modified the presentation transforms to add support for the O: prefex which converts to use Overload:. Here is the changed template in VS2005's main_sandcastle.xsl file (note, this feature was to be added to Sandcastle, but does not appear to be added yet):

<!-- MODIFIED TO SUPPORT O: FOR OVERLOADS AND CUSTOM TEXT FOR CREF -->
<xsl:template match="see@cref">"}
<xsl:choose>
<xsl:when test="normalize-space(.)">
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:', substring(@cref,3))}">
<xsl:value-of select="." />
</referenceLink>
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}">
<xsl:value-of select="." />
</referenceLink>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:', substring(@cref,3))}" />
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}" />
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:template>

<!-- MODIFIED TO SUPPORT O: FOR OVERLOADS -->
<xsl:template match="seealso">
<xsl:choose>
<xsl:when test="normalize-space(.)">
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:', substring(@cref,3))}" qualified="true">
<xsl:value-of select="." />
</referenceLink>
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}" qualified="true">
<xsl:value-of select="." />
</referenceLink>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<xsl:when test="starts-with(@cref,'O:')">
<referenceLink target="{concat('Overload:', substring(@cref,3))}" qualified="true" />
</xsl:when>
<xsl:otherwise>
<referenceLink target="{@cref}" qualified="true" />
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:template>

Feb 18, 2008 at 7:28 PM
Cool, thanks!

Note that when you specify external hyperlinks in this wiki they must be prefixed with url:, as in:

[url:https://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1452885&SiteID=1]

https://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1452885&SiteID=1
Feb 18, 2008 at 10:20 PM
Thanks for the tips. I'm using Sandcastle Help File Builder to control Sandcastle. I can't see how to enable friendly HTML file names in SHFB. My guess is that it is not supported directly by SHFB. In that case perhaps there is a way of doing it by manually editing a Sandcastle configuration file or something. Do you know anything about that?

I did wonder if those GUID file names stayed the same every time. Thanks for the clarification. However, I've got a lot of code documentation that links to overloads the old-fashioned way. So I would prefer to get friendly HTML file names working.

I'll probably give the third suggestion a go with the tweak suggested by dwhearn, though I would rather get the friendly HTML file names suggestion working if that is possible.
Editor
Feb 18, 2008 at 10:46 PM
Edited Feb 18, 2008 at 10:49 PM
To control how the files are named by SHFB, select the method using the NamingMethod property. You'll find it in the Help File category. See the help file for a description of the naming methods and how the friendly names are created.

Eric
Feb 19, 2008 at 1:37 AM
Thanks, Eric. I set NamingMethod to MemberName and sure enough the HTML pages are now generated with meaningful file names. They are not the same file names as NDOC used to generate. So I will still need to change all my links that reference overloads. That is OK. But what do I need to change them to?

I have tried several variations using the example I cited in my opening post as my test case. According to the generated Help 2 collection, the URL of the overloads page for the Increment method is:

ms-help://Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm

Based on that URL, I tried all of the following to reference the overloads page:

<see href="Overload_Test_Info_ProgressTracker_Increment.htm"}">Increment</see>
<see href="html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="ms-help://Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>

None of those worked.

Simon
Editor
Feb 19, 2008 at 2:51 AM
As noted, see the property help in the help file. It describes how it comes up with the names. As for how the links are rendered, it's based on the ProjectLinkType setting. If set to local, it renders all internal links as standard anchor tags (<a href='xxx'>). If set to Index, it renders them as mshelp:link keywords. <see href=> will always render as an anchor tag so if the link type is set to Index, they may not work. I haven't tested that to see if it's true though.

The first or second form would be the one's that work. You might try a Help 1 build to see if the links work (ProjectLinkType would have to be Local in that case).

Eric
Feb 19, 2008 at 11:16 PM
Edited Feb 19, 2008 at 11:17 PM
Hello Eric,

Thanks for the further suggestions.

Yes, I had read the documentation for the NamingMethod property. The names that would be generated according to that documentation match the names actually generated, as can be seen by checking the URLs in the generated help files.

I've just tried setting ProjectLinkType to Index for the Help 2 build. That did not make any difference. I've also tried a Help 1 build with ProjectLinkType set to Local. That did not work either.

For both types of builds I have also tried four additional variations on the see tag, as shown at the top of the following revised list of all the variations I have tested and none of which work in either the Help 1 build or the Help 2 build described above:

<see href="/Overload_Test_Info_ProgressTracker_Increment.htm"}">Increment</see>
<see href="/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="/Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="Overload_Test_Info_ProgressTracker_Increment.htm"}">Increment</see>
<see href="html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>
<see href="ms-help://Test.Info/Test.Info/html/Overload_Test_Info_ProgressTracker_Increment.htm">Increment</see>

Simon
Feb 26, 2008 at 2:27 AM
I've tried the solution explained by davedev and dwhearn. It works with just one line corrected in the main_sandcastle.xsl code given by dwhearn:

<xsl:template match="see@cref">"}

has to be replaced with

<xsl:template match="see[@cref]">

I expect that is what dwhearn intended, but it fell foul of WIKI markup. Thanks Dave and dwhearn for your help.

Simon