Sandcastle : Features

Filtering APIs using Sandcastle

aram — Thu, 19 Jun 2008 01:13:00 GMT

API filters in Sandcastle is a very useful feature and allows namespaces, types, and members to be removed or shown in the reflection XML file, and ultimately in the compiled docs. They can be set up so that only certain topics are dropped, or so that a parent type has all children hidden with only specific ones shown. The API filter configuration can be found in ProductionTools\MRefBuilder.config file and is contained within an apiFilter element.

If no apiFilter element exists the default is to expose everything. This is the same as having an empty apiFilter element that is exposed such as

Setting expose to false will hide everything, which is useful if you wish to expose only certain namespaces, types, or methods.

Filter Inheritance

Filters inherit from their parent filter, with the exception of nested types which look to their parent type(s) before the namespace filter.

In the example below, only ThirdNamespace will be exposed. All other namespaces will be left out. Also, all types in ThirdNamespace and methods within those types will be shown. Types and methods in other namespaces will be left out.

</apiFilter>

This filter shows everything except for ThirdNamespace and it types and members.

</apiFilter>

If a filter is exposed within a non-exposed filter it will still be shown. The example below results in only the single method being exposed along with its declaring types. No other children of the declaring types are exposed. Without the filter for MyMethod, or with the filter set to false, everything will be hidden.

</type>

</namespace>

</apiFilter>

A filter to show all types within MyClass, but leave out MyMethod and MyMethod2 would look like this

</type>

</namespace>

</apiFilter>

Nested Types

Nested types inherit from their parent type. If a type is nested within other nested types it will go through the parent types until it finds a filter.

In the examples below are filters for a class with contains a class called MyNestedNestedClass which is nested within MyNestedClass. MyNestedClass is nested with a class called MyClass.

MyNamespace
     - MyClass
        - MyNestedClass
            -MyNestedNestedClass

This filter will hide everything except for MyNestedClass and its types. Since we set MyNestedNestedClass to be hidden it will not show up. MyClass is also hidden since MyNamespace is not exposed.

</namespace>

</apiFilter>

Here MyNestedNestedClass will also be shown since its declaring type (MyNestedClass) is shown.

</namespace>

</apiFilter>

Exposing members within nested types works the same as with regular types. Using this filter only MyNestedMethod will be shown, leaving MyNestedNestedClass hidden, and all other members within MyNestedClass.

</type>

</namespace>

</apiFilter>

General Examples

The following example filters out three namespaces, and 11 types within the System namespace.

</namespace>

</apiFilter>

Hope this helps. Cheers.

Anand..

Sandcastle Community Projects - Sandcastle Styles

aram — Thu, 05 Jun 2008 19:28:00 GMT

I talked about various community projects supporting Sandcastle in this blog http://blogs.msdn.com/sandcastle/archive/2007/06/21/sandcastle-customer-projects.aspx. I am very pleased to announce the release of Sandcastle Styles to this community project list. Dave Sexton of DocProject for Sandcastle wrote me the following:

Hi Anand,

I don’t know if anyone else notified you about this yet, but Sandcastle Styles is now live.

Thanks Dave for notifying me. As I understand the goal of this project is to improve Sandcastle releases by providing a rolled-up solution to various presentation style issues in a manner that is highly visible to the Sandcastle community and also involves community feedback.

What's Available in this release?

Sandcastle May 2008 Patch - This is a patch for the Sandcastle presentation style files that fixes most of the known bugs. It also includes enhancements to existing features.

Documenting Web Projects 1.0.0.0 - This contains information on producing XML comments for web application and website projects. For website projects, custom code providers are included that make it much easier to obtain the XML comments files needed to create a help file using Sandcastle

Sandcastle MAML Guide 1.0.0.0 - This is intended to be a reference that you can use to find out all that you need to know about Microsoft Assistance Markup Language (MAML) as used with Sandcastle to produce help files containing conceptual content.

Future Plans

Work is under way to produce a set of example code and MAML files that you can use to see the effects of the various XML comments and MAML elements and learn how they can be used. In the future, custom presentation styles and language packs may also be made available.

This is a great community team effort by Dave, Eric and Paul and I thank you guys for brining this effort together. Cheers.

Anand..

Announcing October 2007 Sandcastle CTP Release

aram — Tue, 30 Oct 2007 02:51:00 GMT

I am excited to announce the availability of October 2007 CTP version for Sandcastle. The latest version is now available for download at http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en. My sincere thanks to the Sandcastle user community for providing us with valuable feedback.

What's new in this version:

1. Reflection data files: The reflection files (generated from .net framework 3.5, vs2005 style) are included in the installer. After installation, they can be found under “%DxRoot%\Data\reflection”. In build_sandcastle.bat and build.proj, we have commented out the call to fxReflection.proj.

2. Conceptual example: A conceptual example is located at “DxRoot\Examples\conceptual”. To build it, please run the following command line commands.

Cd c:\program files\sandcastle\examples\conceptual

Build_conceptual.bat

3. Conceptual configs: conceptual.config is added for conceptual build in each presentation style. The path is “Vs2005(/hana/prototype)\configuration\conceptual.config”.

4. Whidbey (VS 2005) style sheet: The old Whidbey style sheet is now available at “DxRoot\presentation\vs2005\style\whidby\presentation.css”. To use it, please copy it to “DxRoot\presentation\vs2005\style” and overwrite the existing css. Before doing this, you may want to backup that css file first.

5. Conceptual Authoring schemas: The schema files under “DxRoot\schemas\Authoring” are schemas for conceptual authoring. The root schema is developer.xsd. The conceptual sample xml can be found at “DxRoot\Examples\conceptual\dduexml”.

6. Reflection schema: The MrefBuilder reflection schema file is available under “DxRoot\schemas\Reflection” folder.

7. Firefox support: we fixed many bugs to make the produced html files compatible with the latest firefox browser.

Changes in this version:

Reflection files are provided under “DxRoot\Data\Reflection” folder.
Schema files for conceptual authoring and MrefBuilder provided.

Getting Started:

1. Using the command line option for the batch file under Examples/Sandcastle folder to build VS2005 or hana or prototype style CHM or HxS file

1. Build_sandcatle.bat vs2005 test

2. Build_sandcatle.bat prototype test

3. Build_sandcatle.bat hana test

If you need to generate hxs, please uncomment the following line in build_sandcastle.bat. Make sure "Microsoft Help 2.0 SDK" is installed on your machine.

::hxcomp.exe -p output\test.hxc

2. Using msbuild to generate build for VS2005 or hana or prototype, CHM or HxS file

