Sandcastle Community

May 15, 2008 at 2:00 AM
Hello All,
I will like us to discuss how to advance the Sandcastle.
Many of the "problems" currently with the Sandcastle are hardly problems with the tools, they
are mainly the transforms and sometimes the styles.

Eric Woodruff has being doing a great job fixing or patching the transforms to get around bugs
and get work done.
I propose that we start a new CodePlex project, say, "Sandcastle Community" to handle this. Here,
we could discuss, fix and update the transforms and styles, may be come out with new ones.
Prototype and Hana for instance are currently not well supported in the conceptual help, even
though I personally do not use them.

It seems Microsoft is reorganizing its documentations teams and may focus attention more
on the new project, which will mean less attention to the Sandcastle.
The current license of the Sandcastle is flexible and allows this.
I now, use the Sandcastle on a daily basis and will wish to get many things done fast and quicker.
If Eric can accept the lead of this project, I promise full commitments, including handling the
testing and documentations.

Now, if the Anand comes with a way of maintaining the source codes here, we could easily
move to this site and delete the "Sandcastle Community" project.

Please share your views on this, it just my observations and proposals. I know many out there
have a better ones, so lets start it going. 

Best regards,
May 15, 2008 at 3:41 AM
Edited May 15, 2008 at 3:45 AM
I'm sitting on about 14 unreported transformation bugs that I found this past weekend while going through the conceptual content stuff plus I've got fixes for about 10 other bugs and feature requests in reported work items.  Since a release of Sandcastle is pending (coming real soon I hope), I haven't bothered creating a work item for the new stuff as I'm waiting to see what changed and what got fixed in the upcoming release.  Anything that hasn't been fixed, I'll submit then as a new work item and a corresponding patch to the new release.  With the fixes I've made, conceptual content using Hana and Prototype are pretty functional and are as usable as the VS2005 style.  The only things not done are missing collapsible sections in the Prototype style and a broken language filter in the Hana style.   Those appear to require a bit more work and may be beyond my XSL skills to fix.

I wouldn't mind seeing a new project for maintenance of the presenation styles as a great many of the problems are located there.  It would also make the patch more visible.  I was thinking about making the patch a separate release all on its own at the SHFB site but I think it's still too easy to miss.  It's only be downloaded about 2,700 times from the SHFB release page.  When you consider that Sandcastle itself has 27,500+ downloads, that's lot of people living with broken transformations.  Many don't realize it's there until one of us points out that it's available.  

On a related note, this might also be a good place to consolidate and deploy translated versions of the content files.  Language support is there, it's just lacking translated versions of the Sandcastle resources.  I've also made a start on a MAML guide that documents the various elements and their attributes.  The goal is to have something similar to Dynicity's XML Comments guide for MAML to make learning to use it easier.  Perhaps this would also be a good place to release it an consolidate our knowledge on the subject.

I'd be happy to work on the project.  I wouldn't mind seeing Dave Sexton added as a coordinator as well since, as developer of DocProject, he's also familiar with the transforms and has opened a number of work items related to them.  Perhaps we should just create the project and I'll submit my current set of files with the latest changes as the starting point rather than waiting for the next release of Sandcastle.  Below is a list of stuff I've fixed.



Adding a root namespace page causes BuildAssembler to crash.
Presentation Style Issues and various missing content items.
Script# Presentation Style Issues.
Missing CHARSET attribute in metadata.
Version info not showing on member pages in Prototype.
XAML code samples cannot be hidden (VS2005).
APIName Attributes Incorrect
ApplyVSDocModel.xsl loses library information
Better implementation of the <note type=""> tag (applied to MAML alert element too)
Support External Hyperlink Target with Appropriate Default
Conceptual: codeEntityReference is sensitive to space
Conceptual: autoOutline Changes
Conceptual: XLinks in relatedTopics section requires explicit text
Conceptual: Formatting is not applied to some in-line MAML elements
Conceptual: Glossary Improvements
Conceptual: Hana does not wrap code blocks in div
Conceptual: <copyright> processing is broken.
Conceptual: Hana and Prototype are missing some namespace declarations
In Hana and Prototype Styles.css "a" element styles need fixing
Conceptual: All three styles, normalize the space on the abstract
mediaLink and mediaLinkInline should be handled as separate templates
ddue:list should support the "nobullet" style.
ddue:table handling is incorrect in Hana and Prototype
Rendering of ddue:definitionTable isn't consistent in presentation styles.
"ddue:schemaHierarchy" and the related "indent" templates are missing (Prototype)
The sub-section toggles do not work in Hana and VS2005
The collapsible sections that are rendered in the Prototype style do not work
Conceptual: Pass-through HTML (implemented via ddue:markup)
Conceptual: Support NamedUrlIndex keywords in metadata.

