Preparing to Fork Sandcastle

Apr 18, 2010 at 4:46 PM

Hello Sandcastle Community,

Clearly, our beloved Sandcastle is dying slowly and we have to work on it. 

I am preparing to fork a community edition of the Sandcastle. Those who have invested in
the Sandcastle for their documentations will soon need to move to .NET 4.0.

The new project will be called Sandcastle Community Edition (Sandcastle CE, for short),
since it will be developed and maintained by the community.

Anyone ready to join?

Best regards,
Paul. 

 

Editor
Apr 19, 2010 at 2:03 AM

Paul,

I think you should hold off for a while.  I heard from Anand last week.  He is turning the project over to a new owner that will manage the future releases of Sandcastle here on CodePlex.  They are working on a new release of Sandcastle that supports VS 2010 and the Microsoft Help Viewer.  Since it is not truly dead yet, I'd rather not see a forked version that goes off in its own direction.

I agree that it was disappointing that the July 2009 version was never officially released and the lack of bug fixes in it was frustrating.  However, I'm willing to wait and see what happens with the next release and to see if the new owner will come through and address the known issues, if not in this upcoming release then at least at some point in the near future.

Eric

 

Coordinator
Apr 19, 2010 at 3:55 AM

Thanks Eric and Paul.

Paul - I am currently working with my colleague, Darren Parker to manage Sandcastle releases in codeplex. We are working on a new release of Sandcastle after our release of VS 2010 and

it's new Microsoft Help Viewer. We are currently discussing with Eric about Sandcastle and SHFB and how to align the releases. Darren will chime in shortly. Cheers

 

Anand..

Apr 19, 2010 at 4:09 AM

Hello Eric and Anand,

I understand and will wait for your next move. I have being trying to plan my own project, but do not
know how to proceed. Getting tired of waiting, I decided to act.

Now Anand, lets hear from the new leadership. Hope you will open the project for others to join and move it
quickly forward.

Best regards,
Paul. 

May 5, 2010 at 8:57 AM

Hi Anand

I've been successfully building documentation for assemblies using the 4.0 framework (using the latest Styles patch and Eric's helpful suggestion for updating the supported framework versions).  For the most part, things run smoothly, however: referencing System.ServiceModel.Web causes MRefBuilder to crash at Microsoft.Ddue.Tools.Reflection.NamespaceFilter.IsExposedNamespace(Namespace space) with a NullReferenceException.  I haven't yet figured out how to work around this, so for the moment we won't be building documentation for our server module.

Is this fixed in the current source tree?

Thanks
David 

 

Coordinator
May 6, 2010 at 2:22 AM
Edited May 6, 2010 at 2:22 AM

Hi everyone.

My name is Darren Parker.  My team is now responsible for taking care of Sandcastle. As Anand already mentioned, Sandcastle is alive and well, we have just sort of been heads down trying to get VS2010 shipped.  Now that its out the door we can concentrate on improving Sandcastle for everyone.

We plan on two releases in the near future:

  • Release code to allow Sandcastle to generate cabs (MSHC files) as output for integration with the new Microsoft Help Viewer that shipped with VS2010.   The code is done, we are currently just waiting on a few loose ends to clear up before we have the green light to post it. I am hopeful that this can happen in the next week or so. If it is longer than that I will keep you in the loop.
  • We are starting work now on a new release.  Since the last public release of Sandcastle, we have obviously had to make many bug fixes and add functionality in order for us to accurately document VS 2010 and .NET 4.  We will be integrating all of these changes, test and will repost as soon as we can. My goal is to get this released by early June.

Longer term:

We are already working on a new content build system and have plans to also release this as Sandcastle v2.  I will provide more details about this in a later post.

On a side note, David Wright (who was the original dev for Sandcastle) and I will be at TechEd in New Orleans 7-10. If any of you are interested in hooking up with us that week, let me know.  We won't have a booth, but would love to meet some of you for drinks, dinner etc. and at the same time talk about the current state and future of Sandcastle. 

Thanks!

Darren

 

May 6, 2010 at 5:30 AM

Hello Darren,

Thanks so much for the information and keeping the Sandcastle alive. We really appreciate this.

>> We plan on two releases in the near future:

The difference between the two releases is really not clear. The first only to add MSHC with
bugs intact and then the next release the address the bugs?

>>  We are already working on a new content build system and have plans to also release this as Sandcastle v2.

The current version of the Sandcastle is 2.4.10520.

>>  I will provide more details about this in a later post.

Can you take over the Sandcastle blog too?

Best regards,
Paul. 

