1. The generated CHM file doesn't seem to have an index. There's no Index tab displayed in the viewer.
2. The generated CHM file doesn't seem to have search capability. There's no Search tab displayed in the viewer.
3. When the CHM file is double-clicked to open it for viewing, the right-hand pane of the viewer shows a mostly-blank page with a small warning icon in the upper left-hand corner. This mostly-blank page goes away when any of the entries in the table-of-contents in the left pane are clicked.
4. In the CHM file, the documentation entries for class constructors always seem to have ".ctor" prepended to them.
5. The table of contents does not group together for each class its properties, methods, events, and constructors into separate subgroups. (Compare this to the current MSDN Library documentation for .NET 2.0.)
   
6. The entries in the table of contents for overloaded methods do not contain the parameter lists of the methods. (Compare this to the current MSDN Library documentation for .NET 2.0.)
7. The summary page for each type (i.e. class) is missing Namespace and Assembly information. (Compare this to the current MSDN Library documentation for .NET 2.0.)
8. The inheritance hierarchy displayed at the bottom of the page for each class does not include the namespace for each class in the hierarchy. (Compare this to the current MSDN Library documentation for .NET 2.0.)
9. The language drop-down in the upper right-hand corner contains entries for just C# and VB, while the Syntax section contains entries for C#, VB, and Managed C++.
   
10. There are some typos in the error messages emitted by some of the tools (.EXEs) that are part of Sandcastle.
11. The Sandcastle installer doesn't seem to set any registry keys that indicate the installation path.

WN,

I agree that we should add the list of know issues and I will post a blog about this in future. I have provided answers to your questions below.

1. The generated CHM file doesn't seem to have an index.  There's no Index tab displayed in the viewer. {Anand} Fixed for our August CTP due later this week
2. The generated CHM file doesn't seem to have search capability.  There's no Search tab displayed in the viewer. {Anand} Please see suggestion from parheric. This will increase the size of your CHM. 
3. When the CHM file is double-clicked to open it for viewing, the right-hand pane of the viewer shows a mostly-blank page with a small warning icon in the upper left-hand corner.  This mostly-blank page goes away when any of the entries in the table-of-contents in the left pane are clicked. {Anand} This is an issue due to missing root node in your HHP and has been fixed for our August CTP due later this week
4. In the CHM file, the documentation entries for class constructors always seem to have ".ctor" prepended to them. {Anand} Fixed for our August CTP due later this week
5. The table of contents does not group together for each class its properties, methods, events, and constructors into separate subgroups.  (Compare this to the current MSDN Library documentation for .NET 2.0.)
   
6. The entries in the table of contents for overloaded methods do not contain the parameter lists of the methods.  (Compare this to the current MSDN Library documentation for .NET 2.0.)
7. The summary page for each type (i.e. class) is missing Namespace and Assembly information.  (Compare this to the current MSDN Library documentation for .NET 2.0.)
8. The inheritance hierarchy displayed at the bottom of the page for each class does not include the namespace for each class in the hierarchy.  (Compare this to the current MSDN Library documentation for .NET 2.0.)

{Anand} For 5 through 8 we will release an MSDN compatible transform in future. The look and feel you got is a part of the new documentation model for our future releases.

     9.The language drop-down in the upper right-hand corner contains entries for just C# and VB, while the Syntax section contains entries for C#, VB, and Managed C++.

{Anand} We will address this in future. You will also be seeing XAML.

     10. There are some typos in the error messages emitted by some of the tools (.EXEs) that are part of Sandcastle. {Anand} Sorry about this and we have fixed them for our August CTP due later this week. Please email the typos you are seeing to me. Thanks.

     11.The Sandcastle installer doesn't seem to set any registry keys that indicate the installation path. {Anand} I will track this. Thanks.

Anand..

I'd like to expand the list of questions. :-)

12. Sandcastle, like NDoc, doesn't seem to support the Compact Framework. Is this something that will be adressed in Sandcastle?

Edward - We do have plans to address this. What would you like to see? Could you please ealborate?

Anand..

I have only recently tried SandCastle when NDoc failed building the documentation for my PocketPC project. All I really want to see is support for the .Net Compact Framework namespaces; i.e. recognition of .Net 1.0.5000 versions. Currently the only recognized versions are 1.0.3705, 1.1.4322 and 2.0.50727 full framework which renders build errors for version number of System.* namespace (1.0.5000.0) and specifically System.Data.SqlServerCe. So basically all I want is recognition of Compact Framework 1.0 and 2.0 assemblies. :-)

I have no desire to create output for the PocketPC/Windows Mobile form factor. All I want is to be able to create a documentation of my projects for future reference. I want to move away from "Read the Source, Luke" to only having to take a quick look at an up-to-date documentation. Not much of an elaboration perhaps but I hope it describes my desires regarding SandCastle.

Anand,

I want to join Edward regarding his question about Sandcastle and .NET Compact Framework.

