Project Status?

Feb 28, 2011 at 8:59 PM

Is this project still alive?

In June 2010, we were told this tool was what Microsoft used to build the .NET Framework 4.0 documentation, but today it still doesn't support .NET 4.0 assemblies.

Looking through the developers and coordinators for this project, the only activity in the last 60 days was by Darren Parker, who closed a two-year-old bug report as "not a Sandcastle bug". None of the others have visited CodePlex at all since last June. The last update on the MSDN Sandcastle blog is from June as well.

Eric seems to be the only person answering questions in here. He's doing a great job, but he's not a "developer" on this project, and he's not a Microsoft employee, so I doubt he has access to fix any of the outstanding issues that Microsoft have forgotten.

This is all very reminiscent of the NDoc project after the .NET 2.0 release. Has Microsoft has abandoned this project? Is anyone else going to take over development? Or do we have to start looking for yet another tool to build our documentation?

Editor
Mar 1, 2011 at 1:17 AM

I heard from Darren in November at which time a future update was planned.  I've sent him an e-mail to see if he can comment here on an updated timeline and planned fixes.

Eric

 

Mar 2, 2011 at 9:18 PM

I'm wondering about this also. I'm looking at generating documentation about a framework we've been developing, and my first thought was Sandcastle. Problem for me was that it's very hard to start with, but after a lot of hours, I now have aspx pages generated in the old VS2005 syntax (also with bugs in it as the aspx pages contain links to htm pages instead of other aspx pages).

I now have a few things I'm wondering about.

1. There have been several questions if there will be support for generating the msdn 2010 style, which I would really prefer over the vs2005 style
2. I want to add some extra information to the pages, so I was starting to look into creating a buildcomponent for this. However, if there is no real active development from MS on this project, I don't see much use in working on a custom buildcomponent, but I'll have to figure out other ways to generate the required documentation.

Hope there will be a clear answer on the future of this project.

Mar 2, 2011 at 10:19 PM

>>KoenWillemse: ...msdn 2010 style, which I would really prefer over the vs2005 style

The MSDN 2010 style will only support the MS Help Viewer platform, so unless you are plugging into the
that help collecton, it is really not useful.

The MSDN 2010 style is clearly work in progress, if you have being following the changes in the MSDN, so
until it is finalized, Sandcastle release for this will be useless. My guess is after VS2010 SP1 is released with
its offline viewer, we might see a completed version of the MSDN 2010 style, which could be supported by
the Sandcastle.

>>KoenWillemse: ..so I was starting to look into creating a buildcomponent for this..

The current release is complete and usable, and any build component, which takes into account the style type
will have to make adjustments for each style, so I see no reason why you cannot continue with your custom build
component, and update it to support later Sandcastle releases.

Best regards,
Paul. 

Mar 3, 2011 at 11:32 AM

>> SelormeyPaul: The current release is complete and usable ...

Unless you're trying to document .NET 4.0 assemblies, in which case the output is useless gibberish!

Mar 3, 2011 at 12:23 PM

>>richarddeeming: Unless you're trying to document .NET 4.0 assemblies...

The result you are seen there is a bug in the SHFB and has nothing to do with Sandcastle. SHFB is setting the
the source directory for .NET 4.0 to that of .NET 2.0, so you get that result. 

May be it is fixed in the new release of the SHFB, I cannot tell - please, verify that.

Best regards,
Paul. 

Mar 3, 2011 at 12:58 PM

Strange - I reported it as a bug in SHFB, and was told by Eric that it was a bug in MRefBuilder, which is why I reported it here.

I've just tried SHFB v1.9.2, and apart from 60Mb of warnings like [1], there's no difference in the output.

Eric - any comments on Paul's analysis? Is this a bug in Sandcastle or SHFB?

 

[1] Warn: CopyFromIndexComponent: Entries for the key 'F:System.IO.Ports.StopBits.One' occur in both 'C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.xml' and 'C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\Profile\Client\System.xml'. The last entry will be used.

 Warn: CopyFromIndexComponent: Entries for the key 'F:System.IO.Ports.StopBits.One' occur in both 'C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.xml' and 'C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\Profile\Client\System.xml'. The last entry will be used.
Mar 3, 2011 at 1:23 PM
Edited Mar 3, 2011 at 1:26 PM

Not a bug in MRefBuilder, but in the use of the MRefBuilder. The platform version and path could be
confusing, see below: 

Try this, if you are using the sample posted there...

1. Set the "clean intermediates" property to false.

2. Build the help, go to the output directory and examine the MRefBuilder.config file.

3. If it displays the following line for the platform for the .NET 4.0 build, then that is the source of the problem 

<platform version="2.0" path="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\" />

4. Now, go to the SHFB installed directory, and in the Template folder, create a backup of that configuration file for later
restoration, manually change the platform to look like this...

<platform version="2.0" path="%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\" />

Save this file. Build again and see the results. Restore that configuration after the verifications.

NOTE: For .NET 2.0 and later, the platform version should be 2.0, otherwise, you will get an exception. 

Best regards,
Paul. 

Mar 3, 2011 at 1:40 PM

Excellent! It's definitely a bug in SHFB, not Sandcastle.

The tempate config file had:

<platform version="{@MRefFrameworkVersionShort}" path="%SystemRoot%\Microsoft.NET\Framework\v{@MRefFrameworkVersion}\" />

Despite setting the framework version in the project file to v4, the output config file had:

<platform version="2.0" path="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\" />

I've replaced the line in the template config file with:

<platform version="{@MRefFrameworkVersionShort}" path="%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\" />
and now the file is generated perfectly.

Thanks for your help.

Editor
Mar 3, 2011 at 3:30 PM

I know MRefBuilder won't accept a version value greater than 2.0 and was under the impression that the path had to match the version.  I'll adjust SHFB so that it uses the selected framework path.  I'd still call this a problem with MRefBuilder since it should accept a version that matches the path.  This would avoid such confusion.

Eric