How does the 'address' attribute work

Apr 1, 2008 at 3:53 PM
I'd like to be able to provide links to locations in the middle of topic pages instead of the top of the page. It seems like the 'address' attribute is designed to do this but I can't figure out how to hook it up. Is this what this attribute is designed to do and if so how do you configure it to work? If it is not designed to do this is there another way to link to a position in the middle of topic page?
Apr 1, 2008 at 8:32 PM
Hi,

I've just investigated the address attribute and it appears to do exactly what you expected, and a bit more.

It seems that you can use address on the introduction and any section elements to define named anchors. Check out utilities_dduexml.xsl to see the template that matches @address and main_conceptual.xsl to see where it is applied.

You can use the bookmarks in external links that point to your topics since a normal anchor is created: <a name="the value of @address"/>Collapsible Introduction or Section...

I discovered an autoOutline feature that's pretty cool as well, although the comments claim a different usage than I've found to actually work. The comments are located in main_conceptual.xsl near the bottom:


Inserts a bullet list of links to the topic's top-level sections or a section's subsections.
Authors can insert <token>autoOutline</token> in a topic's introduction to get a bullet list of the top-level sections;
or in a ddue:section/ddue:content to get a bullet list of the section's subsections.
The shared content component replaces <token>autoOutline</token> with an <autoOutline/> node.

The shared content component doesn't do what the comment says it does. But I found that you can simply add <autoOutline xmlns=""/> manually and it works.

There also appears to be some built-in addresses, but I haven't figured out what they are for yet. Just do a global search in Visual Studio for @address and you'll find them in a few different XSL transformations.

Here's a MAML topic that works using the address attribute and the <autoOutline/> element.

<?xml version="1.0" encoding="utf-8"?>
<topic id="af335e2a-404b-4b2b-b3af-2141dde33425" revisionNumber="0">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
                               xmlns:xlink="http://www.w3.org/1999/xlink">
    <introduction>
      <autoOutline xmlns=""/>
      <para>Required Introduction</para>
    </introduction>
    <section address="example1">
      <title>Example section 1</title>
      <content>
        <autoOutline xmlns=""/>
        <para>The first section.</para>
        <para>
          Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the 
          source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the 
          following key features.
        </para>
      </content>
      <sections>
        <section address="subsection1">
          <title>Example subsection 1</title>
          <content>
            <para>The first subsection.</para>
            <list class="bullet">
              <listItem><para>Works with or without authored comments.</para></listItem>
              <listItem><para>Supports Generics and .NET Framework 2.0.</para></listItem>
              <listItem><para>Sandcastle has 2 main components (MrefBuilder and Build Assembler).</para></listItem>
              <listItem><para>MrefBuilder generates reflection xml file for Build Assembler.</para></listItem>
              <listItem><para>Build Assembler includes syntax generation, transformation, etc.</para></listItem>
              <listItem><para>Sandcastle is used internally to build .Net Framework documentation.</para></listItem>
            </list>
          </content>
        </section>
        <section address="subsection2">
          <title>Example subsection 2</title>
          <content>
            <para>The second subsection.</para>
            <para>
              Some text to fill up space in the second subsection.
            </para>
          </content>
        </section>
      </sections>
    </section>
    <section address="example2">
      <title>Example section 2</title>
      <content>
        <autoOutline xmlns=""/>
        <para>The second section.</para>
        <para>
          Some text to fill up space in the second section.
        </para>
      </content>
      <sections>
        <section address="subsection3">
          <title>Example subsection 3</title>
          <content>
            <para>The first subsection.</para>
            <para>
              DocProject is an open source help authoring tool (HAT) that consists of Visual Studio Project Templates, 
              an Add-In and an API that provide an extensible platform for authoring, managing and building compiled 
              help in various formats.
            </para>
          </content>
        </section>
        <section address="subsection4">
          <title>Example subsection 4</title>
          <content>
            <para>The second subsection.</para>
            <para>
              The latest version of Microsoft Sandcastle is used to generate HTML help topics for conceptual 
              documentation and auto-generated reference documentation for managed assemblies in various presentation 
              styles, such as one that looks like the documentation for Visual Studio and the Microsoft .NET Framework. 
              DocProject also automates HTML Help compilers to produce Help 1.x (.chm) and Help 2.x (.HxS) output in 
              a single build.
            </para>
          </content>
        </section>
      </sections>
    </section>
    <relatedTopics>
    </relatedTopics>
  </developerConceptualDocument>
</topic>
Apr 1, 2008 at 11:07 PM
Thanks, that worked like a champ. I like the autoOutline feature as well. I was using GUID as address strings and they happened to begin with a number which I guess invalid. Also it doesn't seem to like it if you put a space in the address string.

Kevin
Apr 2, 2008 at 12:46 AM
Hi Kevin,

Thanks for the tips. I wonder though if that has something to do with the browser more than it does Sandcastle. We could examine the XSL to find out...

- Dave
Apr 2, 2008 at 6:13 PM

To be more clear, strings that begin with numbers or have spaces violate the xsd definition. The Visual Studio xml editor underlines these with the little blue squiggly lines. Because of this I assumed there was some specific format I needed for the address attribute and didn't bother to build to see if it actually worked. I have tried since and it does seem to work as long you don't mind the schema violation.

I have another issue though, the links worked great with the autoOutline feature, however I can't seem to figure out how to link things up in other topics. For instance I added your example topic above to my project and tried to link to the 'example1' section from one of my topics using this syntax <link xlink:href="example1">Does it work</link> and all that appears in the help file is [example1].
Apr 2, 2008 at 7:40 PM
Edited Apr 2, 2008 at 7:42 PM
Hi Kevin,

Thanks for clearing that up.

As for the other issue, the link that you've tried doesn't identify the topic, so I don't see how it could work. (I assume that you can use the same address in different topics.)

Here's a few things that I just tried:

<content>
  <para>
    <externalLink>
      <linkText>This works.</linkText>
      <linkUri>af335e2a-404b-4b2b-b3af-2141dde33425.htm#example1</linkUri>
    </externalLink>
  </para>
  <para>
    <link xlink:href="af335e2a-404b-4b2b-b3af-2141dde33425#example1">
      This doesn't work.
    </link>
  </para>
  <para>
    <link xlink:href="af335e2a-404b-4b2b-b3af-2141dde33425">
      This works, but it doesn't contain a bookmark.
      (The text will be replaced with the topic's title, automatically.)
    </link>
  </para>
</content>
The first example works fine. Notice that you must use the file name, not the topic ID.

- Dave