1. Msbuild build.proj /property:PresentationStyle=vs2005

2. Msbuild build.proj /property:PresentationStyle=hana

3. Msbuild build.proj /property:PresentationStyle=prototype

To build hxs, add /target:Hxs, eg: Msbuild build.proj /property:PresentationStyle=vs2005 /target:Hxs

Issues fixed in this version (Reported by Customers):

1. Sandcastle: Langword "null" is not rendering in vs2005 style

2. Sandcastle: Add other supported languages to configs

3. Sandcastle: The font of "send feedback" looks strange

4. Sandcastle: Method name has double '()' in prototype style

5. Sandcastle: No index entry in hxs build (prototype style)

6. Sandcastle: Format of Declaration Syntax section need to improve.(prototype)

7. Sandcastle: Nested type split type name with two dots. (prototype)

8. Sandcastle: Incorrect bracket order of generic type. (prototype)

9. Sandcastle: Add a switch to have the ApplyVSDocModel.xsl transformation generate an R:Project node with an auto-generated Namespaces topic

10. Sandcastle: Chm Title Property to project name instead of "help"

11. Sandcastle: Duplicate pubenumeration.gif and broken image

12. Sandcastle: The methodnames in the prototype template are having a strange trailing '()()'.

13. Sandcastle: In fxreflection.proj the itemgroup is called AssemblyFloders (typo)

14. Sandcastle: JS error using the VS2005 style when browsing the raw HTML topics in IE7

15. Sandcastle: Make DxRoot System Variable

16. Sandcastle: MRefBuilder namespace ripping feature bug

17. Sandcastle: Overridden methods in sealed classes do not show up in the class

18. Sandcastle: In VSOrcas style in the TOC, every item under the Methods, Properties,Events, Fields, and overloads containers is prefixed with the class name which is unnecessary and clutters up the list

19. Sandcastle: In VsOrcas style there are duplicate entries for namespaceNameHeader, methodIndexEntry, and runningHeaderText in reference_content.xml

20. Sandcastle: In VSOrcas style there is a remarksTitle entry in both reference_content.xml and shared_content.xml

21. Sandcastle: In VS2005 Replace getStyleDictionary() in CommonUtilities.js to fix 2 issues

22. Sandcastle: In VS2005 presentation <item id="XAMLLabel">XAML</item> is missing from the shared_content.xml file.

23. Sandcastle: In prototype style an exception occurs when generating the table of content if there are overloaded operators in the assembly

24. Sandcastle: In Prototype style nested classes prefixed with the parent class's name are not sorted into the correct location TOC

25. Sandcastle: In Prototype style Methods with no parameters on class members page and on the method pages show an extra set of parentheses

26. Sandcastle: In Prototype style Methods with no parameters on class members page and on the method pages show an extra set of parentheses

27. Sandcastle: In Prototype Style the <see> tag ignores inner text

28. Sandcastle: Changes to Prototype Presentation.css

29. Sandcastle: In Prototype the "style" attribute on the ManagedCPlusPlus <language> element in the TransformComponent configuration should be set to "cpp"

30. Sandcastle: In Prototype <item id="XAMLLabel">XAML</item> is missing from the shared_content.xml file.

31. Sandcastle: In Prototype Style <item id="comments"> is missing from the shared_content.xml file.

32. Sandcastle: In Prototype style <item id="VisualBasicUsageLabel"> in shared_content.xml should say "Visual Basic Usage" to match the other styles.

33. Sandcastle: Support u and font tags in the HTML passthrough section in the main_sandcastle.xsl

34. Sandcastle: For the VS2005 and VSOrcas style Overloads pages are being created for methods in base classes

35. Sandcastle: In VSOrcas the language syntax section are too tall when viewed in Firefox

36. Sandcastle: Several issues with Firefix

37. Sandcastle: Icon name of public enum should be "pubenumeration.gif" (hana)

38. Sandcastle: missing content items 'pubenumerationalttext' and 'pubclassalttext' (vsorcas style)

39. Sandcastle: Add VB support for the <see langword="abstract"/> also

40. Sandcastle: TOC has duplicate constructor nodes

41. Sandcastle: Plain text is showing as link with version-specific reflection files provided

42. Sandcastle: If the content is too long in the Tables in MREF docs there is no scrollbar displayed.(prototype style)

43. Sandcastle: Version info is not showing up

44. Sandcastle: Error of main_schema.xsl (prototype)

45. Sandcastle: Page has no vertical scrollbar.(prototype)

46. Sandcastle: Some share content items missed. (vsorcas)

47. Sandcastle: langword "null" should be displayed as "null" not "a null reference " also in bold just like "Nothing" in VB.

48. Sandcastle: The middle segment does not align with other segments in feedback section (whidbey stylesheet)

49. Sandcastle: Differences between whidbey stylesheet and current vs2005 stylesheet

50. Sandcastle: VSDoc Model bug causes Overloads TOC entry pages that are invalid

51. Sandcastle: The text is missing in Vs2005 style.

52. Sandcastle: The button and link of "send feedback" don't work.(vs2005 style)

53. Sandcastle: The link of "send comments" doesn't work.(hana style).

54. Sandcastle: The tabs is broken in VSOrcas (hana) style.

55. Sandcastle: The dropdownlist seems float.(prototype style).

56. Sandcastle: In firefox the font for feedback's title looks odd (vs2005 style)

57. Sandcastle: In firefox language filter does not work (vs2005 style)

58. Sandcastle: 'copycode' does not work in firefox

59. Sandcastle: The link of "Copy Code" doesn't work.

60. Sandcastle: Icon's alt text does not show up in firefox

61. Sandcastle: Support <seealso href=""> tag

62. Sandcastle: There some script errors in the html page under vista (hana style).

63. Sandcastle: Private field and method displayed in TOC but not in the detail content

Cheers.

Anand..

Part 2: Version Builder

aram — Wed, 24 Oct 2007 09:08:00 GMT

In my previous blog http://blogs.msdn.com/sandcastle/archive/2007/10/03/sandcastle-september-2007-release-versionbuilder.aspx I provided details about Version Builder. I had several questions (http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2237661&SiteID=1) about this feature. Attached is an example of versionbuilder. Here are the steps to run it.

Unzip it to “c:\program file\sandcastle\examples”;
Run command to get version-specific reflection file: > runversionbuilder.bat
Run command to build chm: > build_sandcastle.bat vs2005 test;

In this example, the method “swap(T)” is supported only in 2.0 version, other methods are supported in both 2.0 and 1.1. See image below:

