html comments and sandcastle filtered documentation

Topics: User Forum
May 13, 2009 at 3:24 PM

dear all, i would like to know which is the correct lang attribute value to include inside <code> tag in visual studio 2008 xml documentation tags to document HTML code. Putting my HTML code inside "<![CDATA[" tag (inside the "code" tag) and formatting it manually with tabs, the code is perfectly visible in the chm SandCastle documentation, but I can't find a correct value for the lang attribute that shows the type of language; i try with HTML, XML, ASP.NET, XHTML...I can see only the "copy" link without any information about the used language.

I would like to know if it's also possible to "filter" the sandcastle documentation showing only the info concern the current assembly I want to document without all the microsoft info and msdn references. I know it's possible to filter Methods/properties/events clicking on the "Members" link at the top of the chm file including only the protected members...In this way microsoft base members will not be shown but also my own inherited members aren't visible.

Thank you for any helps.

Giampiero

Coordinator
May 13, 2009 at 7:17 PM

The lang attribute values htm, html, xml, and xsl all equate to the same colorizer rules (XML).  This assumes you are using the help file builder or that you have incorporated the CodeBlockComponent and PostTransformComponent into your configuration files if using Sandcastle by itself without the help file builder.

<code lang="html" title="HTML Example">

... HTML goes here
</code>

Regarding filtering, again assuming you are using the help file builder, you can use the properties in the Visibility category to filter out unwanted items.  See the SHFB help file for information on what each property does.  If not using SHFB, you will need to define an API filter in your MRefBuilder.config file.

Eric

 

May 14, 2009 at 9:24 AM

Great Eric, thank you very much for your reply and help. Yes, i use the Sandcastle Help File Builder GUI interface to create .chm file starting from XML document generated building the project inside Visual Studio 2008 where i put all tags that I need to document the assembly code.

Put in my documentation code tag the attribute lang="html" and title = "HTML" like in this way:

 

 

 

 

 

 

 

 

<font size="2">

 

</font>

 

/// <code lang="html" title="HTML">

/// <![CDATA[<font size="2">

 

</font>

 

/// <asp:TextBox ID="TextBox4" runat="server"></asp:TextBox>

<font size="2">

 

</font>

 

<font size="2">

 

</font>

 

<font size="2">

 

</font>

 

/// ]]>

<font size="2">

 

</font>

 

///

</code>

i achieve the result i was looking for in the chm documentation having on the left the text HTML that display the language i'm using for the example and on the right the Copy image command, and below the line to separate the code content. The only thing I can't do is filter the code by the link "Code:" situated at the top of the chm file that shows the language (from SyntaxFilters in the Project Properties window of the Sandcastle Help File Builder GUI interface), but it's not so important.

Regard the question about filtering the documentation, obtaining an improvement in the building project and a "stand-alone" documentation assembly, I use, how you suggest, the filter DocumentInheritedFrameworkMembers in the Visibility section to False and leaving DocumentInheritedMembers property to True, achieving the result.

Thank you very much for the help

Best Regards

Giampiero

 

 

 

I found that to avoid