Coordinator
May 6, 2010 at 6:03 AM
Edited May 6, 2010 at 6:10 AM

You are correct about the two releases, the first one is only to add the functionality to build the MSHC files, with current bugs intact. Then the next release, which we are starting work on now, will address bugs that have been fixed over the last year.

 

With regards to the versioning of Sandcastle, it is probably more appropriate for me to say that we are working on ‘VNext’ of Sandcastle instead of v2 since as you point out we already versioned the current binaries with a major version of 2.

 

I will also start posting to the Sandcastle blog.

 

Thanks,

 

Darren

 

May 6, 2010 at 7:49 AM
Edited May 6, 2010 at 7:49 AM

Hi Darren,

Thanks for the info.

Are you planning on providing a new VS 2010 presentation style as well?  A blog post alluded to the answer already: no.

It you're not, then it significantly lowers Sandcastle's value.  Some people in the community could develop one, and try to keep it up-to-date, but that would be a tremendous task.

I've always felt that one of the main features of Sandcastle has been that it produces documentation with the look and feel of MSDN, and that Microsoft writes and maintains the XSLT files to keep everything in sync.

Thanks,
Dave

May 6, 2010 at 10:08 AM

Hi Darren;

Thanks for the update and keeping us all in the loop.

I have to agree with Dave, that providing the ability to produce documentation with the same look and feel as the current MSDN very much helps keep our documentation products "up to date" with our target audience, and this has always been one of the great features of Sandcastle.

It would be avery backward step if Microsoft decided to cease developing the presentation styles in line with future releases of Sandcastle and I am hoping that serious consideration can be given to the inclusion of the VS2010 style.

Kindest Regards

Dave Ballantyne

Coordinator
May 6, 2010 at 3:30 PM

Sandcastle does produce MSDN look and feel docs. MSDN currently has 3 different look and feel:

  1. Classic
  2. Scripft-Free
  3. Lightweight

 See my post on this at http://blogs.msdn.com/innovation/archive/2009/10/26/launching-lightweight-beta-view-for-msdn-library.aspx

Sandcastle supports "classic" look and feel. I am not sure if we will be able to support the other presentation styles. Darren can answer that. Hope this helps.

 

Anand..

May 21, 2010 at 6:46 PM

So, what happened to the

I am hopeful that this can happen in the next week or so. If it is longer than that I will keep you in the loop.

from 6th of May?

That was a little more than 2 weeks ago. Like so many... I am waiting with even core documentation generation for a new build ;)

By now it is even already nearly time for

in order for us to accurately document VS 2010 and .NET 4.  We will be integrating all of these changes, test and will repost as soon as we can. My goal is to get this released by early June.

When can we expect some release, especially in the light of projects moving to .NET 4.0?

 

Coordinator
May 21, 2010 at 6:55 PM

We have actually decided to just combine it all into one release instead of doing two releases, , thats why its taking a little longer.   So this release will contain all bug fixes from the last year, in addition to support to build the correct html for the new Help format

the current status is that we are doing final testing. If all goes well, I will release it on Monday or Tuesday.

If anything changes from this schedule I will let you know.

Darren

May 22, 2010 at 2:03 AM

Hello Darren,
Thanks for the information and the work. 

>>DarrenIf anything changes from this schedule I will let you know.

How about starting a release cycle (Beta and/or RC)? Many MS projects here on CodePlex go through it.

Best regards,
Paul. 

Coordinator
May 25, 2010 at 3:09 PM

Unfortunatley we won't be able to release today.  We are working on it though! There were a few ship stoppers that were identifed thanks to Eric Woodruff that we really need to take care of before we release.

May 27, 2010 at 3:58 AM
Edited May 27, 2010 at 3:59 AM

 Hello Darren,