The following lines should be added to vs2005\transforms\main_sandcastle.xsl and this will be fixed in the October release

<xsl:if test="not($group='list' or $group='namespace' or $group='root' )">

<xsl:apply-templates select="/document/reference/versions" />

</xsl:if>

<xsl:call-template name="seealso" />

Hope this helps. Cheers.

Anand..

Sandcastle September 2007 Release: VersionBuilder

aram — Wed, 03 Oct 2007 03:23:00 GMT

Sandcastle September 2007 release includes the VersionBuilder tool under \ProductionTools folder to provide support for documenting multiple versions of a project. The VersionBuilder tool generates a single reflection data file from multiple version-specific reflection files. The output reflection file can then be used in the Sandcastle build to generate reference documentation in which each API's topic contains information about the versions that support the API. For example, if you have three versions of the same DLL, with some APIs present in all three versions and other APIs present in only one or two versions, the topic for each API can include a Version Information section that lists the versions that include the API.

For Orcas RTM, the Version Information section of the documentation is as follows:

A member that’s been in all versions of .NET will say:

Supported in: 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0, 1.1, 1.0

A member introduced in 2.0 SP1 will say:

Supported in: 3.5, 3.0 SP1, 2.0 SP1

A member introduced in 3.0 SP1 will say:

Supported in: 3.5, 3.0 SP1

To fully understand the version information, it’s important to understand how .NET 3.5 is built. Unlike versions 1.0, 1.1, and 2.0., .NET 3.5 (and 3.0) use dlls from the previous versions of .NET and adds its own as well. For example, there is no 3.5 version of mscorlib.dll. Instead, .NET 3.5 uses the same version that .NET 2.0 uses. But installing 3.5 on a computer updates the 2.0 version of mscorlib.dll. In fact, you can get the updated dll without installing 3.5; you can get the new dll by installing .NET 2.0 SP1. That means that any APIs added to mscorlib.dll after .NET 2.0 RTM are part of 2.0 SP1.

We think of Orcas as using .NET 3.5, but in reality, Orcas allows you to target .NET 2.0, 3.0, or 3.5. You’re not targeting the RTM versions of 2.0 or 3.0, though, because Orcas installs .NET 3.5, which includes the updated dlls for 2.0 and 3.0. As a result, when you target 2.0 or 3.0, intellisense shows the APIs that have been added since either version RTM’ed. But the recommendation to our customers is to only use the new APIs if you target .NET 3.5 because it’s difficult to tell whether a user has the RTM version of .NET 2.0 or .NET 2.0 SP1. Please see http://www.danielmoth.com/Blog/labels/Orcas.html and the video at http://channel9.msdn.com/Showpost.aspx?postid=333940 to understand the complexities of the Framework versions with the Orcas release.

Sequence of processing in VersionBuilder:

· Run MRefBuilder on each version's DLL set. Note that the DLL set for each version of a project includes the complete set of DLLs, not just the DLLs that are new or changed.

· Run the MergeDuplicates.xsl transform on each of the version-specific reflection files.

· Run VersionBuilder with the version-specific reflection files as input and the combined reflection file as output

· Proceed with the rest of the Sandcastle build using the combined reflection file

VersionBuilder command line:

The VersionBuilder command line has two switches.

/config:versionCatalog

versionCatalog is the path of a configuration file that specifies the reflection files for each version

/out:outputFile

outputFile is the path of the file where VersionBuilder writes the combined reflection file. If not specified, VersionBuilder writes output to the console. VersionBuilder throws an exception if the outputFile specifies a directory that does not exist.

For example:

VersionBuilder.exe /config:%projectPath%\config\versionBuilder.config /out:%projectPath%\reflection_allversions.xml

VersionBuilder configuration file:

The VersionBuilder configuration file specifies the input reflection files that MrefBuilder generated for each version. It also specifies a name for the project and names for each version. The names correspond to the ids of shared content items for the project and version names that appear in the Version Information section of an API's documentation.

Here is the content of a typical VersionBuilder configuration file:

<versions>

<versions name="ourproject">

<version name="ourproject30" file="%versionReflectionFolder%\reflection_ourproject30.xml" />

<version name="ourproject20" file="%versionReflectionFolder%\reflection_ourproject20.xml" />

<version name="ourproject10" file="%versionReflectionFolder%\reflection_ourproject10.xml" />

</versions>

Additional shared content items for version names

In a reflection file generated by VersionBuilder, each <api> node has a <versions> child node that contains information about the versions that include the API. When the <versions> node is present, the build transforms insert a Version Information section in each API's topic to list the versions that support the API. For example:

Version Information

Our Project

Supported in: 3.0, 2.0

The project name ("Our Project") and the version number strings ("3.0" and "2.0") come from a shared content items that you must define. For example, you can create a file named ourSharedContent.xml that has the following contents:

<content xml:space="preserve">

<item id="ourproject">Our Project</item>

<item id="ourproject30">3.0</item>

<item id="ourproject20">2.0</item>

<item id="ourproject10">1.0</item>

</content>

Then you need to update the BuildAssembler configuration file to include a reference to the ourSharedContent.xml file.

<component type="Microsoft.Ddue.Tools.SharedContentComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

<content file="%DXROOT%\Presentation\vs2005\content\shared_content.xml" />

<content file="%DXROOT%\Presentation\vs2005\content\reference_content.xml" />

<content file="%DXROOT%\Presentation\shared\content\syntax_content.xml" />

<content file="%DXROOT%\Presentation\vs2005\content\feedback_content.xml" />

<content file="c:\ourSharedContent.xml" />

</component>

Hope this helps. Cheers.

Anand..

September 2007 Sandcastle release: Generating Framework Reflection data for resolving links

aram — Tue, 02 Oct 2007 09:25:00 GMT

Sandcastle September 2007 release was shipped without the Framework reflection data. This allowed us to reduce the Sandcastle installer size to 1.5 MB. In our previous releases we shipped the reflection files under the \Data\Reflection folder. For the September release we expect the users to generate this information.

Why do we need this reflection data?

The reflection files are used to resolve any reference links to the Framework. Please see http://www.dnrtv.com/default.aspx?showNum=84 for additional details.

Why did we leave the reflection files from our Install?

We could have generated the reflection files and shipped it with our installer. In our previous releases we shipped the reflection files for Framework 2.0 under Data\Reflection folder. However the reflection files we shipped were specific to a document model.

