Sandcastle Workshop: Conceptual Templates

Sandcastle Workshop is our IDE for Sandcastle, and will be based on the Sandcastle Assist builder libraries and tools. This project is based on the SharpDevelop IDE, which we have scaled down with some usability improvements.

For the past 2-3 months, this project took away all our spare times. By God's grace, we have made progress with this effort and we are planning an alpha release on the November 30th, 2009. You can read our recently announced road-map here.

We have just completed the file templates for the Sandcastle conceptual topics, and we want to present that in this blog.

Conceptual Templates

Here is how it looks in the our New File dialog (click for larger image):

As shown are are providing two sets of conceptual topic templates:

1. AML Topic Templates: The file extension is *.aml, first introduced by DocProject and now supported by SHFB. These topics files are wrapped in the topic tag.
   
2. MAML Topic Templates: The file extension is *.maml. These topics are not wrapped in the topic tag, and will be the recommended format for the Sandcastle Workshop, I will explain why below.

The New File dialog will allow you to provide author information, topic title etc., and the will generate both the main topic file and the companion file.

The companion files are supposed to contain information on the topic, and we will use it extensively to keep most information on the topic (its metadata), including those not directly required by the Sandcastle compiler, such as your topic TO-DO, and other memo information.

Why the *.maml topic files?

The topic tag is not defined by the Sandcastle conceptual authoring schema, and VS.NET IntelliSense, for instance, will give at least two warning for every such file opened in its Error List window.

Also, we think the topic identifier and the revision number are better kept as part of its metadata or topic information in the companion file.

Wrapping the topic in the topic tag should be considered an intermediate step, and handled by the building tools.

The "tradition" of creating topics wrapped in the topic tag started with the Sandcastle conceptual example. In order to be able to compile that example with a simple batch file, and not requiring any preprocessing by tools, the Sandcastle conceptual example came with all the intermediate files, including wrapping the topic in the topic tag. We want to restore the normal way of doing this stuff!

How we did it

We created the templates for all the 19 topic types supported by the Sandcastle, and then customized copies of these by adding Sandcastle Workshop specific file template items.

The original empty templates will be available in the development branch of the source control at the Codeplex for you to customize and enhance for your own IDE or applications.

On the user interface, New File Dialog, we have to rework parts of the SharpDevelop's New File Dialog, which had a nice innovative feature of including the property grid control support.

We like that feature, but unfortunately, it was not as complete as we thought when we started working with it. We improved upon the idea, including the support for read-only property you see for the topic creation date, and in this blog we presented our result.