Do you have a ETA on when you are going to release? Any way to get a beta version of the next release? (I guess I just can't wait).....

 

Thanks

 

Jun 1, 2010 at 11:24 PM

I'd be happy with even an expected week. I'd love it sooner, but I'd rather have it working well than working now.

 

(Posted mostly to add that I'm interested in the new version)

Coordinator
Jun 2, 2010 at 12:08 AM

Hey all,

It's awesome to see all the interest in Sandcastle!!  I realize that you all have been waiting patiently for quite a long time since our last release.

The current status is that we are nearly done fixing the issues that were found during testing.

The good news is that we did fix a bug that many of you are aware of, - Members being removed in types that contain Action<T> delegates and/or new .NET 4 generic types such as Tuple<T>. This actually ended up being a bug in CCI that we had to code around.
This fix was submitted to test, and they found that this change has problems with the new code that was added to generate the MSHC compatible output files for the new Help Viewer in VS 2010.  Our dev is working on this as we speak and am hoping that he has a fix ready for test today.   

So in short, we are working very hard to release this as soon as possible, but I agree with rangoric, I would rather wait and release something that is going to work well for you.

Darren Parker

P.S. I mentioned this before, but if anyone is going to TechEd in New Orleans next week and wants to meet up with our team, send me a mail.  

 

Jun 2, 2010 at 1:05 AM

>>Darren: ...but I agree with rangoric, I would rather wait and release something that is going to work well for you.

I think the whole issue of release beta is to have others test and give feedback in order to release a  more robust application.
Each Sandcastle release fixes bugs, but brings in other bugs - minimizing this is a good thing for all of us.

>>Darren: ...TechEd in New Orleans next week and wants to meet up with our team

I thought you just returned from one conference/shows! I will need to be educated on what developers actually gain out of these conferences/shows - anyone?.

Best regards,
Paul. 

Jun 2, 2010 at 1:36 AM
SelormeyPaul wrote:

>>Darren: ...but I agree with rangoric, I would rather wait and release something that is going to work well for you.

I think the whole issue of release beta is to have others test and give feedback in order to release a  more robust application.
Each Sandcastle release fixes bugs, but brings in other bugs - minimizing this is a good thing for all of us.

>>Darren: ...TechEd in New Orleans next week and wants to meet up with our team

I thought you just returned from one conference/shows! I will need to be educated on what developers actually gain out of these conferences/shows - anyone?.

Best regards,
Paul. 

What I like about Conferences is the chance to ask very specific questions or have talk/demos of technology that you just don't have time to dig into or find things on yourself.

It is also good for networking or just chat with people who actually have similar interests.

Jun 2, 2010 at 2:12 AM

Hello rangoric,

Thanks for the information and the head up.

>>rangoricWhat I like about Conferences is the chance to ask very specific questions or have talk/demos of technology...

Normally get enough from MSDN documentations, forums and blogs. and books. StackOverflow and Codeproject forums/articles
fill in the missing gaps. You will be surprised to know people hardly try to use and understand the SDK samples, which normally
provide the demo of the technologies. 

>>rangoricIt is also good for networking or just chat with people who actually have similar interests.

MS is investing so far in its social forums, I do not know why this is still not sufficient.

Anyway, thanks for the information, and sorry for this off-topic question.

Best regards,
Paul. 

Jun 3, 2010 at 4:13 PM

I agree overall. And I don't tend to attend them. However, I did go to Heroes Happen Here for the VS2008 release. If there was something similar in my area for the VS2010 release I would have tried to go also, as it was a nice setup to hear about the new features.

As for wanting a Beta release, that'd be nice, but it would also be a release they have to set up, that would take time away from finishing it. Once there is a stable release for it, then beta releases for new features/functionality would be great as they can be less structured, since there is a stable release to point to and say use that, but if you want to try X add this.

Jun 6, 2010 at 10:45 AM

I agree. I find all these delays a LOT more irritating than working with a system that may have a bug or generate partial documentation for the moment. It will take me a week or two to get thigns into TFS and our build cycle anyway.

Right now, sadly, the situation is "no code at all" and I am starting to be sad MS even released sandcastle (and thus killed off ndoc), only to then disappear with any usable release for what is ages in internet time.

Jun 10, 2010 at 8:09 PM

Agreed - very much looking foward to the latest release/update! Sandcastle has been great, but we really need to be able to produce the mshc files directly (instead of our current workarounds). Any information on a possible date?

Katy

Jun 11, 2010 at 4:34 PM
This stops being funny. How big can an issue be stopping the release, when Visual Studio 2010 is out and - according to the information you gave - Sandcastle was used to build the 2010 documentation? Seemed to work there pretty well (apart from the new help system being a hugh step backward). Sandcastle killed off ndoc being "the official microsoft tool", and now - it is "nothing that exists outside of Microsoft".
Coordinator
Jun 11, 2010 at 5:26 PM

Sorry for the lack of posts this week as I have been at TechEd.  I checked my my team and they tell me me that we should be ready to release by next Friday. June 18th.  Believe me when I say that there is a lot more to getting this release out than you might think and if I could speed it up I would. 

One clarification ttomiczek, the code that Sandcastle is based upon (Manifold) was indeed used to generate the initial topics for VS2010, but that was only the first step in the publishing process.  We took that content and published it into the system that produces the MSDN Online Library.  The content was then organized and extracted from that system and then the MSHC cab packages were built from that source.  Sandcastle did not do that part.  This is part of the reason this is taking a little longer, as we have had to go back and retrofit Sandcastle to also build MSHC ready topics, it wasn't just a matter of reusing the same code. 

Once we release, Sandcastle will have the ability to produce MSHC compatible topics,.  The topics will not have the exact same look and feel as the MSDN Lightweight look that you see in the VS2010 docs.  There is is additional retrofitting work that we will need to do for that, 

Once we get past this large release I will get us on a regular and more frequent release cycle.

Darren 

Jun 11, 2010 at 10:33 PM

Once we release, Sandcastle will have the ability to produce MSHC compatible topics,will not have the exact same look and feel as the MSDN Lightweight look that you see in the VS2010 docs. 

 So just to get this correct, the version coming out next week will not have any updates for style? We'll still have just VS2005, hana, and Prototype? How long would it be until additional styles were released? When we take our HxS output (VS2005 style) and convert it, we're running in to an issue where all the fonts are really tiny and we've had to just manually change the Presentation.css file. Unfortunately, we then have to maintain two Presentation.css files - one for creating our HxS help and one for creating the MSHelpViewer help. Maybe someone else has seen this problem and has a suggestion?

Katy

Jun 16, 2010 at 5:09 AM
katydalton wrote:

Once we release, Sandcastle will have the ability to produce MSHC compatible topics,will not have the exact same look and feel as the MSDN Lightweight look that you see in the VS2010 docs.

 So just to get this correct, the version coming out next week will not have any updates for style? We'll still have just VS2005, hana, and Prototype? How long would it be until additional styles were released? When we take our HxS output (VS2005 style) and convert it, we're running in to an issue where all the fonts are really tiny and we've had to just manually change the Presentation.css file. Unfortunately, we then have to maintain two Presentation.css files - one for creating our HxS help and one for creating the MSHelpViewer help. Maybe someone else has seen this problem and has a suggestion?

Katy

 Hi, personally, i don't like new lightweight MSDN version just for large fonts and space wasting between paragraphs. I will stay with "old" VS2005 style :-)

Jun 19, 2010 at 4:27 AM
DarrenParker wrote:

I checked my my team and they tell me me that we should be ready to release by next Friday. June 18th.

That was like yesterday ;) And nothing appeared. May I ask what year you live in? Maybe "next Friday" is next Friday 2110 for you ;)

