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

Formatted text in documentation (carriage return and spaces)

Topics: Questions
Aug 21, 2013 at 11:17 AM
Hello,

If the XSD documentation text has carriage returns and white spaces, those gets lost when documentation is created using Schema Documenter/SandCastle. Can anybody help how to get it to retain carriage returns? I have tried putting <br/> tag in the text, but it did not help. I also tried extending AnnotationTransform.xslt such that each newline ends with </br> tag. That did not help either.

If the annotation in XSD is follows:
<xs:annotation>
    <xs:documentation>
        This is Schema Description.
        This is second line.
        This is third line.
        This is fourth line.
    </xs:documentation>
</xs:annotation>
We would like the output help file/html to retain the text as multiline. We CAN modify text in XSD also and add additional information if that is required to achieve this.

Thanks for all help and inputs.
Raj
Coordinator
Aug 31, 2013 at 9:18 PM
Edited Aug 31, 2013 at 9:30 PM
XML schema files have two different annotation elements: xs:annotation and xs:appinfo. The annotation element is for human readable text and the convention is pretty much to use plain text for this element. As such, it doesn't really support pre-formatted content, such as line breaks. Most tools will simple collapse all whitespaces and remove line breaks.

The app info element is meant for machine readable annotations and can contain abitrary XML. XML Schema documenter will look for a schemaDoc element from the namespace http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3. You can use this element to get structured documentation.

For example, this schema annotation
<xs:annotation>
  <xs:documentation>
    The first line.
    Another line.
  </xs:documentation>
  <xs:appinfo>
    <sd:schemaDoc>
      <ddue:summary>
        <ddue:para>
             This is the summary.
        </ddue:para>
      </ddue:summary>
      <ddue:remarks>
        <ddue:content>
          <ddue:para>
            This is the first paragraph.
          </ddue:para>
          <ddue:para>
            This is another paragraph.
          </ddue:para>
          <ddue:code>
            This is code.
          </ddue:code>
          <ddue:alert class="note">
            <ddue:para>This is a note.</ddue:para>
          </ddue:alert>
        </ddue:content>
      </ddue:remarks>
    </sd:schemaDoc>
  </xs:appinfo>
will render like this:

Image

Please note that the summary element only supports a single para element. This is a limitation in the XML documentation used by Sandcastle called MAML. For more details on MAML have a look at Eric's MAML Reference.

For more details on XML Schema documentation, have a look at xsddoc's help file that you can find here:
%ALLUSERSPROFILE%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\XML Schema Documenter\Help.chm
In particular, have a look at Documenting | Inline Documentation.

Does this help?
Marked as answer by terrajobst on 2/15/2014 at 6:13 PM