This project has moved. For the latest updates, please go here.

Links from MAML

Topics: Questions
Nov 15, 2009 at 7:53 AM
Edited Nov 15, 2009 at 8:50 AM

Hi,

First, thanks for making this plug-in available. Apart from the issue described below, it does everything we need at this time, and should save us a huge amount of reengineering as we move our documentation to MAML.

What I haven't been able to do is format the text links produced by xmlEntityReference, or to override the text of the link. Can anyone give me any pointers as to how I might do this?

I'm looking for the equivalent of:

<relatedTopics>
<link xlink:href="577784a9-06c5-480b-8804-8e3754998b01">My specified text</link>
</relatedTopics>

Thanks,
Bruce

Coordinator
Nov 15, 2009 at 10:29 AM
fnqbruce wrote:

First, thanks for making this plug-in available. Apart from the issue described below, it does everything we need at this time, and should save us a huge amount of reengineering as we move our documentation to MAML.

Thanks, I am glad to hear that!

What I haven't been able to do is format the text links produced by xmlEntityReference, or to override the text of the link. Can anyone give me any pointers as to how I might do this?

I am sorry but this is not possible. Orginally, Sandcastle and MAML itself did not support overriding the text in the link element. This is an SHFB feature. The MAML documentation for the link element states that:

The link element can contain text but this text is discarded at build time in favor of the actual title of the link target, so the text in this element is not localizable.

So one could argue that this is a feature. The xmlEntityReference intentionally uses the inner text for the XML entity's fully qualified name instead of using an attribute - this makes it similar to the syntax of codeEntityReference that can be used to reference manged code elements.

Why do you want to change the link text?

The original mail notification from Codeplex inlcuded a different question from you. But apparently you already found the answer. But to be sure it is documented for other people let me also answer this question:

What I can't work out how to do is reference any of the generated pages from MAML elsewhere in a SHFB project (i.e. in files other than NamespaceDoc and SchemaSetDoc). I've tried <xmlEntityReference>, as in <xmlEntityReference>http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport</xmlEntityReference>, but it fails to be recognized.

You are using the correct element but the namespace is incorrect. The XSD Documenter elements reside in a different namespace. To use them in regular MAML you have to declare the namespace. I would recommened adding them on the document root element (e.g. developerConceptualDocument) right under the topic element. I prefer using the alias xsd but of course you can use anything else:

<?xml version="1.0" encoding="utf-8"?>
<topic id="e30e87fa-d0a1-46fd-b445-a0ac489c11f3" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
                               xmlns:xlink="http://www.w3.org/1999/xlink"
                               xmlns:xsd="http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3">
    <introduction>
      <para>This topic shows how to link to a XSD element.</para>
    </introduction>
    <section>
      <title>What this Sample Shows</title>
      <content>
        <para>This samples shows the following features of XML Schema Documenter:</para>
        <para>
          <xsd:xmlEntityReference>http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport</xsd:xmlEntityReference>
        </para>
      </content>
    </section>
    </section>
    <relatedTopics>
    </relatedTopics>
  </developerConceptualDocument>
</topic>

 

I can't use a guid, as this changes with each build.

If this is the case please file a bug. The guids should remain stable as long as the XML entities original fully qualified name (such as http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport) does not change because the guid is from its MD5 hash (Sandcasle uses the same approach).

Hope this helps.

Kind regards,
Immo Landwerth

Nov 16, 2009 at 1:21 AM

Thanks for your help.

terrajobst wrote:
Why do you want to change the link text?

 I'd like to differentiate in the relatedTopics section between a class name (from an codeEntityReference) and an XML element with the same name (from a xmlEntityReference). Something like:

Thing Element (XML Schema)
Thing

In in-line links this isn't a problem, because I can say something like:

<para>
  See the <xsd:xmlEntityReference>http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport</xsd:xmlEntityReference> element.
</para>

But in the relatedTopics section, the surrounding text is cleared out, and only the element and its inner text are used.

Another solution would be to have the XML Reference topic type appear in a separate section from other Reference topic types in the relatedTopics list, but I imagine that that would require work deep inside sandcastle, which is beyond my capabilities.

In the meantime, I can work around the problem by using the <link> "feature".

I can't use a guid, as this changes with each build.

If this is the case please file a bug. The guids should remain stable as long as the XML entities original fully qualified name (such as http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport) does not change because the guid is from its MD5 hash (Sandcasle uses the same approach).

 

My mistake, sorry. My testing was at fault.

Thanks again for all your help.

Bruce

May 7, 2013 at 3:08 PM
In the example:
<para>
See the <xsd:xmlEntityReference>http://conqat.cs.tum.edu/ns/clonereport#E/cloneReport</xsd:xmlEntityReference> element.
</para>
how do you construct the URI? Which part is the namespace, the schema name, etc? Does #E/cloneReport translate to the cloneReport element?

Is it #A for attributes and #T for types?

Have I missed some documentation somewhere?
Coordinator
Aug 31, 2013 at 9:35 PM
Edited Aug 31, 2013 at 9:35 PM
The link syntax is documented in xsddoc's help file which can be found here:
%ALLUSERSPROFILE%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\XML Schema Documenter\Help.chm
The topic is Documenting | Linking.
Marked as answer by terrajobst on 2/15/2014 at 6:14 PM