Indentation in code-tag in included xml-tag
If I want to use a <code>-tag containing indentation in an Xml documented member, I can do it like this:
///<remarks:
///
<code>
///<MyKey>
///<registrations default="<i>MyDefaultRegistration</i>">
///</MyKey>
///</remarks>This works fine. However, I have some sample code that I need to use a couple of times so I wanted to copy this sample code to a separate Xml-document and then reference this sample code using the <include>-tag. Like this:
///<include file='ApplicationDoc.xml' path='docs/member[@name="ApplicationLogon"]/*'/>
The contents of my xml-document looks like this:
<?xmlversion="1.0"encoding="utf-8" ?>
<docs>
<membername="ApplicationLogon">
<remarks>
<code>
<MyKey>
<registrations default="<i>MyDefaultRegistration</i>">
</MyKey>
</code>
</remarks>
</member>
</docs>
This also works fine, but the only way that I've found to get the identation of my code-sample right is to align it to the complete left of the xml-file. If I don't do that my sample code also contains all the identations of the xml-file itself and it ends up somewhere half the page. The problem is that Visual Studio automatically changes the identation of all xml-elements each time that you close a tag and so additional spaces or tabs are always automatically added, like this:
<docs>
<membername="ApplicationLogon">
<remarks>
<
code>
<AlfaPrint.Adam>
<registrations default="<i>MyDefaultRegistration</i>">
</AlfaPrint.Adam>
</code>
</remarks>
</member>
</docs>As you can see, the identation of my sample gets screwed up. I like the auto-ident feature of Visual Studio, but I still want to get the identation in my sample code right. I was hoping that inclusing a <br/> would solve the problem, but apparently this tag doesn't end up in the documentation generated using Sandcastle. Does anybody know a solution?
I've often wondered why the text in <code> sections get indented so much. After reading Michael's message, I decided to look at the documentation XML file generated by csc.exe. I noticed it places leading spaces (12 to be exact) in front of most example code, which causes the indent in generated documentation.
It's interesting that Michael says that the example code in an XML documented members format correctly for him. For me, I always get the big indent except if I have a comment with a <code> section all on one line like:
/// <code>Here is some code</code>
Note that as I recall, this extra indentation also occurs when using NDoc for creating documentation — it's not limited to Sandcastle.
— Eric —
Hi All,
Don't know if you've tried this....
In Visual Studio 2005, go to Tools > Options > Text Editor > XML > Formatting:
In the "Auto Reformat" dialog section, uncheck the "on completion of end tag" checkbox (it's checked by default).
This should keep your intended indentation format, but I don't know if Sandcastle will reinterpret it.
Hope this helps,
Frank
p.s.
This may be quite off-the-wall, so I apologize beforehand....
Could it be that the xslt/css processor is interpreting the <code></code> element you're using in your xml file as an html element and thus using the default <code> format for your code section within it? Unless using the <code></code> element is required in these cases, have you tried changing it to something not so-related to a html element? Or, maybe even better, try using the html <pre></pre> element to enclose the code. If this is the case. the <pre></pre> element should naturally preserve your indentation. Once again, this is just a wild guess, and you may be ok already by turning off the "on completion of end tag" checkbox in the XML Text Editor.
Hi Frank,
I also thought about disabling the "on completion of end tag" checkbox, but I decided against doing that. The problem with this solution is that it does solve the problem for now, but my files can get screwed up by accident very quickly. What if one of my developers forgets to disable this checkbox (after for example reinstalling Visual Studio) and adds a node to one of these files, then the indentations in the beginning of the file will be lost and he would never even notice it.
Not really sure I understand your last remark concerning the <code>-element.
Regards,
Michael
Hi Michael,
Yes, I see your point in leaving the default checked. The only thing I can suggest is that you place a warning as a comment in the beginning of your xml file to anyone editing it to uncheck this box, thus maintaining the indentation structure. My last remark was just a thought not to use html elements in an xml file if this can be avoided. Maybe using <mycode></mycode> for example would work just as well. However, I'm sure Anand will have further info on this from the actual Sandcastle viewpoint.
Frank
Hi Michael,
Yes, as you say, the <code></code> tag kept within the C# /// xml comment structure poses no problems. My question arose after seeing your example of the separate xml file you are pulling into the C# /// comment section using the <include></include> tag. Although it's going into a C# /// xml comment, I thought that since it is in itself a pure xml file there could be some conflct with the <code></code> element being interpreted on it's own, out of the comment's context.
Frank
Michael,
Our internal documentation process is much more complex than the Sandcastle scenario. We do not use /// comments, we draw on information stored in databases and external files, we have to interact with localization and online publishing pipelines, etc. Please see a description on documentation process for ASP.NET AJAX Beta 1 at http://blogs.msdn.com/sandcastle/archive/2006/10/21/documentation-for-asp-net-ajax-beta-1-site-http-ajax-asp-net-docs-using-sandcastle-code-base.aspx.
Our code snippets are stored in a separate data store and are passed into the build process as a shared content xml file. http://blogs.msdn.com/sandcastle/archive/2006/08/14/699129.aspx provides details on the action components of Buildcomponents.dll. The codeExample component resolves the code snippets into the appropriate topic based on the reference.
I plan to write a detailed blog about our internal documentation process and the various Sandcastle components we use to build the documentation.
To go back to this thread I did not get any additional information. I will try to find more and see if I can provide a resolution or an answer.
Anand..
