Sandcastle documentation xml code example displaying without carriage returns

Question

I'm using sandcastle to document at web service API and to summarys and remarks to the top level Namespace I've add a sandcastle.xml file to my project.

My problem is when I try and add a xml example code to the namespace remarks section in that xml file sandcastle renders the xml code all on one line without any of the carriage returns.

<member name="N:BrokerServices.GatewayAsmx">
    <summary>summary text</summary>
    <remarks>
        remarks text
        <example>
               Sample xml code              
               <code lang="xml">
                <Membership>
                    <firstname>Cliff</firstname>
                    <lastname>Mayson</lastname>
                    <age>27</age>
                </Membership>
            </code>
        </example>
    </remarks>
</member>

The resulted rendered code example displays as:

<Member><firstname>Cliff</firstname><lastname>Mayson</lastname><age>27</age></Member>

I've tried using \n or \r which work but the \n and \r characters are left in the code example:

<Member><firstname>Cliff</firstname>\n
    <lastname>Mayson</lastname>\n
    <age>27</age>\r
</Member>

How do I insert new lines without the new line characters show in the code.

Answer 1

When the code tag's language attribute is xml you need to add xml:space="preserve" attribute to the tag for the xml example to render correctly.

eg.

<member name="N:BrokerServices.GatewayAsmx">
    <summary>summary text</summary>
    <remarks>
        remarks text 
    </remarks>
    <example>
        Sample xml code             
        <code lang="xml" xml:space="preserve">
            <Membership>
                <firstname>Cliff</firstname>
                <lastname>Mayson</lastname>
                <age>27</age>
            </Membership>
        </code>
    </example>
</member>

This is not necessary if the code tag's lang attribute value is c# or VB

Answer 2

1st option: replace the < characters with <.
2nd option: put your XML code into a <![CDATA[ ... ]]> block.
3rd option: you can also use alternative tool like ForgeDoc :)

One more thing: don't put example blocks into the remarks section. Example is a top-level tag.