Seriously, though, when can those of us stuck in nether nether land thanks to MS "publishing" sandcastle and thus killing of ndoc.... start getting documentation generated? Next month? (i.e. in 2 weeks)? 

Editor
Jun 19, 2010 at 8:51 PM

Let's be fair.  Sandcastle was not the only reason NDoc died.  People being rude and demanding the next release that supported .NET 2.0 and the general lack of support from the community played a much larger part in its demise.  Have some patience.  I'd rather see a working copy that properly supports .NET 4.0 released rather than a version that doesn't work correctly.  If it had been released, we'd just see people complaining about the lack of proper support since it would effectively be no better than what we have available to us now.

Eric

 

Jun 21, 2010 at 10:16 AM

All fine with not releasing "a version that doesn't work correctly", however, I'd still like to see a prerelease/alpha/whatever since we (and also others, I guess) would like to test build integration as well as get a general feeling for the new help format. I just can't believe that there are no snapshots that are at least partially working (i.e. don't crash for reasonable input and generate at least some kind of Help3). Source code together with a big fat warning would be completely sufficient (the last source snapshot dates back from July 2009 - where is all that development happening???). At the very least, a status update would be nice - we have to decide whether to wait even longer, to convert the documentation with h3migrate or to buy a commercial solution (which would be a shame, since one thing we really like about SC is the great amount of flexibility it offers).

I know, much work and (probably) too few developers, so I don't want to sound too ungrateful - after all it's free and it is a really great solution.

JM

Jun 21, 2010 at 5:02 PM

I would be happy to have a simple status update if it gets to a stated release date and the release is not going to happen.

Coordinator
Jun 22, 2010 at 12:20 AM

Status Update:

Test has signed off on the code.  Currently we are waiting for the codesigning process on the MSI to finish so that we can publish.

Darren

Jun 22, 2010 at 7:43 AM
DarrenParker wrote:

Status Update:

Test has signed off on the code.  Currently we are waiting for the codesigning process on the MSI to finish so that we can publish.

Darren

Hurrah! As none of us are paying for this product I don't think we can complain when it takes time to release a new version - although I do recognise some of frustrations people have mentioned.

Jun 22, 2010 at 3:24 PM
Any news when the updated version will be available for download? We hit a severe bug in Sandcastle (Action<T> related; mentioned above) that prevents generating a correct help system for our .NET 4 app and we already postponed our launch because of this bug. Any information about the plans for releasing the new build of Sandcastle would help A LOT. Kind regards, Rainer.
Coordinator
Jun 24, 2010 at 4:57 AM

Latest version has now been posted to CodePlex.  Thanks for your patience!

http://sandcastle.codeplex.com/releases/view/47665 

Darren

Jun 24, 2010 at 5:21 AM

Darren: >>Latest version has now been posted to CodePlex.  Thanks for your patience!

Thanks for the work and efforts put into releasing the update. I will start testing it this weekend to
see how to work with it.

BTW: The sandcastle-mshc-how-to-use.txt says....

Sandcastle code modified by ComponentOne to support the Microsoft Help Viewer 1.0 MSHC target format

Did you accept the forked version by ComponentOne or contracted ComponentOne for this release?

Best regards,
Paul. 

Coordinator
Jun 24, 2010 at 5:32 AM

Thanks Paul. It was definitely a learning experience for me and I promise to get us on a more frequent release schedule moving forward.

We contracted ComponentOne to do the work to modify the Sandcastle code to be able to generate the MSHC files.

Since we didn’t use Sandcastle to actually generate the final mshc packages that shipped with VS 2010, we needed to retrofit Sandcastle so that the community would have a tool that could create this content.

Darren

From: SelormeyPaul [mailto:notifications@codeplex.com]
Sent: Wednesday, June 23, 2010 10:22 PM
To: Darren Parker
Subject: Re: Preparing to Fork Sandcastle [Sandcastle:209712]

From: SelormeyPaul

Darren: >>Latest version has now been posted to CodePlex. Thanks for your patience!

Thanks for the work and efforts put into releasing the update. I will start testing it this weekend to
see how to work with it.

BTW: The sandcastle-mshc-how-to-use.txt says....

Sandcastle code modified by ComponentOne to support the Microsoft Help Viewer 1.0 MSHC target format

Did you accept the forked version by ComponentOne or contracted ComponentOne for this release?

Best regards,
Paul.

Read the full discussion online.

To add a post to this discussion, reply to this email (Sandcastle@discussions.codeplex.com)

To start a new discussion for this project, email Sandcastle@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe or change your settings on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com

Jun 24, 2010 at 6:25 AM

Hello Darren,
Thanks for the reply and the information. 

Darren: >>It was definitely a learning experience for me...

Thanks for doing everything possible to pull it out, we really appreciate this.

Darren: >>...and I promise to get us on a more frequent release schedule moving forward.

Your quick response is already an evidence you are ready for the pressure and leadership of this project.

Darren: >>Since we didn’t use Sandcastle to actually generate the final mshc packages that shipped with VS 2010...

Right, my guess was you contracted ComponentOne. However, the main reason for asking that question is why
is it still a problem to completely host the project here? since all point to the fact that Sandcastle is not being
used for the MSDN deployments, which means, it is more for the community than for MS own projects.

My fear is whether the cost of continual development and maintenance at the MS can be justified. Anything that
will give some form of hope to the community is highly welcome.

Best regards,
Paul. 

Jun 28, 2010 at 1:55 PM
Edited Jun 28, 2010 at 10:42 PM

Darren, can you tell us what tool was used instead of sandcastle for Visual Studio 2010?

Update: I see you discussed that a bit in the thread. Still I am curious about the details, why Sandcastle could not be used directly. Thanks.

Coordinator
Jun 29, 2010 at 1:04 AM

Frank,

In the previous releases(2005 & 2008)  of Visual Studio we generated HxS using Sandcastle which was consumed by DExplore (previous  Visual Studio Help Viewer). We released a new version of Help Viewer (Microsoft Help Viewer 1.0) for VS 2010 (http://channel9.msdn.com/posts/kmcgrath/Help-30-New-Help-System-in-Visual-Studio-2010/). Unlike DExplore, Microsoft Help Viewer 1.0 uses MSHC format.

We generated HxS for Visual Studio 2010 help using Sandcastle, which was then decompiled and transformed into MSHC format. All of this decompile and transformation process was done as a part of our MSDN/TechNet Publishing System (MTPS) process.

In summary, Sandcastle was used to generate help for Visual Studio 2010 in HxS format. As Darren mentions "we didn’t use Sandcastle to actually generate the final mshc packages that shipped with VS 2010". Since the community do not have access to MTPS we had to retrofit Sandcastle to provide MSHC generation support. Hope this helps.

 

Anand..