Examples element

Topics: Questions
Sep 15, 2011 at 2:43 PM
Edited Sep 15, 2011 at 2:45 PM

Hi all,

 

It took me some time to get familiar with how Sandcastle worked and espacially how to install the XML Schema Documenter plugin and have it working (a tutorial would be much welcome!!).

Anyway, I am now able to generate a nice html documentation from my xsd files and that is great.

 

However I am trying to have my examples nicely documented and I can't manage to have the Schema Documenter doing anything with it. The help file says it could be included in both schemaDoc or member, neither worked for me. I also tried with or without the ddue: namespace prefix but with no luck: the examples are always stripped out from the help files.

An extract of my XSDs:

 

<xs:simpleType name="LanguageCode">
		<xs:annotation>
			<xs:appinfo xml:lang="en">
				<schemaDoc xmlns="http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3"
             xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
					<ddue:summary>
					  <ddue:para>
						2 letters ISO language code.
					  </ddue:para>
					</ddue:summary>
					<ddue:remarks>
					  <ddue:content>
						<ddue:para>
						  If the language is not supported, the default language is used instead.
						</ddue:para>
					  </ddue:content>
					</ddue:remarks>
					<ddue:examples>
						en
					</ddue:examples>
				  </schemaDoc>
			</xs:appinfo>
		</xs:annotation>
		<xs:restriction base="xs:string">
			<xs:length value="2"/>
		</xs:restriction>
	</xs:simpleType>

 

The summary and remarks elements are properly transformed into nice html tables but <ddue:examples> disappears from the final output. I also tried with included content and para... nothing.

 

So... how the hell can we do anything with the examples element?

 

Thanks in advance,

 

Olivier

Coordinator
May 26, 2012 at 8:58 PM
Edited May 26, 2012 at 9:00 PM
choucrouteman wrote:

The summary and remarks elements are properly transformed into nice html tables but <ddue:examples> disappears from the final output. I also tried with included content and para... nothing.

So... how the hell can we do anything with the examples element?


Hi Olivier,

The problem is that the examples element isn't a standard MAML element but is proprietary to the XML Schema Documenter. Thus, you need to change the namespace. I'd simply change your XML fragment to something like this:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
    <xs:simpleType name="LanguageCode">
        <xs:annotation>
            <xs:appinfo xml:lang="en">
                <schemaDoc xmlns="http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3"
                           xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
                    <ddue:summary>
                      <ddue:para>
                        2 letters ISO language code.
                      </ddue:para>
                    </ddue:summary>
                    <ddue:remarks>
                      <ddue:content>
                        <ddue:para>
                          If the language is not supported, the default language is used instead.
                        </ddue:para>
                      </ddue:content>
                    </ddue:remarks>
                    <examples>
                      <ddue:para>
                        en
                      </ddue:para>
                    </examples>
                  </schemaDoc>
            </xs:appinfo>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:length value="2"/>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

Within the element, you can use the same MAML content as under the ddue:remarks/ddue:content element.

Does this help?

Thanks,
-Immo

Marked as answer by terrajobst on 2/15/2014 at 6:14 PM