-- End of list
May 15, 2008 at 5:24 AM
Thanks for the understanding. Will you create the project or I should go ahead and create it?

One thing I wish to avoid is issue of leadership, what is needed is getting real work done not who
is who, so anyone willing to commit to the project should be allowed to join as a coordinator,
developer or position that fits. We only need a leader who will call the shot, we could even put
rights to others to commit codes to vote, if the need be.
Dave is also doing a great work with the tools, supports, documentations, suggestions and others,
and he is very knowledgeable in this stuff, so if he is willing to coordinate, why not?

Please lets get this stuff up now.

Best regards,

May 15, 2008 at 5:34 AM
Hey guys,

I think this project is a good idea.  Count me in if you want the help :)

Just to be clear, the goal is to improve Sandcastle by providing a rolled-up solution to various presentation style issues (with fixes consisting mostly of Eric's work ;), in a manner that's highly visible to the Sandcastle community and also involves community feedback.  In the future we may create custom presentation styles as well.  (And it will also allow us to sharpen our XSL skills :)


We should be explicit though about what changes are made to customized presentation styles, via the Issue Tracker, so that the Sandcastle team has a place to review our consolidated feedback.  I'd like to see the issues reported so that eventually they can be fixed in Sandcastle.

- Dave
May 15, 2008 at 5:36 AM
- What do you think about naming the project Sandcastle Styles?
May 15, 2008 at 6:28 AM
Edited May 15, 2008 at 6:34 AM
Hello Dave,
Thanks for the offer to participate, Eric has already approved you for coordinator. 
Right, we start with the Eric's work and any contribution available, and get into higher gear.

Yes, not only the Sandcastle team, we will also have to monitor both project's Issue Trackers. Everything 
will be very transparent - after all we are working on help! and want to help/support the Sandcastle effort.

davedev wrote:
- What do you think about naming the project Sandcastle Styles?
I think, "Styles" kind of limit its scope, "Presentation" is a bit broader but still limited. The "Community"
may also be too broad, but seems to give more room to dump anything in. I have created XML schemas
for media arts, code snippets, and my recent conceptual contents file format. If approved, it could
be hosted there. May be Eric or someone has a better name.
I have created a project here, "Assist" (still not published), and was going to host the my schemas and
libraries there.

Again, thanks for the interest.

Best regards,
May 15, 2008 at 6:53 AM

I took the liberty of creating the project ( and added both of you as coordinators.  It's currently unpublished so it's only visible to us right now.  I've assigned it the Ms-PL license to match Sandcastle.  Feel free to change the name and project details if you like.  I've uploaded my current set of files to the releases page.  It contains a BugList.txt file that lists the bugs and feature requests that I know of or was going to look into.  Reported items include the URL to the work item and each notes whether or not its fixed by the patch.  My notes on the actual fixes range from detailed to sparse.  I'll put some effort into making the notes more descriptive.

Any bugs reported in the project should also be reported here so that the fixes do make it into Sandcastle.  We're just providing a means to get the fixes out and available without having to wait on the Sandcastle release cycle since we have the ability to do so.


May 15, 2008 at 7:21 AM
Edited May 21, 2008 at 10:39 AM
Thanks Eric,
I have added some tags to the forum, including "Release Notes", which could be used to publish
the BugList.txt.

Until published, all discussions on the project could be here.

Best regards,
May 21, 2008 at 6:30 AM
I really love this enthusiasm. I am working on code signing process so that I can release Sandcastle next week. Sorry about all the delay.
I am willing to open up both Hana and Prototype styles to the community. We will continue our fixes in VS2005 transforms.

May 21, 2008 at 8:38 AM
Thanks for the update Anand :)

I think some of us agree that the delay hasn't been so bad though because it has given us time to get Sandcastle Styles together, among other things.

Does opening up Hana and Prototype just mean that you won't be fixing bugs anymore?