VS2005 and Hana presentation styles follow a document model (ApplyVSDocModel.xsl) and Prototype style follows another document model (ApplyPrototypeDocModel.xsl). We shipped the reflection files with VS2005 document model and users using Prototype style ended up using it. With Orcas RTM the users targeting 3.5 will need access to various versions of Framework reflection files. Please see http://www.danielmoth.com/Blog/labels/Orcas.html and the video at http://channel9.msdn.com/Showpost.aspx?postid=333940 to understand the complexities of the Framework versions with the Orcas release.

With Framework versions 2.0, 2.0 SP1, 3.0 and 3.5 things are getting complicated and it became very clear to us that shipping all the reflection files for all the document models will increase the Sandcastle installer size by 20 plus MB.

How do the users generate reflection data?

If you are using VS2005 or Hana presentation styles do the following:

1. Run MrefBuilder on all the Framework dlls

2. Apply the ApplyVSDocModel transforms.

If you are using Prototype presentation style do the following:

1. Run MrefBuilder on all the Framework dlls

2. Apply the ApplyPrototypeDocModel transforms.

Alternatively you can generate them by executing one of the the following under /Example/Sandcastle directory:

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=VS2005

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=hana

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=prototype

Note: If you are have 3.0 or 3.5 installed please change the NetFxVer accordingly.

Generating Reflection data as a part of test project:

We have shipped a sample command line batch script and msBuild project with the /Example/Sandcastle directory. Users can run the following to build the test project CHM or HxS and also to generate the reflection data information.

1. Using the command line option for the batch file under Examples/Sandcastle folder to build VS2005 or Hana or Prototype style CHM or HxS file

1. Build_sandcatle.bat vs2005 test

2. Build_sandcatle.bat prototype test

3. Build_sandcatle.bat hana test

Note: The reflection files should be generated for the first time only. Please comment the following section in the Build_Sandcastle.bat files after generating them for the first time.

msbuild fxReflection.proj /Property:NetfxVer=2.0 /Property:PresentationStyle=%1

2. Using msbuild to generate build for VS2005 or Hana or Prototype, CHM or HxS file

1. Msbuild build.proj /property:PresentationStyle=vs2005

2. Msbuild build.proj /property:PresentationStyle=hana

3. Msbuild build.proj /property:PresentationStyle=prototype

Note: The reflection files should be generated for the first time only. Please comment the following section in the build.proj files after generating them for the first time.

<Exec Command="$(Framework)\msbuild fxReflection.proj /property:PresentationStyle=$(PresentationStyle)" />

Hope this helps. Cheers.

Anand..

Announcing September 2007 Sandcastle Release

aram — Tue, 02 Oct 2007 03:32:00 GMT

I am excited to announce the availability of September 2007 version for Sandcastle. The latest version is now available for download at http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en. My sincere thanks to the Sandcastle user community for providing us with valuable feedback.

What's new in this version:

CHMBuilder for CHM generation using Sandcastle. Please see http://blogs.msdn.com/sandcastle/archive/2007/09/13/building-chm-using-chmbuilder.aspx.
New Hybrid design (Presentation changes to VS2005 transforms). Please see http://blogs.msdn.com/sandcastle/archive/2007/09/19/part-1-vs-2005-presentation-changes-in-sandcastle-september-release.aspx.
Windows PowerShell script for documenting APIs using Sandcastle. Please see http://blogs.msdn.com/sandcastle/archive/2007/09/12/documenting-apis-with-sandcastle-using-windows-powershell.aspx.
VersionBuilder tool to provide support for documenting multiple versions of a project. I will post a blog on this shortly.
DBCSFix for CHM localization – Please see http://blogs.msdn.com/sandcastle/archive/2007/09/29/chm-localization-and-unicode-issues-dbcsfix-exe.aspx
Reduced installer size: This version has a 1.5 MB installer. We accomplished this by not shipping Framework reflection data. Framework reflection data is now generated during the first run of the test project
5 Star MSDN style Feedback Control

Changes in this version:

Data\Reflection is not installed by the msi. It’s now generated when a use runs the test project (using msproject or batch or powershell). This will take about 4 minutes to generate the files.
CHM will be generated in a CMH folder instead of the Output folder.

Getting Started:

1. Using the command line option for the batch file under Examples/Sandcastle folder to build VS2005 or hana or prototype style CHM or HxS file

1. Build_sandcatle.bat vs2005 test

2. Build_sandcatle.bat prototype test

3. Build_sandcatle.bat hana test

If you need to generate hxs, please uncomment the following line in build_sandcastle.bat. Make sure "Microsoft Help 2.0 SDK" is installed on your machine.

::hxcomp.exe -p output\test.hxc

2. Using msbuild to generate build for VS2005 or hana or prototype, CHM or HxS file

1. Msbuild build.proj /property:PresentationStyle=vs2005

2. Msbuild build.proj /property:PresentationStyle=hana

3. Msbuild build.proj /property:PresentationStyle=prototype

To build hxs, add /target:Hxs, eg: Msbuild build.proj /property:PresentationStyle=vs2005 /target:Hxs

Issues fixed in this version (Reported by Customers):

1. Sandcastle: Add other supported languages to configs

2. Sandcastle: ApiFilter doesn't work as expected

3. Sandcastle: Build intellisense documentation without internal members

4. Sandcastle: BuildAssembler is throwing System.FormatException

5. Sandcastle: Can SandCastle find automatically GAC assemblies

6. Sandcastle: Chinese characters incorrectly display in TOC

7. Sandcastle: duplicate keys in shared_content.xml and reference.content.xml

8. Sandcastle: Example code sections in VS2005 template is having incorrect background-color and font

9. Sandcastle: Format of Delaration Syntax section need to improve.(prototype)

10. Sandcastle: Incorporate Dbcsfix in sandcastle

11. Sandcastle: Incorrect behavior for Complier Generated Class

12. Sandcastle: Incorrect bracket order of generic type. (prototype)

13. Sandcastle: Method name has double '()' in prototype style

14. Sandcastle: Move "UnsupportedExplicit_JSharp" from vs2005/hana to shared file

15. Sandcastle: MRefBuilder Namespace Ripping Bug with /internal+ option

16. Sandcastle: Nested type split type name with two dots. (prototype)

17. Sandcastle: No index entry in hxs build (prototype style)

18. Sandcastle: Open a new window when a MSDN-link is being clicked

19. Sandcastle: Printing issue of prototype transforms

20. Sandcastle: Problems about "public event" in cpp project.

21. Sandcastle: Problems in compiling html help due to encoding settings

22. Sandcastle: Reflection file is not correct if we have overloaded constructors (prototype style)

