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">
<para>This topic shows how to link to a XSD element.</para>
<title>What this Sample Shows</title>
<para>This samples shows the following features of XML Schema Documenter:</para>
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.