I tried to change sandcastle.config file to point to XML files that are distributed with .NET Compact Framework 2.0. This didn't help me. I looked at XML files and found that they just redirect somewhere else (probably to desktop version of XML files). But desktop framework has different version of assemblies.

Could you provide more information about plans to address this issue? September CTP? October CTP?

I'm building class libraries (DLLs) for compact device. The users of these libraries will use Visual Studio on desktop computers to build end-user application. Therefore a regular CHM file would be sufficient for them. So, it seems the only problem is in absence of appropriate XML files with reflected data for compact framework.

May be such files exist and I just don't know where to get them from?

By the way I'm using Sandcastle to build documentation for desktop systems as well. I have no any problems when building documentation for desktop framework. The tool looks very promissing.

Regards, Roman.

Have you triend changing the framework path in Sandcastle.config file to see if it works for compact framework. Look at copy comments section for the following:

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll">
<index name="comments" value="/doc/members/member" key="@name" cache="100">
<data files="comments.xml" />
<data files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\*.xml" />
</index>
<copy name="comments" source="*" target="/document/comments" />
</component>

and change the highlighted path to the appropriate version. Please let me know.

Anand..

I changed the path indicated in your post to point att my Compact Framework 1.5.0000 folder and tried to build without success. I could build the helpfile for the test.cs included with Sandcastle without problems but when running MrefBuilder I get the same unresolved reference error as before.

> C:\Program\Sandcastle\ProductionTools\MrefBuilder.exe mistelpda.exe /out:reflection.org
MRefBuilderStatic (v2.0.2424.18753)
Copyright Microsoft Corp. 2005
Error: Unresolved assembly reference: System (System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=969db8053d3322ac) required by MistelPDA

I noticed that the .Net Framework versions 1.0.3705, 1.1.4322 and 2.0.50727 are all installed on my system in "C:\Windows\Microsoft .Net\Framework\<Framework version>\" where as the Compact Frameworks files are located in a CompactFrameworkSDK folder under the Visual Studio folder. Most likely SandCastle tries to reference a namespace located in the GAC and the Compact Framework namespaces aren't stored there.

Anand,

this is exactly what I was trying to do before I posted my previous message.

On computer with Visual Studio 2005 the DLLs and XML files for .NET Compact Framework are usually located at:

C:\Program Files\Microsoft Visual Studio 8\SmartDevices\SDK\CompactFramework\2.0\v2.0\WindowsCE

On computer with .NET Compact Framework only (no Visual Studio) the same files can be found at:

C:\Program Files\Microsoft.NET\SDK\CompactFramework\v2.0\WindowsCE

In both cases the size of XML files is less than 1Kb. The content of System.xml, for example, looks like:

==============================================================

<?xml version="1.0"?>
<doc redirect="%CORSYSDIR%System.xml">
</doc>

==============================================================

In other words, it redirects somewhere (where?).

MrefBuilder fails when I change config file to point to these XML files.

What's interesting is that before .NET Compact Framework 2.0 the XML files for compact DLLs contained actual data instead of redirection. You will see it if you look at XML files at:

C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE

Regards, Roman.

Roman,

Thanks and this is helpful. I will tack this for a repro. at our end and will provide a fix ASAP.

Anand..

We use the xml file for generating summary information. You should be fine with using what is shipepd wtih Sandcastle by specifying C:\Program Files\Sandcastle\Examples\Cpref_reflection|*.xml or C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\*.xml

Please let me know if it works and if you able to build for compact framework.

Anand..

Anand,

no, this doesn't help. Here is what I do:

1. I have clean installation of Sandcastle August CTP.

2. In Visual Studio 2005 I created default "Device Application" for Pocket PC 2003. In project properties I changed the name of XML file to be generated to "comments.xml" ot simplify the work with default installation of Sandcastle.

3. I compiled the project and copied "DeviceApplication1.exe" and "comments.xml" files to "C:\Program Files\Sandcastle\Examples\Test" folder.

4. Following the http://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx article I enter in command prompt the next command:

MrefBuilder DeviceApplication1.exe /out:reflection.org

Thus way I use default config file with

=============================================================================

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll">
<index name="comments" value="/doc/members/member" key="@name" cache="100">
<data files="comments.xml" />
<data files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\*.xml" />
</index>
<copy name="comments" source="*" target="/document/comments" />
</component>

=============================================================================

I'm getting the following message:

=============================================================================

MRefBuilderStatic (v2.0.2424.18753)
Copyright Microsoft Corp. 2005
Error: Unresolved assembly reference: System.Windows.Forms (System.Windows.Forms
, Version=2.0.0.0, Culture=neutral, PublicKeyToken=969db8053d3322ac) required by DeviceApplication1

=============================================================================

If I add the /dep: option to point to compact dlls (as you advised earlier) I get exactly the same message.

Do you see something wrong in what I'm doing?

Regards, Roman.