23. Sandcastle: Set "style" attribute to "cpp" for ManagedCPlusPlus

24. Sandcastle: Some type's FullName is showing up incorrectly. (vsorcas style)

25. Sandcastle: The "Type Parameters" are showing up differently between "Class" and "Members" page.

26. Sandcastle: Provide 5 Start Feedback Control

27. SandCastle: The icon of protected delegate is shown as public in .chm file

28. SandCastle: The member of enumeration in “Members” section has a link to self page.

29. Sandcastle: The method signature in "Members" section looks uncorrectly. (vsorcas style, Language Filter: Visual C++)

30. Sandcastle: There is an unhandled Exception araise when I run Build_sandcastle with vsorcas style

31. Sandcastle: When a method overrides another, the name of the class defining the original method is not present in the description

32. Sandcastle: when jump to a page, the default Language Filter is C#, and the page style is "VB" (vsorcas)

33. Sandcastle: When there are many constructors, the title of the group page, in the TOC, starts with a dot. The starting dot should be removed

34. Sandcastle:langword "null" is not rendering in vs2005 style

Issues fixed in this version (Features and Bugs as a part of Orcas RTM):

Approximately 500 work items for Orcas (Visual Studio 2008) RTM. I will be happy to publish a list if users are interested.

CHM Localization and Unicode issues - dbcsFix.exe

aram — Sat, 29 Sep 2007 08:31:00 GMT

In this thread (http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2139818&SiteID=1) we discussed about the localization issues in CHM. With September Sandcastle release we have addressed the Unicode issues for CHMs built in East Asian languages. Here’s the problem:

1. For localized CHMs the sources need to be in ANSI if the language’s characters don’t all map to Western-1252.

2. If you compile ANSI sources, the HTML help compiler assumes that the HTML codepage is your current system codepage. If your system is set to EN-US ( like my system), the resulting CHM contains incorrect characters, unless you change my system settings (which require a reboot).

To resolve this, one must:

1. Note the codepage in the source HTML (a META tag).

2. Re-encode all files in ANSI, using the appropriate code page.

3. Trick the OS in to stating its current codepage is something different than what it really is.

4. Compile.

Here’s our solution:

1. Have ChmBuilder write the codepage as UTF-8 into the HTML as it generates them (they actually are UTF-8 at this point).

2. Re-encode the files using dbcsFix.exe. DBCS stands for Double Byte Character Set and we use this program to convert UTF-8 to ANSI . While doing so, substitute the actual codepage (e.g., big5) for what was initially written (UTF-8).

3. Wrap the call to HHC.exe in a call to MS APPLocale or SbAppLocale.exe, passing in the appropriate LCID.

dbcsFix.exe Details:

dbcsFix.exe attempts to work around limitations in the CHM compiler regarding character encodings and representations. Specifically:

1. Replaces some characters with ASCII equivalents, as follows:

Char name	utf8 (hex)	ascii
Non-breaking space	\xC2\xA0	" " (for all languages except Japanese)
Non-breaking hyphen	\xE2\x80\x91	"-"
En dash	\xE2\x80\x93	"-"
Left curly single quote	\xE2\x80\x98	"'"
Right curly single quote	\xE2\x80\x99	"'"
Left curly double quote	\xE2\x80\x9C	"\""
Right curly double quote	\xE2\x80\x9D	"\""
Horizontal ellipsis	U+2026	"..."

After this step, no further work is done when LCID == 1033.

2. Replaces some characters with named entities, as follows:

Char name	utf8 (hex)	named entity
Copyright	\xC2\xA0	&copy
Registered trademark	\xC2\xAE	&reg
Em dash	\xE2\x80\x94	—
Trademark	\xE2\x84\xA2	™

3. Replaces the default "CHARSET=UTF-8" setting in the HTML generated by ChmBuilder with "CHARSET=" + the proper value for the specified LCID, as determined by the application's .config file

4. Re-encodes all input HTML from their current encoding (UTF-8, as output by ChmBuilder) to the correct encoding for the specified LCID.

USAGE:

dbcsFix.exe [-d=Directory] [-l=LCID]

-d is the directory containing CHM input files (e.g., HHP file). For example, 'C:\DocProject\Output\Chm'. Default is the current directory.

-l is the language code ID in decimal. For example, '1033'. Default is '1033' (for EN-US). Usage is also available with -?

After processing the inputs with dbcsFix.exe, the call to the CHM compiler must be made when the system locale is the same as the value set when calling this tool. This can be done either by changing your system settings via the control panel, or by MS APPLocale or by SbAppLocale.exe. In the latter case, the call should be similar to:

SbAppLocale.exe $(LCID) "%PROGRAMFILES%\HTML Help Workshop\hhc.exe" Path\Project.HHp

REFERENCES:

Here are some useful links about Unicode and general encoding issues:

Sincere thanks to my colleagues John Carl and Justin Russell for developing dbcsFix.exe. Cheers.

Anand..

Part 1: VS 2005 presentation changes in Sandcastle September Release

aram — Wed, 19 Sep 2007 09:18:00 GMT

We have made several improvements to the VS 2005 presentation transforms for our September release of Sandcastle. Internally we call it the “hybrid” document design for Orcas. This new documentation presentation layer targets Visual Studio Developers who need to find information quickly and easily in our documentation that grows significantly with every Visual Studio/.NET Framework release. As new .NET Framework features are released, we must update the documentation design to accommodate the associated new concepts. As a result, we need improvements to the way that we navigate, filter, and display the documentation. These new features allow developers to locate, filter, and sort information in ways that are necessary to perform their job.

The following new features will be introduced in our Orcas documentation and users can take advantage of this by using the September Sandcastle release.

1. Programming language filter drop down: Syntax blocks, code examples, and member tables should be filterable by language. Users can pick one or more procedural code languages that will determine what content is shown on the member page.

2. Content Controlled by the Language Filter: The TOC titles will always use neutral language syntax

3. Frameworks Filter: The framework filter dropdown will appear on member list topics to enable framework filtering of the rows and icons displayed in the member list tables. It will be a separate dropdown in addition to the member filter dropdown. There will be a framework drop-down filter consisting of checkboxes.

4. Member List Filter Drop Down: The members filter will be its own drop down box consisting of check boxes that allow the displaying/hiding of protected and inherited members in the member list tables. Table rows for public members and explicit interface implementation members are always visible; but rows for protected members are shown/hidden based on the state of the “Include Protected Members” checkbox. Similarly, declared members are always visible, but the visibility of inherited members depends on the “Include Inherited Members” checkbox. Unlike the framework filter, this filter will not persist between type pages as the user navigates the documentation.

