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

Include Additional Code in Annotation

Topics: Questions
Oct 18, 2010 at 11:46 AM

Hi,

 

I was wondering whether it is possible to include additional codeblocks in the annotation elements. I would like to include documentation in form of (x)html statements. and link to pictures etc. Is this possible? I haven't found a way out to get it working. 

 

Possible example would be something like: 

 

 <xsd:annotation>
  <xsd:documentation>
    <htm:table>
      <htm:tr>
        <htm:td>
          <htm:h3>Version:</htm:h3>
        </htm:td>
        <htm:td>
          <htm:h3>V1.3</htm:h3>
        </htm:td>
      </htm:tr>
      <htm:tr>
        <htm:td>
          <htm:h3>Date:</htm:h3>
        </htm:td>
        <htm:td>
          <htm:h3>2010-08-01T16:00:00</htm:h3>
        </htm:td>
      </htm:tr>
    </htm:table>
    <htm:div align="center" width="100%">
      <htm:table width="75%" style="border:1px solid #000000;">
        <htm:tr>
          <htm:td align="center">
            <htm:b>Axis</htm:b>
          </htm:td>
          <htm:td align="center">
            <htm:b>Direction</htm:b>
          </htm:td>
          <htm:td align="center">
            <htm:b>Description</htm:b>
          </htm:td>
          <htm:td align="center" rowspan="4">
            <htm:img width="100%" height="100%" src="images/axissystem.png" />
          </htm:td>
        </htm:tr>
        <htm:tr>
          <htm:td align="center">x</htm:td>
          <htm:td align="center">tailwards</htm:td>
          <htm:td align="center">from nose to tail</htm:td>
        </htm:tr>
        <htm:tr>
          <htm:td align="center">y</htm:td>
          <htm:td align="center">spanwise</htm:td>
          <htm:td align="center">from symmetry plane to the right wingtip</htm:td>
        </htm:tr>
        <htm:tr>
          <htm:td align="center">z</htm:td>
          <htm:td align="center">upwards</htm:td>
          <htm:td align="center">from landing gear to tip of vertical tailplane</htm:td>
        </htm:tr>
      </htm:table>
    </htm:div>
  </xsd:documentation>
</xsd:annotation>

Any help appreciated!

Daniel

Coordinator
Oct 24, 2010 at 7:12 PM
Edited Oct 24, 2010 at 7:14 PM

First of all I would like to apologize for the late reply.

Unfortunately, you cannot embedd HTML content in this way. Instead, XSDDoc supports MAML, the Microsoft Assistance Markup Language for providing additional content. See help file for details. You can find the help file in the installation folder which is

%ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\XML Schema Documenter

For documentation that lives directly in the XSD file, see section Documenting - Inline Documentation.

For example, to represent the HTML snippet you provided the following MAML code could be used:

<xs:annotation>
  <xs:appinfo>
	<sd:schemaDoc>
	  <ddue:summary>
		<ddue:para>
		  The summary for the documented item.
		</ddue:para>
	  </ddue:summary>
	  <ddue:remarks>
		<ddue:content>
		  <ddue:definitionTable>
			<ddue:definedTerm>Version</ddue:definedTerm>
			<ddue:definition>
			  <ddue:para>V1.3</ddue:para>
			</ddue:definition>
			<ddue:definedTerm>Date</ddue:definedTerm>
			<ddue:definition>
			  <ddue:para>2010-08-01T16:00:00</ddue:para>
			</ddue:definition>
		  </ddue:definitionTable>
		  <ddue:table>
			<ddue:tableHeader>
			  <ddue:row>
				<ddue:entry>
				  <ddue:para>Axis</ddue:para>
				</ddue:entry>
				<ddue:entry>
				  <ddue:para>Direction</ddue:para>
				</ddue:entry>
				<ddue:entry>
				  <ddue:para>Description</ddue:para>
				</ddue:entry>
			  </ddue:row>
			</ddue:tableHeader>
			<ddue:row>
			  <ddue:entry>
				<ddue:para>x</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>tailwards</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>from nose to tail</ddue:para>
			  </ddue:entry>
			</ddue:row>
			<ddue:row>
			  <ddue:entry>
				<ddue:para>y</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>spanwise</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>from symmetry plane to the right wingtip</ddue:para>
			  </ddue:entry>
			</ddue:row>
			<ddue:row>
			  <ddue:entry>
				<ddue:para>z</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>upwards</ddue:para>
			  </ddue:entry>
			  <ddue:entry>
				<ddue:para>from landing gear to tip of vertical tailplane</ddue:para>
			  </ddue:entry>
			</ddue:row>
		  </ddue:table>
		</ddue:content>
	  </ddue:remarks>
	</sd:schemaDoc>
  </xs:appinfo>
</xs:annotation>

The result looks like this:

Does this help?

Oct 26, 2010 at 12:43 PM
Thanks a lot, this helps a great deal. I spent the morning looking into the schemaDoc and I think it is very likely that I will be using it from the future on. I also saw there is a HTML to MAML Converter, I will try it out later. I am still not making my way to integrating pictures. 

Apparently MAML Documentation is still sparse. As far as I have found out the MediaContent file is generated by SHFB for Media I place in a folder with the same name. So how do I link pictures in the Schema?

This is the code from html

<htm:td align="center" rowspan="4">
    <htm:img width="100%" height="100%" src="images/axissystem.png" />
</htm:td>

In a SchemaDoc Element this would be something like?

<ddue:mediaLink>
    <ddue:image class="image" href="???"/>
    <ddue:summary>Try</ddue:summary>
</ddue:mediaLink>
I only found one example at http://www.help-info.de/en/Help_Info_AP_Help/longhorn_maml_example.htm
<mediaLink>
 <image class="image" xlink:href="help://microsoft.windows/?language=en-us&amp; version=6.0&amp;bundle=media&amp;topic=/images/carmen_img.jpg"     mimeType="image/jpeg" width="241" height="355">
 <summary>Carmen</summary>
</mediaLink>
Any small snippet can make me happy! 
Coordinator
Oct 27, 2010 at 1:32 AM
Edited Oct 27, 2010 at 1:35 AM

First of all, you may want to download the MAML Guide. It should contain enough information to get you started with MAML.

If you want to look at an example on how to use images you can look at the source of a help topic of the XSD Doc user interface. In MAML you either use mediaLinkInline or mediaLink. The mediaLinkInline element can be used anywhere where you would normally also have text, i.e. is inline within a paragraph. On the other hand, the mediaLink element is a block element that you can use anywhere where you can have paragraphs, tables or lists.

<mediaLinkInline>
   <image xlink:href="44dbb4b3-5b07-4741-9ba4-08bec8515856"/>
</mediaLinkInline>

The basic idea for images in MAML is to use a unique identifier instead of a path. Everything in MAML is reference by such an ID. As far as I remember, the identifiers for images can be any string as long as it is unique. However, I failed several times defining a consistent naming convention so I simply used GUIDs.

To add the image to the SHFB project and associate an ID with it, you simply add an image item to the project. In the property grid at the bottom of the project you can enter an ID for the image.

You can see the result in the SHFB project file of XSD Doc:

<Image Include="Media\DocFilePathsEditor.png">
   <ImageId>44dbb4b3-5b07-4741-9ba4-08bec8515856</ImageId>
</Image>

Does this help?

Marked as answer by terrajobst on 2/15/2014 at 6:15 PM
Oct 27, 2010 at 8:57 AM

It's working and looks nice!

As I was struggling with the IDs, changing the buildAction item in the properties window to Image did the change for my. It was set to Content and there was no entry for the ID..

Tanks again for your help.