Indentation of nested code tags including CDATA

Topics: User Forum
Jul 17, 2008 at 11:11 AM
Edited Jul 17, 2008 at 11:39 AM

Hello,

I would like to nest some code tags and CDATA in a <code lang="xml"> tag .
My purpose is to copy only some piece of xml from a web.config into my documentation in order to write an example.

Unfortunatelly, the output is not adequatly indented.
Here is my code tag:

/// <example>
/// <code lang="xml" title="How-to configure the Dummy Service">
/// <![CDATA[
/// <configuration>
///   <configSections>
///  ]]>
/// <code source="Dummy.Sample\Web.config" region="Dummy configSection"/>
/// <![CDATA[
///   </configSections>
///  ]]>
/// <code source="Dummy.Sample\Web.config" region="Dummy section"/>
/// <![CDATA[
/// </configuration>]]>
/// </code>
/// </example>

And here is the ouput:

        <configuration>
          <configSections>

<section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

          </configSections>

<dummy name="Dummy" value="Hello World"/>

        </configuration>

As you can see, the text from the CDATA tags and the code copied from the web.config are not indented adequatly.
The content of the code tag is aligned to the very left...

I am not sure if I have to use the CDATA tags but it was mentioned as useful when having literal xml in code blocks...
However, even if I remove these TAGS (and encode the < and > with &lt; and &gt;) it's also not correctly formated.
Here is the code tag modified without success:
/// <example>
/// <code lang="xml" title="How-to configure the Dummy Service">
/// &lt;configuration&gt;
///   &lt;configSections&gt;
///     <code source="Dummy.Sample\Web.config" region="Dummy configSection"/>
///   &lt;/configSections&gt;
///   <code source="Dummy.Sample\Web.config" region="Dummy section"/>
/// &lt;/configuration&gt;
/// </code>
/// </example>

Is there something that I could do to solve this ?

Thank you very much in advance for any tip!

Valery.

Coordinator
Jul 17, 2008 at 7:54 PM
The line with the least amount of indent determines the overall amount of leading indentation that gets stripped off of all the lines in the merged code block.  Since the imported snippets probably have less of an indent than the sample code in the CDATA sections in the XML comments, the imported snippets win with regard to how much leading whitespace is trimmed off of each line.  As such, they appear flush left while the CDATA code appears indented more than the imported code.

You can probably look at the XML comments file to determine how much leading whitespace is in front of the CDATA sample code and then indent the imported block of code by that much plus some extra space to indent them in the merged sample.  That should allow you to get the layout that you want.

Eric
Jul 18, 2008 at 9:45 AM
Edited Jul 18, 2008 at 9:47 AM
Thanks for your explanations !

I understand the principle. However, I did a small test and was expecting everything to be aligned on the left.
Indeed, in my test, I didn't have any whitespace in front of any comments:

Here is my web.config (as you can see, there is no whitespace) :
<configuration>
<configSections>
... here come some useless config sections that I don't want to see in my documentation ...
<!-- #region Dummy configSection -->
<section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
<!-- #endregion -->
</configSections>
... here come some useless sections that I don't want to see in my documentation ...
<!-- #region Dummy section -->
<dummy name="Dummy" value="Hello World"/>
<!-- #endregion -->
</configuration>

Here is my xml doc:
notice that I can't change the indentation of the comments (I.e.: the ///). This is done automatically by Visual Studio.
notice also that for the same reason, I can't remove the whitespace after the ///.
notice finally that in this example, there are 12 characters in front of the actual comments : 8 whitespaces + 3 slashes + 1 whitespace

        /// <example>
        /// <code lang="xml" title="How-to configure the Dummy Service">
        /// &lt;configuration&gt;
        /// &lt;configSections&gt;
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy configSection"/>
        /// &lt;/configSections&gt;
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy section"/>
        /// &lt;/configuration&gt;
        /// </code>
        /// </example>
   
Here is the generated result (I have clicked on the "copy" icon in the generated doc and pasted the result here. So you see the actual indentation made by sandcastle):
            <configuration>
            <configSections>

<section name="dummy" type="Fortis.Framework.Dummy.DummyConfigurationSection, Fortis.Framework.Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

            </configSections>

<dummy name="Dummy" value="Hello World"/>

            </configuration>

It seems to me that at least with such a simple example, I should have everything well aligned in the generated documentation.

You could notice in this result that there are 12 characters in front of the each comment that is not issued from a nested <code> block !
So, I tried to add 12 whitespaces in front of the lines in my web.config. doign so, the generated documentation appeared to be well aligned on the left ?!
I also tried to remove the whitespaces in front of the ///, but this does not change the results. There are still 12 whitespaces in front of the generated doc (except the lines from the nested <code> blocks).

Adding whitespaces in the source of the nested <code> blocks is however not a good workaround. Indeed, as sources for these <code> blocks, we intend to use some content from web.config files that are part of "hands on lab" projects (I.e.: "completed labs" used for trainings). It means that these web.config should be "well" formated (we always use Ctrl-K D to let VS formats our xml). There are not "fake" code that is never read or used (i.e.: they are actually not "snippets" imported in shfb).

So, I am still looking for another solution. Would you have an idea ? Could something be adpated in shfb ?

It would also be nice if there was no added blank lines between the local comment and the comment issued from the nested <code> block.

Valéry.
Jul 18, 2008 at 10:05 AM
In order to complete my reply here above, here is the indented web.config and the code comment block that produce the right result:

The code comment block :
        /// <example>
        /// <code lang="xml" title="How-to configure the Dummy Service">
        /// &lt;configuration&gt;
        ///   &lt;configSections&gt;
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy configSection"/>
        ///   &lt;/configSections&gt;
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy section"/>
        /// &lt;/configuration&gt;
        /// </code>
        /// </example>
   
The web.config containing the "sources" of the nested <code> blocks used in the code comment here above:
<configuration>
<configSections>
   ... here come some useless config sections that I don't want to see in my documentation ...
                <!-- #region Dummy configSection -->
                <section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
                <!-- #endregion -->
</configSections>
  ... here come some useless sections that I don't want to see in my documentation ...
              <!-- #region Dummy section -->
              <dummy name="Dummy" value="Hello World"/>
              <!-- #endregion -->
</configuration>

And the result is :
<configuration>
   <configSections>

     <section name="dummy" type="Fortis.Framework.Dummy.DummyConfigurationSection, Fortis.Framework.Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

   </configSections>

   <dummy name="Dummy" value="Hello World"/>

</configuration>

As mentioned in my previous reply, the result is nearly fine (there are some unwanted blank lines). We would like however to avoid changing the indentation of the source (as explained, because we keep VS indents automatically this file). Instead, we could change the indentation in the xml doc, as you actually suggested. But it does not work (whitespaces in front of the nested <code> blocks are not taken into account) :/

Valéry.
Coordinator
Jul 18, 2008 at 3:23 PM

To determine spacing, take a look at the actual XML comments file.  When generated, the member comments are always indented so you have to take that into account rather than how you specify them in the XML comments in the code.  The only way to control the indentation manually is to move the comments to an include file that gets pulled in with the <include> tag at compile time.

Eric