5. Dynamic language-specific text based on language filter: The language filter drop down determines how language-specific text is displayed in link text, topic titles, and language keywords. When a single language is checked in the language filter, the language-specific text is displayed using the format appropriate for the selected language. For example, when only C# is checked, link text is displayed using the C# convention for arrays (“String[]”) and generic types (“Collection<T>”); and when only VB is checked, link text is displayed using the VB convention for arrays (“String()”) and generic types (“Collection(Of T)”).

6. Filtering Persistence: A user can interact with the documentation by checking boxes in the filter drop down menus. In some cases the checkbox states should be persistent, meaning that the filter maintains the user’s choices as they navigate the documentation

7. Intelligent Filter Display: Language filter defaults should be configurable on a per-document project basis. For example, a C++ specific document set should default to C++. When a topic is configured for a single language, the language filter drop down is NOT displayed, but the topic’s content is filtered as if a checkbox for the single language is checked.

8. XAML syntax blocks/code samples: XAML is not a procedural language proper, however there are syntax blocks and code samples associated with it. The build process that generates XAML syntax will do so only for topics where it is appropriate (e.g. for APIs in assemblies that support XAML).

9. ASP.NET syntax blocks: In a similar manner to XAML syntax, ASP.NET syntax is always visible.

10. Updates to the non-scrolling region: Changes to the links in the non-scrolling region for the following pages

a. Member List Pages

b. Namespace Pages

c. Type Overview Pages

d. Member PagesLinks to Namespace on Member and Type Overview Pages

11.Cut and Paste Functionality: When users cut text from a topic, code must accommodate that the clipboard is populated with the currently selected language syntax.

12.Printing the Documentation: When a user is viewing the documentation, they are able to pront the topic and it’s subtopics from the TOC nodes.

13. Double Index Entries: Inject double entries into the Index for types and member pages to ensure that index entries displayed both C# and VB syntax for example

14.TOC Display Format: Topic titles as shown by the TOC can only be shown in one language syntax and is not changeable at runtime by the user

15. Representations of Generic Types and Methods

a. Generic TypeGeneric Method on Generic Type

b. Generic word and italics

c. Additional Examples

16. New 5 Star ‘Send Feedback” link in documentation

I will blog details about these features in the next part of this blog. Cheers.

Anand..

Building CHM using CHMBuilder

aram — Thu, 13 Sep 2007 08:55:00 GMT

Please see my blog about Sandcastle September 2007 release. With this release, we plan on shipping a new tool called CHMBuilder for CHM generation using Sandcastle.

What is CHMBuilder?

CHMBuilder is an executable that will be shipped under the Production Tools folder of Sandcastle. The HXS generation process in Sandcastle works much better than the CHM generation process. There are several reasons for this, but the central problem is that CHMs do not get the data to build TOC and indexes from the topic HTML files themselves. We have transforms under Production transforms folder that collect this data, but they are very slow ( http://blogs.msdn.com/sandcastle/archive/2007/02/28/sandcastle-performance-improvements-in-february-ctp.aspx) and are not localized

Given HXS-ready Sandcastle output, ChmBuilder will produce HHP, HHC, and HHK files, and transform the HXS-ready topic files to CHM-ready topic files. Using CHMBuilder the user would no longer have to do separate BuildAssembler runs to generate CHM’s and HXSs. This also solved the internal scenario for our team where we build CHM and HxS for many products.

CHMBuilder Usage:

ChmBuilder /html:htmlDirectory /toc:tocFile /project:projectName /lcid:languageId /out:outputDirectory

/html:htmlDirectory

Specify a html directory.

/project:projectName

Specify a project name.

/toc:tocFile

Specify a toc file.

/lcid:languageId

Specify a language id. If unspecified, 1033 is used. See chmbuilder.config for the list of languages.

/out:outputDirectory

Specify an output directory. If unspecified, CHM is used.

On input, htmlDirectory is a directory containing HTML topic files with XML data islands containing HXS metadata. The tocFile is the manifold TOC file, produced either using either the ReflectionToToc.xsl or DsTocToToc.xsl transforms.

Upon completion, the outputDirectory contains the files projectName.HHP, projectName.HHC, projectName.HHI, and a directory with the same name and as htmlDirectory containing topic files with the same names and contents as the input topic files, but stripped of HXS-specific elements.

CHMBuilder Details:

1. The HHP file produced references the HHC and HHK files produced, and the output topic directory. HHP file is generated with template read from config. Three items are replaced for a given project; they are {projectName}, {defaultTopic} and {language}.

2. The HHK entries are produced using the Term attributes on all <MSHelp:Keyword Index=”K” /> elements within the XML data island of all the topics.

3. The HHC file is produced using the structure defined in the tocFile, taking titles from the input topic files. If an <MSHelp:TOCTitle /> attribute is present, that title is used. Otherwise, the value in the HTML <title> element is used.

4. The output topic files do not contain the XML data island. All <MSHelp:link>linkText</MSHelp:link> elements are transformed into <span class=”nolink”>linkText</span>. Any other elements in the MSHelp namespace are removed. The topic documents are otherwise identical.

5. The input topic files are read with an XmlReader, and the output topic files are produced with an XmlWriter, for speed and low memory overhead.

6. The tool also successfully transforms topic files that do not appear in the TOC.

7. The tool supports htmlDirectorys with a directory substructure. The processing goes recursively through subdirectories and reproduces this structure in the output directory.

8. The tool supports Localization of TOC and Index. For HHK file, the encoding is “codepage” read from config file. For HHP file, the language option is set to “name” attribute from config.

9. The tool supports indented second level index. If there is a comma in K keyword, then only the second half of it will appear in index. Also this index entry is indented.

10. It also converts some special characters in index, eg: %3c (‘<’).

CHMBuilder Config file

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

<languages>

<language id="1033" codepage="65001" name="0x409 English (United States)" />

<language id="2052" codepage="936" name="0x804 Chinese (PRC)" />

</languages>

<hhpTemplate>

<line>[OPTIONS]</line>

<line>Compatibility=1.1 or later</line>

<line>Compiled file={0}.chm</line>

<line>Contents file={0}.hhc</line>

<line>Index file={0}.hhk</line>

<line>Default Topic={1}</line>

<line>Full-text search=Yes</line>

<line>Language={2}</line>

<line>[FILES]</line>

<line>icons\*.gif</line>

<line>art\*.gif</line>

<line>media\*.gif</line>

<line>scripts\*.js</line>

<line>styles\*.css</line>

<line>html\*.htm</line>

<line>[INFOTYPES]</line>

</hhpTemplate>

</configuration>

Cheers.

Anand..

Documenting APIs with Sandcastle using Windows Powershell

aram — Wed, 12 Sep 2007 02:34:00 GMT

Please see my blog about Sandcastle Spetember 2007 release. With this release, we plan on shipping an example Windows powershell script to document APIs using Sandcastle.

Why Windows Powershell

I saw what Scot Hanselman did for Sandcastle with Powershell and got the inspiration for creating a Windows powershell script for Sandcastle. BTW you can view Scott's latest show on DNR TV about Windows powershell at http://www.dnrtv.com/default.aspx?showID=82.

I have details about this new scripr below. The script that will be shipped is called “scbuild.ps1” and provides the following features:

Provides a single command wrapper to build CHM and HxS files regardless of where the source assemblies and comments are located. For example, to build the sample project we ship with Sandcastle use the following command:

scbuild –buildchm -buildhxs –framework 2.0 –sources test.dll,comments.xml
Allows the build options to be read from a configuration file. Options specified on the command line override options defined in the configuration file.
Handles any number of target assemblies and comment files, including globbing.
Handles any number of dependencies.
Should work with .NET 2.0, 3.0, and 3.5.
Supports vs2005, prototype, and Hana presentation styles.
Provides hooks to add new presentation styles in the future, including user defined styles, and user defined function overrides.
The script is written for PowerShell 1.0.

Prerequisites

The build script has the following dependencies:

September 2007 release of Sandcastle.
The DxRoot environment variable must point to the root of the Sandcastle installation.
To make it easier for the user, the PATH environment variable should contain the …/ProductionTools folder, which contains the scbuild.ps1 script.
.NET 2.0 for Sandcastle.
PowerShell 1.0, with the execution policy set to RemoteSigned or Unrestricted. [Note: In a future release we could Authenticode sign the script to make this unnecessary.]
hhc.exe to compile CHM files.
Hxcomp.exe to compile HxS files.

Running the Script

To run the script, open a PowerShell window and run scbuild with the “appropriate” options. You’ll want to make sure that DxRoot points to the root folder of the Sandcastle installation and [optionally] that your PATH variable contains the ProductionTools folder. Internally all Sandcastle executables are referenced relative to DxRoot; setting PATH is only necessary to avoid having to type the entire path to scbuild each time.

NOTE: If you’ve just installed PowerShell to run this script, you have to give it permission to execute scripts on your machine. If you don’t, PowerShell will refuse to execute any scripts that haven’t been Authenticode signed. To change the execution policy, open a PowerShell window and type the following command:

set-executionpolicy RemoteSigned

This allows the shell to execute all local scripts, as well as signed remote scripts. The setting is persistent.

Once that’s done, you can run the script. For a synopsis of the command line options available, see the header of …/ProductionTools/scbuild.ps1. Most of the options should be pretty self explanatory from the synopsis. I’ll expand on a couple of the more advanced features here.

Using the –Config Option

The –config option allows you to specify the options you would normally type on the command line in a configuration file. You’ll want to use this feature to easily manage build configurations or if the command line is too long for the shell.

The config file is a PowerShell script and the command line options are exposed as variables in “Script:” scope. For example, with the following statements in a file named “testconfig.ps1”:

$BuildChm = $true

$BuildHxs = $true

$Framework = "2.0"
$Sources = "test.dll", "comments.xml"

You can then run the build with this command:

scbuild –config testconfig.ps1

Using the –Mixin Option

The –Mixin option allows you to override any of the functions defined in scbuild.ps1 and DocModel.ps1, except for Init(), which is called before the mixins are loaded. Like the config file, the mixin file is a PowerShell script. It gets loaded just after scbuild and the doc model have been initialized, but before any of the build commands are executed. You can use this feature to add new functionality or to change build details.

NOTE: This feature is experimental. Future versions of the build script may be quite different, and functions and variables that exist in this version may not be there in future versions. Anybody using this feature should expect breaking changes.

For example, to override the function that copies the CHM file to its final destination you could create a script file named “testmix.ps1”:

function CopyChmToOutputDir {

WriteInfo "copy chm file to output directory with date"
MakePath $OutputDir

copy-item –force "$TempDir\Output\$($Name).chm" "$($Name)-$([DateTime]::Now.ToString('yyMMdd'))"

}

To run the build command with this mixin use:

scbuild –buildchm -buildhxs –framework 2.0 –mixin testmix.ps1 –sources test.dll,comments.xml

When you run this command, the output file name would now include the current date: test-070910.chm.

New & Changed Files

scbuild.ps1 requires a number of support files, but touches only one previously existing file: …/Prototype/Transforms/utilities_reference.xsl. In that file, we removed the HTML 4.0 doc type declaration, because the output from the transforms is not valid HTML 4.0 and having the doc type causes validation errors later in the tool chain. Eventually, the transforms should be fixed to produce valid XHTML 1.0 transitional and then the doc type declaration should be added back in.

Also, each presentation now has a new BuildAssembler config file named Sandcastle-scbuild.config. The new config differs from the previous Sandcastle config in that it includes a different set of reflection and comment files. It is necessary to make the build script location independent, and to support any number of input files.

The doc model specific scripts include a shared script: …/Presentation/Shared/SharedDocModel.ps1. This script defines functions that are the same for all doc models.

Note that the doc model specific script must be called DocModel.ps1, and no other directory under …/Presentation that does not define a doc model must have a DocModel.ps1 file in it. The presence of this file is used to determine if a particular style specified on the command line is a doc model, or just some other support directory like “Shared.” This allows us to add/delete doc models without touching the build script itself, and to ship different configurations that include only a subset of the doc models. It also allows the user to define a custom doc model.

Futures

Better error handling when intermediate build steps fail.
The script currently rebuilds all of the framework and dependency reflection data each time it is executed. This makes it easy to handle different frameworks and doc models. In a future version we can speed things up by keeping a copy of the data around and only rebuilding it on request.

Hope you all like this new script. Cheers.

Anand..

September 2007 Sandcastle Release

aram — Wed, 12 Sep 2007 02:19:00 GMT

Thank you all for the continued support to Sandcastle. I have had many questions about the next release of Sandcastle and the roadmap through forums (see http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2071190&SiteID=1 and http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2127456&SiteID=1&mode=1) and email

We will be releaing a new version of Sandcastle next week! This will be the version used for shipping Orcas RTM. This version of Sandcastle will include the following features:

Tools that we are using to ship Orcas RTM and Framework documentation
A CHM Builder tool for documenting CHM. Look for my blog about this tool.
New exciting features to VS 2005 design. This design will have features from Hana document model
New Powershell script to document your APIs. This will be shipped with the Example folder. Look for my blog on this shortly.

Cheers.

Anand..

Sandcastle - Interview with .NET Rocks

aram — Thu, 02 Aug 2007 21:36:00 GMT

In July I blogged about my interview with .NET Rocks! David Wright (Architect and developer of Sandcastle documentation compiler) from my team and I interviewed with .NET Rocks! The interview lasted about 90 minutes and Carl and Richard were amazing! J.

Please visit http://www.dotnetrocks.com/ or http://www.dotnetrocks.com/default.aspx?showNum=260 to this show. Hope you enjoy our interview. I will post another blog when this show becomes available on August 2nd, 2007. Cheers.

See Also

Gordon Hogenson: Documenting Development Technologies - http://channel9.msdn.com/ShowPost.aspx?PostID=311257

Fabrice Fonck and Molly Bostic: MSDN Wiki - http://channel9.msdn.com/ShowPost.aspx?PostID=299490#299490

Anand..

Componentization - Building Assembly level HxS using Sandcastle

aram — Wed, 25 Jul 2007 09:21:00 GMT

The primary goal of componentization is to reduce the size of a run-time image. In addition to helping meet space requirements, componentization has the following benefits:

Performance - Reducing disk and memory use can significantly improve performance of both the platform and your software.
Reliability - As a general rule, reliability increases with fewer executable files running and interacting with each other, devices, and the user.
Customization - Componentization allows for granular customization that is not possible using traditional setup programs.

Componentization using Sandcastle:

Sandcastle now allows us to build API documentation on a per-assembly basis. That is, we can build an HxS that contains documentation only for the types in a given DLL and then combine the HxS into a cohesive document set (e.g., create a unified TOC). We will be shipping "Orcas Beta 2" FxRef documentation as componentized HxS to improve our F1 performance within the VS IDE. This feature is available with Sandcastle June CTP.

How does this help with performance, reliability and customization?

When we shipped Windows SDK in November 2006 (http://blogs.msdn.com/windowssdk/archive/2006/11/08/windows-sdk-for-windows-vista-is-live.aspx) the Framework documentation was a 400 MB monolithic Hxs. This created performance and reliability issues for customer downloads and also impacted the F1 calls in VS IDE. Also customization was an issue when we wanted to ship documentation for certain assembly with VS Express SKUs.

Here are some of the issues we investigated before designing this feature in Sandcastle:

1. Size of HxS - HXS size could theoretically be a problem with an assembly-level HXS, but it won’t practically become a problem any faster than it would under our current practice (used in VS 2005 documentation) of namespace-level HXS. Our largest HXS under the current practice is for the System.Windows.Forms namespace. Those APIs pretty much represent the contents of the System.Windows.Forms.dll assembly, so under the new practice the largest HXS would remain about the same. Sandcastle provides infrastructure which will make it easy to build assembly-level HXS.

2. FX Issues - Building documentation for the APIs in an assembly does require information from other assemblies, not just for inheritance hierarchies, but also for parameter and return types, interface implementations, etc. In order to deal with this requirement, Sandcastle expects to have reflection data files for such other assemblies available while it is building documentation for one assembly.

3. Distributed build ownership – If you are a big corporation (like Microsoft) with different build teams then individual teams can maintain the ownership of building their assembly.

Here is an overview of assembly level build process using Sandcastle. We use MRefBuilder on each assembly to generate reflection data file. SegregateByAssembly generates reflection information for each assembly and BuildAssembler creats documentation (HxS) from the reflection data files. We use AggregateByNamespace utility, which creates a namespace reflection data files from a collection of assembly reflection data files. See a conceptual sketch below that describes this process:

Attached is a componentized builds sample for Sandcastle users. The steps below provide information on using this feature. Please install Sandcastle June CTP before trying the following:

1. Copy the attached file to “c:\program files\sandcastle\examples”;

2. Unzip it to folder “C:\Program Files\Sandcastle\Examples\componentized”;

3. Run “msbuild comp_build.proj”.

4. When done, assembly level Hxs files can be found under output\hxs and its subfolders.

5. You can copy your dlls to “C:\Program Files\Sandcastle\Examples\componentized\dll” and comments files to “C:\Program Files\Sandcastle\Examples\componentized\comments”.

6. The properties in comp_build.proj can be modified per you needs.

<PropertyGroup>

<Name>Sample</Name>

<PresentationStyle>vs2005</PresentationStyle>

<Framework>$(WINDIR)\Microsoft.NET\Framework\v2.0.50727</Framework>

<BuildDir>$(DxRoot)\examples\componentized</BuildDir>

<OutputDir>$(BuildDir)\Output</OutputDir>

<ProductionTools>$(DxRoot)\ProductionTools</ProductionTools>

<ProductionTransforms>$(DxRoot)\ProductionTransforms</ProductionTransforms>

<Presentation>$(DxRoot)\Presentation\$(PresentationStyle)</Presentation>

<Dlls>$(BuildDir)\dll\*.dll</Dlls>

<Comments> $(BuildDir)\comments\*.xml</Comments>

</PropertyGroup>

Let me know your feedback and I hope you like this feature. Cheers.

Anand..

Sandcastle and MTPS Conntent Service

aram — Fri, 20 Jul 2007 09:30:00 GMT

Sandcastle uses MSDN and Technet Publishing System (MTPS) content service to resolve refeence links to MSDN. MTPS processes all the content at MSDN and Technet. MTPS Content Services are a set of web services for exposing the content in MTPS. With this web service, users have programmatic access to all that data via SOAP. For details see http://www.pluralsight.com/blogs/craig/archive/2006/06/12/27273.aspx. According to this blog (http://www.pluralsight.com/blogs/craig/archive/2007/06/21/47807.aspx) MTPS content service is getting over 1.3 million hits per day.

PackgeThis application also uses this service. I installed and tried PackgeThis. It's a cool GUI C# application for creating help files (.chm and .hxs) for the content obtained from the MSDN Library via the MSDN Content Service. You can select the content you want from the table of contents, build a help file, and use the content offline. This application allows users to develop personalized ebooks of MSDN content. Both help file formats also give full text search and keyword search.

PackgeThis CodePlex site has a code that illustrates how to use the MSDN Content Service to retrieve documentation from MSDN. It also shows how to build .hxs files and .chm files programmatically.

Cheers.

Anand..