Dave Sexton's Blog

Code Contracts for Visual Studio Pro

Dave Sexton — Thu, 12 Jan 2012 05:19:27 GMT

If you decided long ago that you weren’t going to bother trying Code Contracts because you didn’t have Visual Studio Premium edition or higher and thus couldn’t take advantage of static checking, then your wait is finally over.

Code Contracts 1.4.41228.0 was recently released, along with some great news: The Code Contracts static checker is now available for all editions of Visual Studio (excluding Express).

On a sad note, it seems as though Code Contracts will remain in DevLabs through the next Visual Studio cycle.

But to end on a brighter note, apparently the team is still trying to make it an official product.

From the forum announcements section:

We are trying to make the case for Code Contracts to be included in Visual Studio as an official product. Please send us your feedback as soon as possible, especially if you have any details about how exactly it has helped your development process.

So start using it and send them all of your success stories!

Here are some links to get you started:

Editor Extensions (Optional)
http://visualstudiogallery.msdn.microsoft.com/85f0aa38-a8a8-4811-8b86-e7f0b8d8c71b/

Portal
http://msdn.microsoft.com/en-us/devlabs/dd491992.aspx

Research Site
http://research.microsoft.com/en-us/projects/contracts/

Release Notes
http://research.microsoft.com/en-us/projects/contracts/releasenotes.aspx

Forum
http://social.msdn.microsoft.com/Forums/en-US/codecontracts/threads

Resources for Learning Rx

Dave Sexton — Sat, 12 Nov 2011 18:51:00 GMT

Start by bookmarking the Rx hub on MSDN:

http://msdn.microsoft.com/en-us/data/gg577609

Especially the beginners guide and the .NET Resources and Community pages, which together provide several links to official videos, blog posts and articles, all of which are worth reviewing.

http://msdn.microsoft.com/en-us/data/gg577611
http://msdn.microsoft.com/en-us/data/gg577612

Next, bookmark the Rx forum. This is the official place to search for answers and to ask new questions:

Rx Forum
http://social.msdn.microsoft.com/Forums/en-US/rx/threads

Depending upon your current level of knowledge with Rx, you may want to continue by going through the official hands-on labs. They are a bit out-dated although differences between the labs and the latest Rx class library should be minimal. When you do come across differences, a quick search on the Rx forum will show you what changes need to be made.

Hands-On Labs
http://go.microsoft.com/fwlink/?LinkId=208528

For further reading, I recommend starting off with the official conceptual documentation:

http://msdn.microsoft.com/en-us/library/hh242985(v=VS.103).aspx

followed by the recommended design guidelines. This document is a bit outdated, although where there may be differences between the examples and the latest Rx class library, the purpose and reasons for the guidelines still apply.

Recommended Design Guidelines
http://go.microsoft.com/fwlink/?LinkID=205219

After that there's plenty of community resources to choose from. A new book has been written about Rx recently:

http://social.msdn.microsoft.com/Forums/en-US/rx/thread/813e56db-e410-4f35-8f72-1be34b08ce8a

And here's a list of blogs and open source projects that may interest you:

http://social.msdn.microsoft.com/Forums/en-US/rx/thread/2cbd3b1c-d535-46ba-a9cf-3cd576a8e7c2

As for open source projects, I’m particularly fond of Rxx, and not just because I’m the co-founder and author along with James Miles. ;)

Rxx 1.2 Released

Dave Sexton — Wed, 09 Nov 2011 15:01:00 GMT

If you’re not familiar with the Rxx project yet, it's something I’ve been working on for several months now along with James Miles.

Rxx is a library of unofficial reactive LINQ extensions supplementary to Microsoft's Reactive Extensions for .NET (Rx). Rxx is developed entirely in C# and targets the .NET Framework 4.0, Silverlight 4.0 and Windows Phone 7 (WP7).

Why should you use Rx and Rxx?

Well, if you’re doing any kind of programming that involves asynchrony or concurrency, such as what is commonly found in UI layers, business layers, data access layers, middle tier services – basically everywhere, then you’ll definitely find Rx to be very useful. Rxx adds a whole bunch of useful features on top of Rx and the .NET Framework Class Library (FCL), making it quite easy to introduce common patterns of asynchrony into any .NET program through the use of IObservable<T> and LINQ.

Rxx provides the following features. See the Documentation for details.

Many IObservable<T> extension methods and IEnumerable<T> extension methods.
Many useful types such as CommandSubject, ListSubject, DictionarySubject, ViewModel, ObservableDynamicObject, Either<TLeft, TRight>, Maybe<T> and others.
Various interactive labs that illustrate the runtime behavior of the extensions in Rxx. Individual labs' source code included.

The latest release of Rxx is now available:

New features for Rxx 1.2 include:

Compatible with Microsoft's Ix Experimental library.
UI extensions for WPF and Silverlight, including AnonymousCommand, CommandSubject, a Subscription XAML markup extension for binding UI elements to observables, EventSubscription trigger and a reactive view model infrastructure. (Download the labs application for examples.)
N-ary Zip and CombineLatest combinators.
Several parser updates, including new operators, non-greedy (lazy) quantifiers and major performance and memory improvements, such as avoiding stack overflows due to recursion in quantifiers.
Cursor types and extensions (Rx and Ix).
ListSubject and DictionarySubject.
Consume extensions that generalize the producer/consumer pattern over observables.
ApplicationSettingsBase extensions.
ObservableSyndication for RSS 2.0 and Atom 1.0.
ObservableFile and additional ObservableDirectory extensions.
Stream, FileStream and TextReader extensions.

More details can be found in the latest release notes: http://rxx.codeplex.com/wikipage?title=Release%20Notes

We’d really appreciate your feedback. Please let us know about your experiences with Rxx by starting a new discussion or submitting an issue. Thanks!

Sandcastle with Code Contracts

Dave Sexton — Sun, 13 Sep 2009 19:19:39 GMT

Microsoft Dev Labs has released a new version of Code Contracts. (For more information about Code Contracts in the .NET Framework 4.0, see System.Diagnostics.Contracts and this article). If you haven't yet, I highly recommend installing the latest Code Contracts release. If you're using Visual Studio 2008 then you'll also get a shiny new tab in your project's Properties window.

Figure 1: Code Contracts tab in Visual Studio 2008 project Properties window

Along with the latest features is a new tool that adds documentation for Code Contracts to an assembly's XML documentation file. The latest release also includes a Sandcastle patch that allows the vs2005 style to include the code contract documentation within an expandable Contracts section, as shown in the following screenshot.

Figure 2: Example Sandcastle output with Contracts section

The following blog post describes how you can patch Sandcastle so that it uses Code Contracts in XML documentation files. The author chose to use DocProject to automate the build process, but I suspect that it will work with or without any automation tools for Sandcastle.

http://www.leading-edge-dev.de/?p=447

Note that I've tested this procedure with success in Visual Studio 2008 standard edition.

Just don't forget to create a new DocProject or DocSite project after applying the Sandcastle patch. You can use the Import Topics and Settings step in the New Project Wizard to copy over the important stuff from an existing project if you'd like.

On a side note, I think this also about ruins my ContractN project ;). I've abandoned it anyway, so I'll be doing the honorable thing and will close down the ContractN project on CodePlex at some point (to help keep CodePlex clean - just doin' my part). I'll continue to host the code on my blog in case anybody's interested in learning how to use Context-Bound Objects, in some form or another.

MAML Editor: Progress II

Dave Sexton — Tue, 08 Jul 2008 13:52:02 GMT

In a previous blog post I discussed my work on a WYSIWYG editor for authoring MAML topics, either inside or outside of DocProject. This post is simply another quick update on my progress.

Preview Release Timeline

A few weeks ago I started a new job and they put me on a project with a tight deadline so I haven't had much time to do anything else. Last weekend I was still too busy to do much with the editor (even on July 4th) so I missed my most recent target date: yesterday.

I'll probably have time to work on the editor each night this week though so I should be able to put a working preview out there soon. Last night I was able to almost complete key input behavior processing, which I had actually planned to work on after the preview. I was also able to complete a few controls; e.g., the alert control now has a drop down list in the header with icon-text pairs as list items (shown in the screenshot below). It was so easy to implement too compared to having to owner draw items in WinForms apps - WPF is really cool. The next control I'm going to write is for MAML linking, which should be fun :)

Progress

I still have to add the command buttons but I've been deferring that because it should be pretty easy to do with limited functionality for the initial release (e.g., the editor's not schema based yet so all buttons will always be enabled.) Although, I'll probably only add a small subset of commands initially, which will save time.

One thing that I may do for the preview though is to add the ability to insert custom command buttons through a dialog and have them associated with custom MAML markup. Once the markup is inserted, it can be parsed as if it was being loaded from a MAML file using the existing factory/parser infrastructure - that should fill in the gap nicely for MAML elements that I won't be providing support for in the initial release. (Note that this is entirely conceptual - I don't know if it'll actually be worth the effort for the preview release.)

The other major feature that the editor is currently lacking is the ability to parse the physical flow back into MAML for save operations (it currently saves as XAML, for testing purposes). I don't see this being a difficult process though since every element in the document is currently tagged with a parser context object, which provides direct access to the particular parser that can transform the element into MAML, in much the same way that it parses MAML into elements when a topic is loaded. (Load functionality works fine :)

Originally I was hoping to avoid having to parse the physical flow by simply saving the in-memory LINQ to XML document (this was working for a short while during development), however I discovered later that the only change event that gets raised is the FlowDocument's TextChanged event (IIRC), making it difficult to track the relationship between changes in the flow and the underlying XDocument structure. Although, I do see an opportunity to implement change tracking like this in the future due to my parser context and parser input behavior designs, but for the sake of time I'll probably defer it until a subsequent beta release.

Screen Capture

The following is an updated image of the same MAML topic being edited as in my last post. It might not look like much has changed, but functionally speaking, it's now actually becoming a useful app (barring the missing save functionality :).

This time all of the styles that you see are loaded dynamically from XAML style sheets (currently embedded resources, but eventually loose XAML as well) and, although it's not obvious from the image, the editor actually behaves much more like you'd expect from a schema-based editor. For example, pressing the Delete key at the end of the MAML Introduction will no longer cause the first section's header to move up into the introduction's paragraph. This behavior is controlled by each individual MAML element - they define their own key press behavior using a custom preview & bubble approach, just like real WPF controls, but they also inherit some default behavior that restricts the flow a bit.

I've also started using WPF annotations for debugging (not visible in the image below) and I also plan to use them to display a delete button near the currently selected block element. So to delete an entire section from the editor you would click anywhere inside the section and the delete button will appear, perhaps floating at the top-right corner of the element. That's the way I think it should work for all block elements, such as the MAML introduction, section, procedure, alert table and code block shown in the image below.

(Note: The document shown below was actually loaded from a real MAML topic file. The red squiggles are real-time spell checking errors provided by WPF and each element's styles were applied dynamically using XAML style sheets.)

DocProject 2008: Custom Visual Studio Project System

Dave Sexton — Thu, 19 Jun 2008 09:11:13 GMT

For the last couple of weeks I've been testing a new VS package for DocProject 2008. You can read more about my plans here.

More recently I've been working on a new project system that integrates into Visual Studio 2008 but the current implementation only provides a single template, .docproj, which has very limited functionality at the moment. I'm considering whether I shouldn't bother creating a custom project system if I can't do what I want since the current implementation (zipped templates copied to a folder during installation) provides seamless integration into VS already and won't require me to invest any more development time in this area.

However, I'd really like to have a custom project system that inherits from the project system that VS provides for the C# and VB.NET class library/web application templates since it will provide the following advantages to DocProject:

Inherit all of the functionality provided by .csproj and .vbproj, including full support for the class library and web application project sub types. (I'm considering using .csdoc and .vbdoc as the new file extensions.)
I have lots of tested automation code that works against the VSProject system already (provided by EnvDTE). It could be reused with only minimal changes, if any at all. This will mean that I'll be able to deploy the next release much sooner and with minimal impact to DocProject's existing codebase.
I could get rid of the DocProject Properties command and tool window and instead integrate the property grid into the typical Properties window by adding a new tab named, DocProject.
Use custom MSBuild properties to store project options instead of using the automation Globals collection, which stores all custom data as attributes on a UserProperties element. Using actual MSBuild properties provides the obvious advantage of being able to easily set project settings for command-line builds and also has the advantage of being able to make certain properties dependent on the active solution configuration. (The latter point has been a feature that I've been considering for a while but I've felt that it's not worth the effort to implement if I have to roll my own solution via automation code, so it's been deferred until DocProject 2008.)
Create special project folders that have a different appearance and provide custom behavior when double-clicked; like the Properties folder for example. In DocProjects and DocSites, the Help folder would probably be a good candidate for a different appearance. The Comments, Settings and Topics folders could probably have a different appearance and behavior.

I've posted a few questions to the VSX forum in the hopes that someone could give me some pointers as to how I can accomplish my goal of implementing a partially custom project system in Visual Studio 2008; i.e., a system that inherits from the VSProject system that can be automated through the EnvDTE library. If anyone can answer my questions I'd really appreciate it so that I can make a decision about whether a custom project system is worth the effort for the next Beta release. Thanks :)

DocProject 1.11.0 RC - Second Update

Dave Sexton — Mon, 16 Jun 2008 05:25:05 GMT

Another update was just released for DocProject 1.11.0 RC. This update replaces the existing installer on the Releases page that was deployed for the first update.

For anyone that had previously downloaded DocProject 1.11.0 RC or the first update, you can download it again if you're experiencing the problem that was fixed by this update.

Note: Make sure to manually uninstall any existing version of DocProject before installing the new version since the version number was not incremented. Use the Add or Remove Programs dialog in Control Panel.

Update

This time I've fixed a single bug in the XML documentation editor whereby modifying comments in Source mode and then saving the changes would write <see /> elements as <doc:see /> elements instead, which of course Sandcastle ignores because the tags are in an unknown XML namespace. A similar thing happens to other in-line XML documentation elements too.

I've tried testing a few different scenarios after fixing this issue and I can't seem to break the XML documentation editor anymore, but please keep the feedback coming if anyone can find some more stuff for me to fix.

DocProject 1.11.0 RC Updated

Dave Sexton — Sat, 14 Jun 2008 01:57:27 GMT

An update was just released for DocProject 1.11.0 RC. It replaces the existing installer on the Releases page.

For anyone that had previously downloaded DocProject 1.11.0 RC you can download it again if you've experienced any of the following bugs.

Note: Make sure to manually uninstall an existing version of DocProject before installing the new version since the version number was not incremented. Use the Add or Remove Programs dialog in Control Panel.

Issue 1

Missing root Namespaces node in Topic Explorer.

Cause

Documenting only one namespace.

Fix

The TopicManager class was only creating the root node if the topic had more than one namespace, but since this behavior is invalid it was removed.

Issue 2

Installing for Everyone and both VS 2005 and 2008 did not work properly; the Add-In would not appear in VS.

Cause

The custom action that copies the .AddIn files to the target directories is responsible for updating their content so that they're compatible with the target version of VS. Since the target directory for both VS 2005 and 2008 is the same when installing for Everyone, one copy of the .AddIn file would replace the other, and even that didn't get updated properly.

Fix

Since there's already two separate .AddIn files for each version of VS the version number was hard-coded so that it doesn't have to be updated during the installation. To fix the problem of one file replacing another, the names of the target .AddIn files now include the 4-digit year of the version of VS to which they apply.

Issue 3

Topic Editor does not handle XML documentation tags properly. The end tag is always moved to the end of the section, causing the element to wrap all of the content from where it's defined to the end of the section.

Cause

The HtmlToXmlConverter class provides a mechanism by which tag names can be replaced but it only applies to the start tag of an element and not its end tag. This issue was introduced when the HtmlEditor control library was updated for the DocToMaml 1.0 Beta program.

The reason why tag replacement is required in the Topic Editor is that a doc prefix is automatically associated with tag names that are registered in DocProject's configuration file since they are not valid HTML elements; the HtmlEditor control will only support an HTML element or an element that is associated with an XML namespace. This allows styles to be applied, such as those in the TopicDesigner.css file and causes the control to treat the elements more like XML instead of HTML; e.g., unknown tag names are not automatically changed to upper case. When converting HTML back into XML the doc prefix must be removed, hence the requirement for the tag replacement mechanism of the HtmlToXmlConverter class.

Fix

Tag name replacement now works on both the start and end tags so that the parser can properly close the element at the position where the end tag is found in the source XML.

DocProject 1.11.0 RC Is Now Available

Dave Sexton — Mon, 09 Jun 2008 04:02:44 GMT

DocProject 1.11.0 Release Candidate is now available on CodePlex. It supports the Sandcastle May 2008 Release and contains many bug fixes and new features, most of which are listed below.

Full support for both Visual Studio 2005 and Visual Studio 2008 using a single installer.

Conceptual topics created in Topic Exporer are now saved with friendly file names and an .aml extension. A dependent companion file (.cmp) for storing metadata is created as well.

The topic import feature has been improved and now supports the inclusion of raw HTML topics in Topic Exporer. Legacy MAML topics (those with an .xml extension) are automatically imported into the new format and, if possible, a friendly name is chosen automatically.

An optional Import Topics and Settings wizard step has been added to the New Project Wizard. It allows for a single DocProject or DocSite file to be specified from which topics and settings will be imported into the new project automatically.

Wildcard characters, including directory recursion (**\ - but only on the most nested directory) is now supported in various dialogs, including External sources.

The External sources dialog is now available in the last step of the New Project Wizard.

Automatic checkout of source-controlled project items occurs whenever a project option or dialog must write to a file in the project.

ResolveExternalLinksComponent now works for conceptual builds and is automatically added to the conceptual configuration files when new DocProjects and DocSites are created. (The standalone release will also be updated.)

Open in Visual Studio toolbar button added to the DocProject External UI.

New Topic Explorer context menu commands: Copy as reference link, Copy as conceptual link and Copy as topic identifier.

New Topic Properties window that provides a user interface (UI) for editing conceptual topic metadata, such as Help 2.x DocSet attributes, index keywords and the topic's display title. This window is reachable by right-mouse clicking a conceptual topic in Topic Explorer and selecting Properties in the context menu.

New Help\Settings files are automatically included when DocProjects and DocSites are created:

conceptual_snippets.xml: Specifies code snippets written in multiple programming languages that may be included in conceptual topics.
tokens.xml: Specifies shared content items for both conceptual topics and XML documentation comments; items are referenced using <token>name</token> elements.
links.xml: Specifies external hyperlinks that can be used in both conceptual topics and XML documentation comments. (See ResolveExternalLinksComponent for more information.)
metadata.xml: Specifies global Help 2.x metadata that is inserted into all conceptual topics and auto-generated reference topics. Metadata can include attributes such as DocSet, Product, TargetOS and custom values.
bibliography.xml: Specifies global reference information for topic bibliographies. Conceptual topics and XML documentation comments that have citations as <cite>name</cite> elements will have bibliographies generated automatically.
- Note: The Sandcastle Styles patch is required to support this feature.

New management dialogs for Help 1.x and Help 2.x configuration. (Settings are persisted to certain files in Help\Settings\Projects\, Help\Topics\Html\MSHelp2\ and the root Help\ folder.)

Configurable Help 1.x project options such as the list of source files, Binary TOC, Default Window and Display progress during builds.
Configurable Help 2.x project options.
- Named URL values such as DefaultPage and HomePage, which may be chosen from a list of topics, and AboutPageInfo, EmptyIndexTerm and NavFailPage, which can be created with DocProject's HTML editor.
- The Help > About image that appears in Document Explorer. (An HTML page that references the image is automatically generated for the AboutPageIcon named URL.)
- Global metadata attributes, which are stored in Help\Settings\metadata.xml (more information above).

Improved MAML topic templates.

The behavior for detecting out-of-date sources and files has changed to allow for more control over change tacking.

Modifying individual conceptual topics may change the type of the next build. Changes are detected for MAML topics in Help\Topics\ and raw HTML topics in Help\Topics\Html\.
Starting Visual Studio and loading a DocProject or a DocSite does not force a full build anymore unless the output is actually outdated.
Another effect is that deleting the .chm or .HxS files no longer causes a partial build; instead, it always causes a full build. To force a partial build you must modify a partial build item.

Generate root API topic is now enabled by default in new DocProjects and DocSites.

Added inheritdoc tag to the DocProject configuration file so that it appears in the Topic Editor sections list when writing external XML documentation.

Visual Studio Gallery Updated

Dave Sexton — Fri, 06 Jun 2008 16:13:59 GMT

It appears that Microsoft has improved the Visual Studio Gallery by adding the ability for users to rate and review products. The interface was jazzed up a bit as well. Nice work MS - the original gallery was more like a project dump but the new release is community-oriented, which I think people will appreciate.

DocProject has been in the top 10 most visited projects since the VS Gallery went live (it was in the top 3 for quite a while too), which just goes to show you how important documentation is to developers when a tool such as DocProject is more interesting than tools that aid in development. This certainly motivates me to continue working on it for VS 2008 :)

I'd like your feedback so please drop by and write a review if you can find the time. Thanks!

Sandcastle Styles Project on CodePlex

Dave Sexton — Wed, 04 Jun 2008 20:47:30 GMT

The Sandcastle Styles project is now live on CodePlex. From the project's home page:

The goal of this project is to improve Sandcastle by providing a rolled-up solution to various presentation style issues in a manner that is highly visible to the Sandcastle community and also involves community feedback.

This project was started by Paul Selormey, Eric Woodruff and myself. Currently we're the only active contributors but we'll be happy to take any feedback you have to offer. Let us know by starting a discussion.

Sandcastle features and issues should be submitted directly to the Sandcastle Issue Tracker so that the Sandcastle team will be notified.

What's Inside?

Eric has included his presentation style patches from the SHFB project - we're now deploying them as a part of Sandcastle Styles. There are additional bug fixes and modifications that were made for the May 2008 release of Sandcastle as well. He has also included a new MAML guide as a separate download and custom code providers for VB and C# that can be used to extract assemblies and XML documentation files from Visual Studio Web Site projects.

We've also added some new features to each presentation style, such as support for the MAML glossary document type, image placement support in MAML, enhanced <autoOutline> in MAML, and also an auto-generated bibliography for both conceptual and reference topics. Tools such as DocProject and SHFB support these features with the patches applied.

I've started an Examples project that shows the typical usage of XML documentation comments (all tags supported by Sandcastle) and common MAML markup, such as linking, tokens, code snippets and media. I've also included DocProject's MAML document templates for those that are using a different tool. Lastly, there's an API that can be used to test Sandcastle filtering capabilities in our automation tools, which also provides some nice examples of how to add XML documentation to code and how to use the <include/> tag to share comments and keep code neat.

We expect to improve our library of examples and include additional languages and project types in the future, and I hope to make it available as a separate download as well. Also, if people will donate language packs for Sandcastle we'll tidy them up and host them.

Hopefully the community will find this project to be a valuable Sandcastle resource. Any feedback will be appreciated :)

MAML Editor: Progress

Dave Sexton — Tue, 03 Jun 2008 05:35:00 GMT

This blog post is just an update on my progress creating a WYSIWYG (what you see is what you get) MAML editor. I've received a lot of feedback (relative) for the MAML editor and I know that people are waiting for one, so I'd like to share with you some information about the one that I'm working on and when it will be available.

For those of you who are unaware of what MAML is, you can read about it here.

I've created a very basic MAML editor using .NET 3.5, C# 3.0, LINQ to XML and WPF, but it's not currently my priority since I'm planning to release DocProject 1.11.0 RC later this week. A preview of the editor will be released though in the next couple of weeks as a standalone WPF application, a VS 2008 package (with MAML item templates) and also a standalone class library so that other tool developers can use the editor in their own applications - although note the dependency on the .NET 3.5 runtime and the DocProject license, which is currently the GNU-GPL.

The editor isn't schema based yet - I've hard-coded support for the Conceptual document type only, although since that type shares many common elements with other types, like How To and UI Reference, they're basically supported as well. The only difference now is that there's no schema validation and the UI cannot create several elements that are optional in the schema for the other document types. Though the current implementation has been designed to be flexible enough so that adding these things should be easy to do later on.

Since the editor is based on a WPF RichTextBox control, we get a free spell checker with squiggly underlines and an undo/redo buffer. It's also really simple to implement custom control logic for various elements (the current implementation uses a factory pattern to generate parsers for the individual elements, by name), such as a link editor, tables, images, and other stuff. So far I've added collapsible sections that actually function when you click the button, some custom logic that controls input behavior for various key presses, and also whitespace normalization for text (Run content in WPF).

Loading and saving also works, however synchronization between the data model in memory and the logical tree of the WPF content model still needs to be implemented - a major part of the editor - but with the event model and my current architecture I don't think it'll be too difficult; e.g., the data model currently uses XElement instances (from LINQ to XML) that contain annotations for their corresponding WPF content elements (Section, TableCell, Paragraph, Run, etc.) when the data is first parsed. The idea is to update the document directly when changes in the UI are detected. Saving the changes are then as simple as saving the XDocument.

Metadata is also editable, so I've decided to generate two separate files when saving a single topic. The first file is the topic file itself, which contains the root topic node, its id and revisionNumber attributes, as well as the actual MAML content. The second file is an XML companion file (to use the Sandcastle lingo) that contains metadata such as the topic's title, TOC title, MS Help attributes and index keywords. I may have another XML-based file created in the future to save editor settings for individual topics, such as the visibility status of individual sections; i.e., a designer file.

MAML topics are saved with an .aml extension (Assistance Markup Language) and companion files use a .cmp extension with the same base file name as the .aml topic. In the VS 2008 package, the .cmp file will be created with a dependency on the .aml so that it appears as a child in Solution Explorer. The next version of DocProject will provide support for these extensions so that when I release a preview of the editor your existing DocProjects and DocSites will already be compatible.

There's still a lot more to do before the editor is actually usable for generating quality MAML topics, but it's on its way. After a bit more functionality is implemented I'll blog about it in more depth and post some screenshots. For now, check out a screenshot below of the editor as I edit a simple How To topic that was previously written using Visual Studio's XML editor.

(Note that this is just a temporary WPF app that hosts the control while I develop it. The final app will have command buttons for semantic markup, such as database, ui, application, system, localUri, etc. and block-level elements such as section, procedure, list and table. I didn't implement them yet because commands seem pretty simple in WPF and I wanted to concentrate on the basic editor support first, as a WPF proof of concept (I'm a first-time WPF developer :)

The image above shows a MAML topic with introduction text, a collapsible section, a procedure and a code example. I also splashed some style in there, like the large font for the section title, just for the screenshot (the final editor will most likely get style information at runtime from WPF content resource themes so that its appearance will be completely customizable, without having to rebuild the source code).

Clicking the toggle button for the section will actually toggle the visibility of the section's content in the editor (note that the image is ugly only because it's on a button and I didn't remove the border yet). I plan to add other controls as well for functions such as adding links, tokens and media. The controls will actually be inside the document as part of the flow like the section toggle button - this is one of the really powerful features of WPF 3.5 flow documents.

There's even a context menu with Cut, Copy and Paste commands that I didn't have to write since it's provided by WPF. Editing the text and everything else behaves exactly like you would expect from a WYSIWYG editor, which also means that I'm going to have to add custom logic to attach behavior to specific elements so that everything is a bit less fragile. For example, one thing that I've done already is to add a behavior so that when the Enter key is pressed the cursor moves to a new line instead of an entirely new paragraph. Pressing Enter a second time, while on the new blank line, will delete the blank line and start a new paragraph (it's more complicated than that, but you get the idea). Having a new line within the same paragraph won't change the MAML output, it just provides some control over the appearance while editing. Of course, if this is confusing or annoying I can always remove it later.

I'd like to get feedback on my ideas so that I can quickly provide an editor that people are satisfied with. If you have any suggestions about how the editor can be improved please let know. Thanks!

MAML Migration: The Next Step in the Evolution of Help Authoring

Dave Sexton — Sat, 24 May 2008 14:53:10 GMT

Are you part of that herd of developers that is used to documenting applications by writing help topics in raw HTML? The power of it is nice, being able to add a pinch of bold here, a splash of italics there, some CSS for different layouts, a floating image, several nested tables, an abundance of hyperlinks, embedded Flash and media players, and even some JavaScript to boot. What more could we want? Or maybe a better question is, what could possibly make us want to give any of that up?

XML Documentation Comments

Well, XML documentation comments that may be added to code modules (I'm assuming everyone's familiar with this stuff by now) was one thing that prompted .NET developers to start documenting their code without using HTML. It's nice to be able to apply a bit of XML structure to our documentation, isn't it?

Commonly used semantics for describing an API may be expressed in a universal way with XML tags such as summary, remarks and example, and the compiler builds an XML documentation file that contains the code comments found in each module when we build our project. If you take a look at the contents of this file you may see a repeating pattern - schema - that seems like it could be used by some other tools to do, well, other things with it...

Compare XML documentation to your legacy HTML help topics and what do you notice? The XML comments that you add to APIs do not typically contain much layout or formatting, whereas your HTML topics are chock-full of 's, 's, and 's, and a whole mess of other HTML to describe the document's layout and formatting. Ok, ok, if you've done it correctly then you've made judicious use of CSS - applying class names to all of those <h*>'s, <div>'s, 's, 's, <a>'s, <td>'s, <tr>'s, <ol>'s, <ul>'s, <dl>'s, and certainly many other HTML tags that only add to the confusion when authoring topics (as opposed to designing them).

Now you might be thinking, "Dave, it's not entirely true that XML documentation is without formatting. What about the para, code and c elements?". And to that my reply would be, "Ok, so then what exactly do they look like?". If you look in the XML documentation files that are produced by your compilers, you'll see the markup exactly as it appears in your code modules. In other words, no HTML and no CSS - nothing more than semantic usage: paragraph, code block and in-line code. (If you were thinking something more like, "leading white-space, use pre formatting, code coloring and a fixed font", then you're getting ahead of yourself, so slow down!)

My point is that the semantics for the aforementioned XML documentation tags are clear (i.e., what the tags represent), but their appearance is not yet defined (i.e., their style and format). Take a look at the other Recommended Tags for Documentation Comments and you won't find anything out of the ordinary. Each tag has an obvious reason for its existence - to mark up regions of text that serve a particular purpose in the documentation. But how do they look? Nobody knows! ;)

Sandcastle

Now's probably a good time to introduce Sandcastle. For those of you that aren't familiar with it yet, Sandcastle is Microsoft's tool set for producing HTML help topics dynamically by inspecting managed assemblies and incorporating the markup from XML documentation. From the assemblies that you provide to Sandcastle, it automatically infers a table of contents (TOC), various pseudo-topics such as Properties and Methods, and also generates many individual topics to cover the entire API. The documentation you've written within XML documentation tags, such as summary, remarks and example, is automatically added to the generated topics in the appropriate places.

The results of running Sandcastle on your assemblies and XML documentation is a set of files that are web-ready HTML help topics for your project. This is typically referred to as reference documentation, since it provides a reference for developers that use your API. These topic files can be used as input to a tool such as HTML Help Workshop (Help 1.x) to produce a stand-alone compiled help file (.chm) that may be distributed with your application as an external help module. The .NET Framework even gets in on the action by providing helpful APIs for integrating context-sensitive help and Help 1.x navigation into your managed applications. (See the Help class for more information.)

Presentation Styles

Sandcastle provides three presentation styles that it can produce for your documentation out-of-the-box. Each one consists of a set of XSL transformation files that convert XML documentation into XML-based HTML (not XHTML, however). They also contain resources such as icons and, of course, CSS style sheets.

For an example of a Sandcastle presentation style, look no further than the documentation for Visual Studio and the .NET Framework on MSDN. The appearance that MSDN uses is similar to the VS2005 presentation style in Sandcastle. I believe that Microsoft actually uses a customized version to build their internal documentation, even for Visual Studio 2008. The other, experimental styles, that ship with Sandcastle are Prototype and Hana.

For more information about Sandcastle, see my Sandcastle Help article on CodePlex.

From XML Documentation Comments to Reference Documentation

So the process is actually quite simple. As developers we can easily document our source code using XML documentation, which allows us to concentrate more on writing the content instead of having to worry about formatting it with HTML. When we build our project, the compiler will produce an XML documentation file that can be passed to Sandcastle, which then inspects our assemblies and automatically generates reference documentation that includes the comments that we added to our source code, but in a pretty HTML/CSS-based style that looks very similar to MSDN. Nice!

User Documentation

Sandcastle can automatically generate reference documentation that is useful to other developers, but what about user documentation? I mean things like How To, Sample, Walk-through, Overview, etc. - stuff that an end-user would want to have. Well don't expect Sandcastle to know what you're thinking - we still, unfortunately, have to get concepts out of our heads and into help topics manually. (At least for the time being, until someone invents HAL ;)

Conceptual documentation (how Sandcastle refers to user documentation) is often much harder to write than XML documentation comments since it requires a more in-depth understanding of the application being documented. It's easy to look at the source code, notice that an exception is being thrown and then add an exception element to the XML documentation comments for that API. Or to notice that a particular algorithm is being used and to add a comment in the remarks element that mentions it. But to understand and be able to express the purpose of different user interface (UI) elements, how to perform various UI-related tasks, and how the individual APIs and components fit into the designs of other high-level processes in an enterprise-level application, is certainly more difficult and typically requires an understanding of many different aspects of the application. So the bigger the application the harder it is to write conceptual documentation, and not just because it's more time consuming but also because it's more complex.

So if writing conceptual documentation can be more time consuming and harder to accomplish than writing XML documentation comments, why do people still insist on writing conceptual documentation in HTML? Maybe the advantages of XML documentation comments can be applied to conceptual documentation as well.

The Perils of Writing HTML Help

I started this post by pointing out one very common way of writing help: raw HTML. We've all done it, and I know that each time I do I end up reinventing the wheel all over again. A new HTML layout, CSS styles, some new and strange way of cross-referencing, JavaScript for collapsible sections, etc., must all be redeveloped. (Yea, some companies are too cheap to buy a tool that does this automatically - and so am I. :)

Creating a new help topic starts with copying an existing HTML file that is used as a template, of which there's usually only one kind containing a header, with style sheet links and scripts, a body that's empty, and a footer. Writing a help topic requires having to look through the other topics quite often to find out which HTML tags and CSS class names I should be using for various styles. This is especially annoying when I have a good idea that I simply want to put down quickly and be done with it. Uh oh, that hyperlink to an HTML topic that I've been copying and pasting throughout my documentation is actually misspelled - time to do a search and replace. Hmm, I'm not sure that I like the format that I've been using for laying out tables - oh well, it's not worth the effort to fix it now.

Is There a Better Way?

Technical writers, I can only assume, take help authoring more seriously than that. They get paid to worry about things such as structure, readability and maintenance, so it shouldn't surprise us to know that there's a much better way to write help than simply using raw HTML. As developers, we could probably learn a thing or two from them when writing our own documentation, whether it's for an API or conceptual topics.

Lucky for us, Microsoft has a huge library of documentation and employs technical writers to write their "official" help, which is then published to the web on MSDN. (Sorry about that horrible reference for technical writers, but I couldn't find anything better. I know that I've seen someone from Microsoft, probably Anand, state that they don't use developer code comments internally and instead have professional authors write it.) This means that over the years they've had to come up with a solution that makes authoring help manageable, which is a huge task for such a large documentation set. They also needed a way to manage file names and links for cross-referencing help topics (think, See Also section). Since the look and feel of MSDN changes from time to time, the ability to write documentation that is absolutely independent of any one style or format was imperative as well.

So we have an invaluable example to which we can aspire. A whole plethora of documentation written with clarity and precision using standardized techniques. If you take a look at the documentation on MSDN, you should see a crisp and clean style that, when compared to your raw HTML help topics, probably looks far more professional. This is nothing new to us though - we've been referencing it for quite a long time now as .NET developers. Many people, predating .NET, have even watched MSDN documentation improve dramatically over the years, and most developers that need to write their own documentation seem to want to reproduce the same look and feel. Many tools have even helped us to generate reasonable facsimiles in the past (such as NDoc).

But have we finally come to the point where we can write our own help topics without having to remember abstract HTML tags and CSS class names? Can it be transformed automatically into documentation that looks the same as MSDN, or any other style for that matter? Is there a way to simply specify a unique identifier for another topic and have hyperlinks generated automatically? What about linking to reference topics? Is there a way to ensure that topics of a similar nature will all share the same exact structure?

The answer to all of these questions, of course, is yes. (But wouldn't it be funny if it was no? I'd probably take a nap.)

Microsoft Assistance Markup Language (MAML)

Microsoft uses Sandcastle internally to generate help topics for the .NET Framework, so it's no wonder that Sandcastle also provides a way to apply structured authoring techniques to conceptual documentation, in much the same way that XML documentation comments are used by developers to write reference documentation. In Sandcastle, conceptual topics are written in MAML.

MAML is an XML schema that defines various high-level document types, such as How To, Walkthrough, Sample, Glossary, Whitepaper, Troubleshooting and many others. These document types provide the structure of a help topic, which doesn't change. What can change though, is how Sandcastle presents this structure when it generates HTML topics. This means that, for example, the markup in all of your How To topics will look similar, regardless of the presentation style that you choose. As a matter of fact, the markup in your How To topics will be similar to mine, even if we choose to produce HTML help output in very different styles.

The schema also defines various XML elements that mark up text using a semantic approach. For example, the ui tag is applied to text that corresponds to a user interface element, such as the text on a button. Another example is alert, which also requires an attribute named, class that indicates the type of alert, such as note, caution, tip, warning, and others. Another is country, which you may have already guessed, describes a country! You would surround text with an application element when it represents the name of an application. I think you get the idea... By my count there's well over 40 elements that you can choose from. And with Visual Studio's XML editor you can actually have IntelliSense tell you what they all are and where it's appropriate, within the topic's structure, to use them.

The beauty of all this is that the Sandcastle presentation style that you choose controls the HTML layout of the MAML document type used by your topic. It also defines how all of the MAML elements will appear in the HTML. For example, alert is transformed into an HTML table layout, while ui and application are simply bolded. Special formatting is not actually applied to text that is specified as being the name of a country, but you could update the transformation to change the HTML markup or possibly just add a CSS rule to apply the formatting that you want, without having to update the actual topic itself.

A MAML Example

Here's a small portion of the Glossary help topic that I've written for my Auto-Input Protection (AIP) project.

<?xml version="1.0" encoding="utf-8"?>
<topic id="14790228-f45b-42d5-9b3e-f6b4ab932b9e" revisionNumber="0">
  <developerGlossaryDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" 
                             xmlns:xlink="http://www.w3.org/1999/xlink">
    <glossary>
      <title>Glossary</title>
      <glossaryEntry>
        <terms>
          <term>AIP</term>
        </terms>
        <definition>
          <para>
            An acronym that stands for Auto-Input Protection.
          </para>
        </definition>
      </glossaryEntry>
      <glossaryEntry>
        <terms>
          <term>Answer</term>
        </terms>
        <definition>
          <para>
            A user's or bot's response to a challenge.  In AIP, the correct answer is a 
            string of text that matches the text on the CAPTCHA image.  An incorrect 
            answer does not match.
          </para>
        </definition>
      </glossaryEntry>
      <glossaryEntry>
        <terms>
          <term>CAPTCHA</term>
        </terms>
        <definition>
          <para>
            An acronym that stands for Completely Automated Public Turing test to tell 
            Computers and Humans Apart, trademarked by Carnegie Mellon University according 
            to the following article: <externalLink>
              <linkText>CAPTCHA. (2008, March 26).</linkText>
              <linkUri>http://en.wikipedia.org/w/index.php?title=CAPTCHA&amp;oldid=201120981</linkUri>
            </externalLink> In Wikipedia, The Free Encyclopedia. Retrieved 09:01, March 27, 2008.
          </para>
        </definition>
      </glossaryEntry>
      <glossaryEntry>
        <terms>
          <term>Challenge</term>
          <term>Test</term>
        </terms>
        <definition>
          <para>
            A CAPTCHA image, being displayed on a web page, to which a user must respond 
            with an answer by entering the text that they see on the image.  The result 
            is pass or fail.
          </para>
        </definition>
      </glossaryEntry>
    </glossary>
  </developerGlossaryDocument>
</topic>

The following image shows the results of the glossary transformation into HTML, built by DocProject (a tool that I've written to automate Sandcastle inside Visual Studio). The VS2005 presentation style was used for this example.

And now here's the same exact topic file after being transformed into HTML using the Hana presentation style.

There are a few things to point out about all of this.

First of all, notice that the topic that I've written only uses some very basic XML, yet the output obviously contains additional layout and style, which differs depending upon the presentation style that I've chosen. In the Hana version I've even left in the default header that warns about pre-release documentation.

You may have also noticed the letter bar and the individual letter sub headers. Where'd they come from? These features are not actually part of Sandcastle, but Eric Woodruff and I have added them to the presentation styles by modifying the XSL transformations that convert the MAML Glossary document type into HTML. The additional behavior automatically detects the glossary terms in the topic and creates the letter bar and headers dynamically. All of the terms are sorted alphabetically as well (although it's not obvious in my example because they're already in alphabetical order in my topic file).

Pretty cool, right? You'll be able to get these Glossary updates from the new Sandcastle Styles project on CodePlex, which should go public within a few days after the next Sandcastle release. This project was started by Paul Selormey, Eric Woodruff and myself. In the last week we've been diligently working on preparations for our first release, so please check it out when we go live and let us know what you think :)

Linking in MAML

The last thing that I want to point out about the previous example is that it contains a hyperlink to an external web site. As you can see from my topic, MAML supports an externalLink element that accepts text in a linkText element and a URI in a linkUri element. It also accepts alternate text in a linkAlternateText element, but that's optional.

Instead of linking to external URIs, you can also link to any of the other topics being documented. To do that you would use a very simplified version of the XLink specification on a link element, as in the following example:

<link xlink:href="37852294-410f-4bb2-9008-c5fa9dfb4347">Part II</link>

Right, topics are identified by GUIDs. Currently, Sandcastle also requires that all conceptual topic files are named with a GUID and an .xml extension. A bit annoying at first, but if you use DocProject it provides a Topic Explorer tool window that makes it easy to find the topic that you're looking for without having to open all of them :)

Notice that in my example the value in the href does not have an .xml file extension specified. That's because link doesn't reference files, it references topics. This is important to realize because it's not the same as the way linking works in HTML - this is actually dynamic. If Sandcastle cannot find a topic that is associated with the specified GUID, then it doesn't generate a hyperlink at all.

This is a bit different from what we're used to in HTML, which allows us to link to anything under the sun using only one tag: a. So why such weirdness in MAML? I think the answer to that question is actually quite simple, although for some reason it's easy to miss when first starting out with MAML. The MAML schema defines elements that apply structure and semantics to text, instead of format and style, like HTML. For this reason, you wouldn't see a tag named simply, a in MAML because it's not descriptive at all. Link, on the other hand, is very descriptive. And since an HTML anchor is meant to provide the source point of a diametric link, its use is actually more limited than XLink. The XLink specification actually provides a way to establish relationships between one or more resources (at least that's my interpretation of it), which would offer much more flexibility. So MAML provides a mechanism to link to other topics, not just external URIs, and the XLink implementation provides an explicit way to describe links as being special - they must be processed by Sandcastle. Currently, Sandcastle doesn't actually seem to use any of XLink's features though aside from what has been deemed as "simple" usage, but maybe that'll change in the future.

But that's not all. If you want to create a link to an API in your reference documentation, you would use the codeEntityReference element instead. Yikes! So now we've got yet another way to link. But again, keep in mind that MAML is much more expressive than HTML, and that's why we've got different tags for linking to different things. The benefit being that our intentions are clear when we write our topics so that different styles of linking can be handled differently.

The following XML snippet illustrates all three approaches to linking in MAML topics. Each example is a child of the relatedTopics element, which, in the Sandcastle world, will eventually become your topic's See Also section.

<relatedTopics>
  <codeEntityReference>T:MyNamespace.MyClass</codeEntityReference>
  <codeEntityReference>P:MyNamespace.MyClass.MyProp</codeEntityReference>
  <codeEntityReference>M:System.IO.File.OpenText(System.String)</codeEntityReference>
  <externalLink>
    <linkText>DocProject</linkText>
    <linkUri>http://www.codeplex.com/DocProject</linkUri>
  </externalLink>
  <link xref="home">My Home Page</link>
  <link xref="Contact Us"/>
  <link vref="/related.aspx">Related web page</link>
  <link xlink:href="14790228-f45b-42d5-9b3e-f6b4ab932b9e">Part II</link>
</relatedTopics>

Notice that there are also two more link types in the example above that I didn't mention previously: link elements with xref and vref attributes. This type of linking is used instead of externalLink so that only an ID must be specified instead of an entire URL. The ID is part of an ID-to-URL mapping that is configured elsewhere. This feature is not actually part of Sandcastle though; it's provided by a custom build component that I've written which, for the next release of DocProject, has been modified to support conceptual builds as well. The component is called ResolveExternalLinksComponent and it's available as a separate download or as part of DocProject. Without this build component xref and vref do nothing.

Conclusion

HTML is out. MAML is in.

Well, it's not actually as substantial of a change as I'm implying - HTML is still being used extensively as the final output for compiling help; however, we no longer have to author help topics in HTML, which is a huge benefit.

So all this stuff might seem really wonderful in print, but I feel that I must warn you: It actually took me a few weeks before I finally started to get rid of that itch to lace my topics with bold and italic phrases where it didn't actually add any value. When you first start writing MAML it can feel very restrictive, and it is compared to HTML in terms of how quickly you can apply new styles, since to do that you have to leave the actual topic and modify files in the Sandcastle presentation; but it's actually much more expressive in terms of describing information and that's what we should be concentrating on when we write help topics - the information.

What I've learned from writing topics in MAML is that using elements such as ui, userInput, math, date, and many others, as well as externalLink, codeEntityReference and link for linking, ultimately accomplish the same thing as HTML but in a much better way - no more CSS class names to remember or abstract HTML tags like b and i (or strong and em too). Instead, I can specify exactly what a phrase represents and continue writing. The format and style is already defined for me by the presentation style that I choose, even if I haven't chosen it yet! However, if I've already chosen one that mostly fits my needs but I'm not happy with a particular style, I can apply some HTML and CSS to the different MAML elements without having to update anything in the topics themselves. By reusing the same common tags throughout my documentation, it looks much more professional, it's easier to manage and it's even portable since it's all XML, so if in the future I want to generate Open XML documents instead of HTML, I won't even have to change anything in my topics.

Note that if you want to convert all of your existing HTML topics to MAML in a batch process, I've got a tool called DocToMaml. It's currently in beta, but it does work. Any feedback on it will be appreciated :)

For the next version of DocProject 2008 (Beta 3) I'm working on a MAML WYSIWYG editor that is integrated into Visual Studio, so keep your eyes open for that.

If you have any feedback about how MAML and Sandcastle's conceptual build process can be improved please let the Sandcastle team know by submitting a request to the Sandcastle Issue Tracker on CodePlex.

DocProject Roadmap Part II

Dave Sexton — Sat, 03 May 2008 19:36:02 GMT

In my first DocProject Roadmap post I described my preliminary plans for DocProject 1.x and later versions. In this post I'm going to discuss the project's current status and some updates to my plans for future versions.

1.11.0 RC

DocProject 1.11.0 RC will be deployed within a week after the upcoming Sandcastle release. It contains several new features and bug fixes, and also a few breaking changes that I'll be sure to mention on the release page.

I expect a few changes to Sandcastle that may prompt the addition of a few new features to DocProject before the next release (e.g., support for Help 1.x and Help 2.x project management and, possibly, the ability to include raw HTML topics using Topic Explorer), but since I can't start working on them until Sandcastle is released, there's obviously going to be a delay.

A week should be more than enough time though since I've taken some time off from paid employment to work on my open source projects - a sacrifice that I can barely afford, but working on my own projects is more fun than writing line of business apps and I just couldn't resist after losing my only client anyway (they lost their biggest client first and had to suspend my services, maybe indefinitely).

Universal Installer

The next version of DocProject, 1.11.0 RC, can install DocProject for Visual Studio 2005 and 2008 simultaneously, including all supported Express editions. The code base for DocProject 1.x and DocProject 2008 are now identical and as a result DocProject 2008 now uses the 1.x assemblies.

Ending Phase I

I've done a lot of refactoring in 1.11.0 RC, but I still plan to deploy it as the final release candidate (RC) for DocProject 1.x, with compiler optimizations enabled and without any debug symbol databases (.pdb).

Feedback is a must in this release so that I can iron out showstoppers and maybe even add some mission-critical features that people have been waiting for. If you're a fan of DocProject and you use VS 2005 then now would be the time to get in your suggestions for DocProject 1.x since most of my focus in the next phase of development is going to be on Visual Studio 2008.

Unfortunately I didn't get to add some of the features to 1.11.0 RC as I had planned, but they may be added to 1.12.0 or, more likely, DocProject 2008 Beta 3.

First Production Release

I still expect 1.12.0 to be the first production release of DocProject, but now it will target both Visual Studio 2005 and 2008. To support this I've reorganized source control, once again, and included the source for other projects as well, such as DocToMaml. I've also decided not to package the source code with the installer anymore, starting with 1.11.0 RC.

My plans for DocProject 1.x after the first production release are to provide subsequent releases for bug fixes and small feature updates only, targeting both VS 2005 and 2008. The major features that I have been planning will make their first appearance in DocProject 2008 Beta 3.

DocProject 2008

After I deploy 1.11.0 RC, development will continue on both 1.12.0 RTW and DocProject 2008 Beta 3 simultaneously, although the most notable of new features will only be included in DocProject 2008 Beta 3. Some of these features are described below.

Please let me know which features you're most interested in so that I can prioritize.

Visual Studio Package

DocProject currently provides an Add-In that only uses VS automation, but I'd like to provide more integration to create a better Topic Explorer, Topic Editor and Topic Designer, and even a preliminary MAML editor. I've done some initial research and have already come up with a plan to start development.

This is an exciting task to work on but I don't plan on the first release being extremely stable as this will be my first VS package; although, I do plan on reusing a fair amount of the automation code since it has already been tested. I'll also incorporate much of DocProject's current architecture, including its high level of extensibility and its "openness".

Business logic, infrastructure and utilities will probably end up being mostly the same, but I do want to take this as an opportunity to update some of the designs that DocProject currently uses, like change buffering.

Standalone UI

The current DocProject External UI program relies on DocProjects and DocSites that have been created in Visual Studio. For help authors that just-so-happen to be developers, this isn't a problem. But for anyone that isn't a developer, the free Visual Studio Express edition works well but doesn't make much sense since it's obviously not designed just for building documentation, and certainly not for authoring it.

DocProject 2008 Beta 3 will use the new Visual Studio 2008 Shell to provide a tool that has all of DocProject's features, but without requiring Visual Studio to be installed. I haven't decided yet whether I'm going to use integrated or isolated mode, but I'm leaning towards integrated.

This should be quite easy to create since DocProject is becoming a VS package anyway. A blocking issue though is whether MSBuild is provided by the Shell redistributable. If not, then I may just have to continue to deploy the External UI instead. I'm also not sure whether the Shell provides C# and VB.NET source code editors, but if not it's no big deal since they aren't available in the current External UI either. (The code editors would be used to edit the project's build process component. I think this would be a great feature to have in the standalone app, if possible, but it's not a requirement.)

My ultimate goal for the standalone UI is to create a program that works with or without Visual Studio. It must provide the ability to create new DocProjects and DocSites from existing MSBuild project templates, so they work in Visual Studio as well. It will also provide all of DocProject's existing and upcoming features, including support for UI extensibility; e.g., providers can register new tool bars and tool windows.

Continuous Integration

A project option will be available to enable support for continuous integration. When enabled, DocProject will copy all dependencies into the project, including DocProject and Sandcastle assemblies, configuration files, and the HTML Help Workshop program, allowing them to be easily committed to source control. After a DocProject or DocSite is checked-in, another team member can get the latest version to their computer or to a build server and all the dependencies will be updated as well, without requiring any installation.

The only blocking issue of which I'm aware seems to be that Help 2.x requires installation. DocProject does not use any of the command-line tools that are installed by the VS SDK, however, it does use the MS Help COM interfaces. Unfortunately, to get the libraries and COM objects installed you must install the VS SDK, but to install the SDK you must first install Visual Studio. I'll continue to research this when the time comes to see if I can find a workaround, but so far it doesn't look good.

Continuous Builds

I mentioned this in my previous roadmap post. The idea is to detect only the changes made to APIs and XML documentation and have a web server that continuously rebuilds a live DocSite so that the updates are visible immediately to all team members.

This feature will require dependency detection and differencing algorithms for both API references and XML documentation. One question is whether these algorithms will perform better than building entire documentation sets from scratch, but I believe that they certainly will in the scenarios where it really matters.

The goal is that for projects with many large assemblies there should be little delay to see the updates in documentation, at least compared to the very long delay that ensues when rebuilding entire documentation sets from scratch, which is currently the only option with Sandcastle.

To use this feature you would start be creating a new DocSite project and probably selecting some option in the New Project Wizard to indicate that you want continuous build support. You would also select a VS solution file or an MSBuild project that the DocSite will use to automatically build sources. In the last wizard step you would add all of the sources to the project as project references, like normal. When finished configuring the project as usual, you would deploy it to an intranet web server that all team members can access over HTTP.

The live DocSite would trigger a rebuild using MSBuild at a configurable time interval. This way MSBuild will detect updates automatically and the DocSite will always have the latest versions of all sources. The DocSite will monitor changes to the sources and continuously rebuild only those topics that were affected. It will also update the DocSiteContents.xml and DocSiteIndex.xml files, as well as the full-text search index.

One problem might be getting the latest source code onto the server so that the DocSite can rebuild it. In a team scenario it's probably safe to assume that some sort of source control system is in use. I'm not sure if it's possible, but if source control systems provide an event model that could be used to automatically get the latest version to the web server after each check-in, that would solve the problem. Otherwise, manually getting the latest version to the server may be required. It may be possible to access the source code over a network share (to a build server perhaps) so that it doesn't have to be stored on the web server, although I'm not sure if MSBuild works with UNC.

Using external sources instead of project references may be another option, but replacing the assemblies on a network share automatically might be just as difficult. It could be done manually or, as with the solution for project references, using source control events to run a build after each (labeled?) check-in.

Localization

I've already put a few hours into researching localization support in DocProject. What I discovered, and I'm not surprised, is that if I want an implementation that isn't a hack I'll have to add some new features to support dynamic changes to various configuration files during builds. Anticipating this problem, I had decided to defer localization support into DocProject 2008.

I suspect that these new support features will be useful on their own as well, much in the same way that extension methods in C# 3.0 were probably added to support LINQ yet they are even useful by themselves. The new features will add to DocProject's already high level of extensibility and will be customizable via the DocProject configuration file.

My goal for localization support is for a single DocProject or DocSite to produce multiple compiled help files for different locales in a single build. This must be accomplished without affecting the current feature-set of DocProject, including the Sandcastle Build Component drop-down properties and the fact that you can currently change almost anything that you want in the BuildAssembler configuration files. So in other words, the localization feature must be completely transparent when it's not being used.

All Sandcastle content items and user-written XML documentation comments will be localizable. Once implemented, I plan to ask the community to create language packs for content items in various locales (Unfortunately, I only know English, and not so well ;). A language pack will be a .zip file that contains one or more Sandcastle content documents and an XML manifest file, which describes the contents and rules for locale inheritance. DocProject 2008 will be able to locate the packs in its installation directory, by default, or a user-configured location.

With language packs, DocProject can offer out-of-the-box localization for multiple languages so that help authors can simply check a box and build their project to produce multiple compiled help files, one per language. Localized XML documentation comments can be added to the project's Help\Comments\[locale] folder (e.g., Help\Comments\en-GB) and it will be merged automatically with XML documentation comments from the source code (how it's merged will depend upon the Merge XML documentation project option, in the same exact way that it works now in the current version of DocProject). Likewise, localized conceptual topics (MAML) may be added to the project's Help\Topics\[locale] folder.

Instead of trying to write down the many concepts related to implementing localization support that I have echoing around between my ears, I'll just post my notes in their raw form. If you want more details, please let me know.

1. add content item mappings to DocProject config file: 
  <item name="..." presentationNames="Visual Studio 2005, Sandcastle Hana" source="options-property-name"/> 
  - Items that are added here are automatically removed from the content item documents when a project is 
    first created.
  - Before each build a dynamic content item document is generated in the working directory for all of the 
    items that are configured here.
  - Note that a configChange must be added to register the dynamic content item document. 
2. Add a wizard step, before the Create Shared Content step, that allows a user to specify the values for 
   each of the pre-defined_enum_names: 
  - Documentation set name
  - Running header text
  - Copyright
  - Company name
  - Default locale (combox box) 

3. Add a Localization Management dialog. 
  - Choose the different locales in which distinct documentation sets will be generated by selecting from a 
    drop down list, which will add the selection to another list.
    - one locale may be selected as the "working" locale for the dialog; UI elements will apply only to the 
      "working" locale.
    - a tree view, like solution explorer, shows only the folders that may be localized within the project; 
      e.g., Help\Topics, Help\Comments, etc.
    - one node may be selected at a time.
    - for the selected locale/node, a button can be clicked that will prompt the user to choose a locale from 
      which to import files, with the option of specifying whether the import should be performed recursively.
  - Choose a default locale (corresponds to the wizard step option indicated above).
  - A single build will produce all of the documentation sets in each locale.
  - The BuildContext should have a property that returns the current LCID that's being built and another that 
    returns the list of all LCIDs that are being built.
  - Output will be stored in sub folders named with the locale (e.g., bin\Debug\sp-SP\ or Help\bin\sp-SP).
  - Local input will be stored in sub folders named with the locale (e.g., Help\Topics\sp-SP\, 
    Help\Comments\sp-SP\, Help\Presentation\Style\Content\sp-SP, Help\Presentation\Shared\Content\sp-SP).
  - The default locale's content will be stored at the root;  e.g., Help\Topics\, Help\Comments\, etc. so the 
    build process for the default locale will work the same way that it does now.
  - Source input can be managed in the same way that version management works. 
4. Support dynamic updates to config files at build time. 
  - Take all of the <add> elements in the <configChanges> element and move them under a sub element named, 
    import.
  - Add a new sub element named build that will contain <add> elements for changes to be applied during 
    builds.
  - replacements for build changes will work the same as for import changes, although they will also allow 
    string replacement tokens: {0} {1} {2} ...
    - The values of replacement tokens will be defined by attributes on the <add> element: value0="..." 
      value1="..." value2="..."
    - The values of the replacement attributes are strings that identify the names of public properties on 
      the current derived implementation of the BuildSettings class during builds; e.g., 
      value0="DocumentationSetName"
    - Single-valued properties are converted to strings using Convert.ToString().
    - Properties of System.Collections.IEnumerable implementations are iterated and each element is handled 
      recursively.  Single-valued elements are converted to strings and IEnumerables are iterated.  
      The replacement is executed once for each iteration, recursively.
  - When a build starts the configuration files that will be used are copied to the working directory and 
     then the build changes are applied.
  - Build assembler will use the config files in the working directory. 
5. Support dynamic localization of config files at build time.
  - Add a new sub element to <configChanges> named, localization.
  - replacements for localization changes will work the same as for build changes, including replacement 
    tokens, expect that replacements are specified as properties of the current BuildContext object.
    - BuildEngine implementations should be able to override a method to create a BuildContext 
      implementation, such as SandcastleBuildContext, so that properties such as Lcid and Locale are dynamic.
  - When a localized build starts (not the BuildStarting event but the first step of a localized build, which 
    is executed repeatedly within a single build - once for each locale), the configured localization 
    changes are applied, for the current local, to the working copy of the build assembler config files.  
    Build assembler must then be executed against the localized copy.  (The original copy must not be 
    replaced.) 
** The explanations above were created before this example.  This example illustrates the _better_ approach 
when there are conflicts in the notes above since it's more thought out.
 
- DaveSexton.DocProject.dll.config -
Sandcastle presentation configuration section

<presentations>
  <presentation name="..."
                ... all of the attributes that currently appear in a presentation's add element ... >
    <options>
      <add name="RunningHeaderText" type="System.String" displayName="Running header text"
           description="The text that will appear at the top of each topic." category="Configuration" 
           sort="80" />  <!-- the specified type must be convertible to and from System.String 
                              (serialization is not supported) -->
    </options>
    <content>
      <item name="runningHeaderText" value="RunningHeaderText"/>
            <!-- value is the name of a dynamic project option here, but it can be any property that 
                 exists on a DocProjectOptions implementation -->
    </content>
    <newProjectWizard>
      <step type="type name" assembly="assembly name"/>
            <!-- steps are inserted before the Create Shared Content step in the order that
                 they are added here -->
    </newProjectWizard>
  </presentation> 
  ... more presentations
</presentations> 
<configChanges>
  <import>
    ... all of the stuff that is currently in the configChanges section ... 
    Note that the default comments folder should be changed from Comments\*.xml to Comments\default\*.xml 
    since comments should be segregated by locale; 'default' is used since the default locale can be changed.
  </import>
  <build>
    <add name="assign default reference links locale" ....
         xpath="find ResolveReferenceLinksComponent2 locale attribute"
         setAttribute="{0}"
         value0="Locale" />  <!-- Locale refers to a property (that must be added) on the 
                                  SandcastleSettings class -->
  </build>
  <localization>
    <add name="assign reference links locale" ....
         xpath="find ResolveReferenceLinksComponent2 locale attribute"
         replaceWith="{0}"
         value0="Locale" required="true" />
    <!-- Locale refers to a property on the SandcastleBuildContext class (this class does not currently 
         exist; it will derive from BuildContext) -->
    <!-- The required attribute indicates that append should be used if no node is matched by xpath; 
         although, I'm not sure if I'll be able to determine programmatically whether xpath is selecting an 
         attribute or an element --> 
    <add name="assign localized comments" ....
         xpath="find CopyFromIndexComponent with index name='comments' and select 
                files='Comments\default\*.xml'"
         replaceWith="Comments\{0}\*.xml"
         value0="Locale" /> 
    <add name="assign shared content items" ....
         xpath="find all of the shared content component's content items that start 
                with ..\..\Help\Presentation\"
         replaceWith="..\..\Help\Presentation\content\{0}\{1}" value0="Locale" value1="Regex:[^\\]+.xml"
         collection="true" />  <!-- the collection attribute will indicate whether xpath is expected to 
         return a node collection, in which case this change is applied to each node -->
  </localization>
</configChanges>

Sandcastle: Auto-Generated Bibliography

Dave Sexton — Fri, 25 Apr 2008 14:12:58 GMT

June 11, 2008 Update: This feature is now available as part of the Sandcastle Styles patch and DocProject 1.11.0 RC.

Wouldn't it be cool if you could cite books and web sites while authoring MAML and XML documentation comments and have Sandcastle create a per-topic bibliography automatically?

Someone posted that question in the Sandcastle forums recently and I came up with a solution (in that discussion) that works for the VS 2005 presentation style and both reference and conceptual builds. Please add your vote to this feature request if you're interested in having this ability in Sandcastle.

This isn't a feature that I'm going to add specifically to DocProject since it requires updating XSL transformations. You can add it yourself for now though until it becomes a feature of Sandcastle (hopefully :). Just follow the instructions that I gave in my post in the Sandcastle forum.

Once you make the appropriate updates to the presentation style, here's what you can do to start using this feature in code comments. (Conceptual usage is similar, although you must add an empty <bibliography/> element somewhere in the root of your MAML, preferably before or after the relatedTopics element.)

First, author some XML documentation comments that contain citations.

<remarks>
  <para>
    The statistics show that Sandcastle is a popular tool on 
    CodePlex <cite>sandcastle activity stats</cite>.
  </para>
  <para>
    DocProject can be used to automate Sandcastle <cite>DocProject</cite>.
  </para>
  <para>
    The top referring sites are similar for DocProject and 
    Sandcastle <cite>sandcastle activity stats</cite><cite>docproject activity stats</cite>.
  </para>
</remarks>

Next, create a bibliography.xml file that provides additional information. It will be used for all topics that you write in both conceptual and reference builds.

<?xml version="1.0" encoding="utf-8" ?>
<bibliography>
  <reference name="sandcastle activity stats">
    <title>Sandcastle Activity Statistics</title>
    <author>WebTrends</author>
    <publisher>CodePlex.com</publisher>
    <link>http://www.codeplex.com/Sandcastle/stats/view</link>
  </reference>
  <reference name="docproject activity stats">
    <title>DocProject Activity Statistics</title>
    <author>WebTrends</author>
    <publisher>CodePlex.com</publisher>
    <link>http://www.codeplex.com/DocProject/stats/view</link>
  </reference>
  <reference name="DocProject">
    <title>DocProject</title>
    <author>Dave Sexton</author>
    <link>http://www.codeplex.com/DocProject</link>
  </reference>
</bibliography>

Each in-line citation will be replaced with a hyperlink and a number, which corresponds to an entry in the bibliography that is automatically generated at the bottom of each help topic when one or more <cite> elements are detected.

DocToMaml 1.0 Beta is Now Available

Dave Sexton — Sun, 20 Apr 2008 05:51:27 GMT

DocToMaml 1.0 Beta is a tool that converts HTML and XHTML help files to Microsoft Assistance Markup Language (MAML) in a batch process.

MAML help files are used by DocProject and Sandcastle to build user documentation in various presentation styles.

DocToMaml provides a console mode and a project-based graphical user interface (GUI) for adding inputs and defining conversion rules to quickly and easily convert HTML files into MAML. Future releases will provide more flexibility for defining rules, but the beta can still be used to greatly decrease the amount of effort that would be required to convert large numbers of HTML files into MAML, compared to doing it manually.

Features

Some of the features of DocToMaml are:

GUI and console mode.
Project-based for quickly saving and loading different configurations.
File and folder inputs are supported.
Global and input-specific rule sets may be defined.
Edit the source HTML of a file input using a WYSIWYG editor for full control over the conversion.
Convert a file input in memory so that you can see the result quickly.
MAML results for file inputs can be modified in a text box.
Batch conversion saves results to disc for all file and folder inputs and generates a conceptual artwork file that can be used by Sandcastle's ResolveArtLinksComponent build component.
Hyperlink references to local topics are updated automatically.
Preliminary user documentation.

Current Limitations

Only the Conceptual MAML document type is supported.
Subsections and sub containers are not supported. For example, nested tables and lists are added to the current in-line element, if one exists; otherwise, they are added as new top-level containers.
Images appear to be broken in source view, although this has no effect on the output. You don't have to update the paths to broken images since DocToMaml doesn't do anything with image files in the current release anyway.

For help with DocToMaml, see the compiled help file that is available for download on the release page.

Article Features DocProject in Microsoft's Dutch .NET Magazine

Dave Sexton — Mon, 07 Apr 2008 16:15:12 GMT

Jan Schreuder wrote an article on Sandcastle for Microsoft's Dutch .NET Magazine and it's now available on the web. In it he provides an overview of Sandcastle and some instructions on how to use it. The article also features a few popular community tools that are available for use with Sandcastle; namely, Sandcastle Help File Builder, AjaxDoc (ScriptDoc) and DocProject. Jan mentions that DocProject is his preferred tool for automating Sandcastle and cites some of its advantages. Thanks!

The article is written in Dutch, but I was able to successfully translate it using Google Translator. First, download the PDF (visit Jan's blog for the link) and then save it as text (check the File menu). Copy and paste the text into the translator, select Dutch to English and press Translate. It works well enough to get the gist of the article.

Since the article was written there have been some important changes to Sandcastle and DocProject. Most notably, Sandcastle is now RTW on CodePlex and DocProject now provides first-class support for conceptual documentation using MAML, which of course wasn't mentioned in the article.

More Information about Sandcastle

For an up-to-date reference check out my (peer reviewed) Sandcastle Help article on CodePlex. It doesn't go into detail about how to use Sandcastle but it does provide a bullet-point overview and catalogs the different tools and documentation that exist elsewhere on the web. It's a good starting point.

More Information about DocProject

See my About DocProject article on CodePlex for an overview, screen shots and how to get started.

I also plan to write a few more DocProject tutorials in the future, as well as Sandcastle tutorials for things like how to create a custom presentation style and how to add custom tags, so keep an eye on my blog and DocProject's RSS feed on CodePlex.

Auto-Input Protection 2.0 Beta Is Now Available

Dave Sexton — Wed, 02 Apr 2008 00:26:00 GMT

I've just deployed Auto-Input Protection 2.0 Beta to CodePlex. (Finally!)

It was changed from a Production release to a Beta release because there are so many breaking changes, although I'm confident that it works since I've been using it on my blog for the last week or two. I've even fixed a few bugs during that time.

The release page lists the breaking changes and most of the new features.

Here are a couple that aren't mentioned:

All of the provider collection elements in the web.config file are now optional. (It used to be that just the <filters> element was optional.)
CrossHatchAutoInputProtectionFilterProvider is now built-in. Instead of using a diagonal cross hatch each time it selects a HatchStyle value at random, although you can configure it to use a single style if you want.
The ProviderHelper class is now public. It's useful for parsing configuration values from strings into other types.
An ASP.NET Web Application project, for testing AIP, is part of the source code provided by the installer.
You now have the choice of using the ASP.NET cache or session state to store challenges on the server. With out-of-process session state, AIP can be used in web farm scenarios.

Security

This release fixes a security flaw that was reported for AIP 1.0.0. If you find any other flaws please don't hesitate to report them to me so that I can try to fix them.

Note that due to the flaw I've added some new behaviors to help secure AIP; however, it may not be appropriate for immediate use in some scenarios. A timeout is now implemented that will cause validation to fail if a user does not respond in a timely manner (30 seconds).

If you are using the control on a blog (like me) or any other page that contains reading material or data entry fields, then you can increase the default timeout by setting the ValidationTimeout property on the AIP web control.

Alternatively, although not recommended, you can disable this behavior entirely by setting the ValidationKeepAlive property to true on the AIP web control. Doing so will cause unused challenges to remain on the server indefinitely, which will increase the amount of memory needed upon each request. (An unused challenge is one that is requested but never answered.) If you do decide to disable this timeout (by enabling ValidationKeepAlive) then I recommend setting the PersistenceMode property (new to the AutoInputProtection class) to a value of Session so that at least when a user's session expires their unused challenges will too. You can set this property easily on the autoInputProtection element in your web.config file:

When you enable session state persistence you should also add the new AutoInputProtectionSessionRequestHandler to the configuration file instead of AutoInputProtectionRequestHandler. Refer to the docs for more information.

Documentation

The first batch of preliminary docs were built for this release. Naturally, I used DocProject 1.10.1 RC and Sandcastle so that I could automatically generate reference documentation from my triple-slash code comments and write conceptual documentation using MAML.

The AIP installer merges the MS Help 2 docs (.HxS) into Visual Studio 2005 and 2008 automatically. The HTML Help 1.x docs (.chm) is provided on the release page as a separate download.

A bit off-topic...

For the DocProject users out there, I've learned a few things about Help 2.x since I built the documentation for AIP and I plan to write a tutorial that describes how to:

Add DocSet attributes to your topics so that your documentation appears when filters are applied in Document Explorer, including custom filters.
Set the home and default pages.
Use the Help Integration Wizard to produce a Merge Module for your .HxS file that can be added to a Setup Project. The wizard automatically generates the required collection-level files and allows you to specify titles, IDs and custom filters that will be installed automatically. I'll also describe a few showstoppers that you may run into as well.

There's already documentation online for some of this stuff, but I plan to write this tutorial with DocProject in mind.

In the AIP solution there are two merge modules: one for VS 2005 and one for VS 2008. Both are referenced by the installer project. I didn't include the DocProject that I used in the solution simply because AIP was written in Visual Studio 2008 and I was using DocProject 1.10.0 RC, which requires Visual Studio 2005.

ContractN on CodePlex

Dave Sexton — Mon, 10 Mar 2008 10:23:53 GMT

I've just released the first beta version of ContractN, which is a fully managed programming-by-contract framework that uses the CLR's built-in support for aspect-oriented programming (AOP), which provides a way to seamlessly and intuitively describe the required pre- and post-conditions of a type's contract.

I got the idea based on this blog post by Sasha Goldshtein; although, Sasha's implementation and that of ContractN have little in common other than their purpose. I liked the way Sasha used dynamically-generated code, but other than that I wasn't satisfied having to create the extra stuff that was required to enforce conditions.

Advantages of ContractN

The real benefit of ContractN, IMO, is that there's no overhead in terms of setting up your classes or their consumers, and you don't have to worry about breaking encapsulation or having to create any supporting interfaces or classes. You just need to derive an object from ContractN.ProgrammingByContract. (It's a shame that this is required though - I hope AOP is eventually introduced as a C# language feature; although, I suspect that the CLR would have to participate as well to alleviate the need for subclassing.)

ProgrammingByContract is an abstract base class that sets up the AOP infrastructure, which is used to intercept method invocations and define conditions as attributes. After defining a class that inherits from ProgrammingByContract, simply add the appropriate attributes wherever you'd like to enforce certain conditions on the public contract of your type. Here's a really simple C# 3.0 example:

public class Person : ContractN.ProgrammingByContract
{
  [InRequired, OutRequired]
  public string Name { get; set; }
}

The example illustrates that there are some built-in conditional attributes for basic argument checking, such as InRequiredAttribute, OutRequiredAttribute and ReturnRequiredAttribute, which throw an exception when an argument (or in the case of the latter two, output parameters and a return value) are null. I plan to add more conditions in the future, and the framework was designed to be flexible enough so that you can define your own conditions as well.

Custom Conditions

To define a new condition, create a class that derives from either PreConditionBaseAttribute, PostConditionBaseAttribute or ConditionBaseAttribute and override the abstract members. Usage should be intuitive depending upon the implementation that you need, but you can look at the source code for InRequiredAttribute (beta 1) as an example.

Dynamic Conditions

I decided to take a different approach than Sasha in terms of how dynamic conditions are implemented. I wanted to take advantage of static type checking instead of hard-coding constraints as strings. PreConditionAttribute and PostConditionAttribute allow you to specify a method name on the decorated type that will be invoked automatically whenever any public method is called. That also includes constructors and accessors for properties and events. (Note that these attributes are also valid on a property, constructor, method or event.) The method signature can vary depending upon your needs; generally it will be a parameterless instance method, though static methods are allowed as well. The types of arguments that are accepted encapsulate information about a particular invocation. For example, you could define a method that accepts an argument typed as ContractN.PropertyCall and the method will be invoked automatically whenever a property get or set accessor is invoked, pre- or post-invocation depending upon the attribute used. Within these methods you can write code that will actually be part of the class that it's meant to constrain, which maintains encapsulation, makes it easy to share code between constraints and allows access to state with compiler support.

Here's a more sophisticated example than above. It makes use of pre- and post-conditions described above and also implements ad-hoc conditions by providing an implementation of ICondition:

[PreCondition("TestStatic")]
[PreCondition("TestInstance")]
class AdvancedFeatures : ProgrammingByContract, ICondition
{
    #region Public Properties
    public string TestProperty { get; set; }
    #endregion

    #region Methods
    private static void TestStatic(PropertyCall info)
    {
        Console.WriteLine("Pre Static Property: {0}", info);
    }

    private static void TestStatic(MethodCallBase info)
    {
        Console.WriteLine("Pre Static Default: {0}", info);
    }

    private void TestInstance(MethodCallBase info)
    {
        Console.WriteLine("Pre Instance Default: {0}", info);
    }

    public void NoOperation()
    {
    }
    #endregion

    #region IPreCondition Members
    void IPreCondition.Apply(ConstructorCall info)
    {
        Console.WriteLine("Pre: {0}", info);
    }

    void IPreCondition.Apply(MethodCall info)
    {
        Console.WriteLine("Pre: {0}", info);
    }

    void IPreCondition.Apply(PropertyCall info)
    {
        Console.WriteLine("Pre: {0}", info);
    }

    void IPreCondition.Apply(EventRegistrationCall info)
    {
        Console.WriteLine("Pre: {0}", info);
    }
    #endregion

    #region IPostCondition Members
    void IPostCondition.Apply(ConstructorCall info, MethodCallReturn returnInfo)
    {
        Console.WriteLine("Post: {0}", info);
    }

    void IPostCondition.Apply(MethodCall info, MethodCallReturn returnInfo)
    {
        Console.WriteLine("Post: {0}", info);
    }

    void IPostCondition.Apply(PropertyCall info, MethodCallReturn returnInfo)
    {
        Console.WriteLine("Post: {0}", info);
    }
    
    void IPostCondition.Apply(EventRegistrationCall info, MethodCallReturn returnInfo)
    {
        Console.WriteLine("Post: {0}", info);
    }
    #endregion
}

When the above class is used as follows:

AdvancedFeatures features = new AdvancedFeatures();
features.TestProperty = "A test value";
features.NoOperation();

The console output is:

Pre Static Default: ContractN.ConstructorCall
Post: ContractN.ConstructorCall
Pre: ContractN.PropertyCall
Pre Instance Default: ContractN.PropertyCall
Pre Static Property: ContractN.PropertyCall
Post: ContractN.PropertyCall
Pre: ContractN.MethodCall
Pre Instance Default: ContractN.MethodCall
Pre Static Default: ContractN.MethodCall
Post: ContractN.MethodCall

One of the really neat uses for the PreConditionAttribute that I've found is to have ObjectDisposedException automatically thrown instead of having to check for it everywhere. Here's an example that builds off of the Person class in my first example:

[PreCondition("NotDisposed")]
public class Person : ContractN.ProgrammingByContract, IDisposable
{
    [InRequired, OutRequired]
    public string Name { get; set; }

    private bool disposed;

    private void NotDisposed()
    {
        if (disposed)
            throw new ObjectDisposedException(this.GetType().FullName);
    }

    public void Dispose()
    {
        disposed = true;
    }
}

After the Dispose method is called, public members are no longer accessible to external types. All calls will result in ObjectDisposedException automatically!

Conclusion

ContractN is more of a hobby project for me now than anything else, but it has potential and I'd really like to see it blossom into something useful. If you have any suggestions for improvements please let me know and I'll consider them for the next beta release. (I'm going to establish a timeline on-the-fly as I get ideas for features.) I have some interesting ideas for new conditions and I hope to blog about them in the future, so don't wander too far off if you're interested...

DocProject in the Visual Studio Gallery

Dave Sexton — Thu, 28 Feb 2008 01:28:05 GMT

Microsoft's Visual Studio Gallery was announced to the public today. It provides a one-stop-shop for Visual Studio add-ins, packages, item and project templates, macros, controls, coffee makers, toasters, etc. I think it's a great idea. Google can only help so much here (have you tried searching for "visual studio add-ins"? ;)

Anyone can register their free or paid products, so if you've got one, let the world know!

I've added DocProject under the Build, Documentation and Web categories. It has its own little HTML-formatted corner of the site too, which is a cool feature I think. Take a look at it here. It already has over 150 unique views!

Currently, the site does not host products so I simply link back to CodePlex (although I love CodePlex so I have no intention of leaving anytime soon).

From my few short discussions with the site's program manager, Anthony, I'd say that they have some good ideas to work with for the future. Features that'll make locating products and adding new products easier. So remember to look back occasionally for updates in the next few months.

DocProject 1.10.1 Release Candidate Is Now Available

Dave Sexton — Wed, 27 Feb 2008 11:30:06 GMT

The DocProject 1.10.1 Release Candidate is now available for download on CodePlex.

This release contains some important bug fixes for 1.10.0 RC. One of which, it was reported, prevented the DocProject Add-In from working at all on some installations of Visual Studio (the Project context menu could not be located).

It also provides built-in support for ResolveExternalLinksComponent, which has been updated to include support for URL mapping provider editors and a built-in database URL mapping provider, among other features and bug fixes. The stand-alone component will be released later this week.

ResolveExternalLinksComponent

Dave Sexton — Wed, 27 Feb 2008 11:01:08 GMT

ResolveExternalLinksComponent is a Sandcastle build component that I wrote to solve a general usability problem that was reported here, by Karl, and to dog food my Hosted Sandcastle Build Component Template. The component's current behavior was designed with Karl's help. Thanks Karl :)

Preliminary documentation for the component is here.

Note that the latest release of the component is built-in to DocProject 1.10.1 - a separate download is not required. When you create a new DocProject or DocSite the component will be included automatically in the Help1.x and Help 2.x reference stacks so that you can begin to use its features right away in your XML documentation comments.

Overview

The original problem, to paraphrase, was that Karl had to keep writing repetitive URLs for <see href="url"/> links throughout his XML documentation comments. The common URLs he was using pointed to third-party online documentation and each URL shared the same base, so only the relative portion changed between links. To simplify the process he wanted to write only the relative path each time a link was required, specify the base URL only once, somewhere else, and then have some magic combine them into an absolute path, post-compilation.

As it turns out, a Sandcastle build component was right for the job.

I liked the idea of using IDs instead of hard-coding common URLs throughout the documentation and felt that this would be a feature that I might use, so I developed the component to resolve <see xref="id"/> into hyperlinks using pre-configured ID-to-URL mappings. For Karl's particular scenario I added support for the vref attribute, which adds additional semantics to the ID so that it will act as the URL itself if a mapping is not defined.

During development I noticed a few opportunities to add more features, which I did, like being able to associate a group of ID-to-URL mappings with any combination of optional attributes. In particular, a base URL, hyperlink target, auto-generated reference topic ID or import file. The component allows for any number of mapping groups with any combination of these attributes, allowing for some pretty interesting scenarios.

For example, in one scenario you might define common URLs as IDs for all of your documentation but then override the URLs in one particular topic to point elsewhere, without even having to modify the XML comments in the API.

Another possibility would be to group mappings by hyperlink target. So, for example, you could set the default target for all mapped links to open in the same browser frame when clicked but then configure a group of links that reference a third-party website to open in a new browser window when clicked.

The component has a graphical editor that works in DocProject and the Sandcastle Help File Builder, which makes configuring it really simple. It also provides a few DocProject-specific features, such as providing a list of topic IDs that you can choose from, defaulting to the project's settings directory when using an external mappings file, using a relative path to an external mappings file, automatically including an external mappings file as a project item and expansion options for build component stacks in the DocProject Properties window.

What's New In Beta 2

The next release has a few bug fixes and some neat features that I'd like to mention here. You can read about additional updates on the release page.

First, I've added support for resolving IDs to URLs that are stored in a database. (See the section on URL Mapping Providers below for more information.)

You can now use xref and vref attributes on seealso tags as well; although, due to a current limitation in Sandcastle, the target attribute will be ignored. However, if Sandcastle eventually supports the target attribute on seealso tags then my component should work without having to be rebuilt.

The editor now provides the ability to edit the base and target attributes on the component element.

In DocProject, if you configure an external mappings file then it will be included as a project item automatically. Also, you can use the open file dialog to specify the name of a file that doesn't actually exist and it will be created when the editor is closed. The path of the file will be made relative to DocProject's working directory.

URL Mapping Providers

The common way to define a group of mappings is to add them to the component's XML configuration using the mappings and url elements. The class that parses url elements is, XmlUrlMappingProvider, and as you may have already guessed, it's a specialization of the abstract base class, UrlMappingProvider. Here's what a common configuration might look like:

<component type="DaveSexton.Sandcastle.ResolveExternalLinksComponent"
           assembly="C:\...\DaveSexton.Sandcastle.dll">
  <mappings>
    <url id="home" href="http://davesexton.com" />
    <url id="contact" href="http://davesexton.com/Contact" />
  </mappings>
</component>

You can create your own custom providers as well. To use them simply specify the full type name and path to the assembly using the type and assembly attributes, respectively, on the mappings element. The outer XML of the mappings element will be supplied to your provider as raw text.

URL mapping providers can have a UI that will be displayed in the component's editor to easily modify the provider's configuration. The built-in XmlUrlMappingProvider uses a simple DataGridView for editing the url elements.

DatabaseUrlMappingProvider

DatabaseUrlMappingProvider is a new provider as of DocProject 1.10.1 and the ResolveExternalLinksComponent Beta 2 release. It allows you to define ID-to-URL mappings in a database table instead of the inner XML of a mappings element.

This provider could be useful in scenarios where you already have URLs stored in a database or when you have a large number of URLs that must be shared between multiple tools, whether related to documentation or not.

A custom editor that allows you to configure the provider is embedded into the component's editor. With it you can easily specify the data provider, connection string, query, parameters and other settings all in one place:

Here's an example configuration that might be used with this provider:

<component type="DaveSexton.Sandcastle.ResolveExternalLinksComponent"
           assembly="%DocProjectBuildPath%\DaveSexton.Sandcastle.dll">
  <mappings type="DaveSexton.Sandcastle.DatabaseUrlMappingProvider"
            topic="M:SomeNamespace.SomeType.DocumentedMethod(System.String)">
    <connection provider="System.Data.SqlClient">
      Data Source=DEV1\SQLEXPRESS;Initial Catalog=Docs;Integrated Security=True
    </connection>
    <query>
      SELECT ID, HREF FROM UrlMappings WHERE TopicID = @TopicID;
    </query>
    <parameters>
      <parameter name="@TopicID" source="TopicID" />
    </parameters>
  </mappings>
</component>

The component can use any of the built-in Framework data providers (e.g, Odbc, OleDb, SqlClient) or even plug-ins such as Oracle.

Parameterized textual queries and stored procedures are supported, but only the first result set is used. By default the provider will look for ID and HREF columns, but you can specify different names.

Parameters can have hard-coded values or they can be mapped to a specific source. In the example above the value of the topic attribute will be used as the value for the @TopicID parameter. The other acceptable values for the source attribute are: BaseUrl, File and Target, which also correspond to attributes on the mappings element. To define a specific value for a parameter use the value attribute instead of source.

Sandcastle Build Component Templates 1.1 Released

Dave Sexton — Wed, 13 Feb 2008 05:03:23 GMT

The Sandcastle Build Component Templates 1.1 release provides two C# Item Templates that you can use to easily create custom Sandcastle Build Components in Visual Studio 2005 and Visual Studio 2008.

In this blog post I intend to provide some details about the templates, with more focus on hosted components and DocProject's API. Instructions for template installation and usage can be found here.

Basic Sandcastle Build Component Item Template

The Basic Sandcastle Build Component item template is a multi-file Visual Studio Item Template, written in C#, that provides a working example of a custom build component that can be used for command-line builds or with editor support in automation tools such as DocProject and the Sandcastle Help File Builder. It comes with a built-in graphical editor and a dynamic sub property for the DocProject Properties window, which can be shown by expanding the component in a build component stack (for more information about the stack properties, see How To Use Third-Party Sandcastle Components in DocProject).

Hosted Sandcastle Build Component Item Template

The Hosted Sandcastle Build Component item template is the same as the basic template, but it also provides direct access and a working example of how to gather information from DocProject's API, thus DocProject is required in order to compile the build components that are created based on this template. Although, DocProject isn't actually required to use the components if you provide a fall-back initialization path.

Initialization Paths

The template's Configuration class provides two initialization paths, one of which is a fall-back that's automatically invoked if the DocProject host API is not detected.

Note: The host API is never available during builds - it's only available when the component's editor is displayed.

Fall-back initialization works since the template depends upon just-in-time (JIT) compilation. If you properly encapsulate the use of host interfaces, as the template does out-of-the-box, then you can control the initialization path of the component's Configuration class.

The template's Host class is used to encapsulate host interfaces and services, and it provides a way to safely check, at runtime, whether a particular host is reachable. Support for DocProject's host API is built-in to the template. All other hosts will use the fall-back initialization path automatically unless you add support for them to the Host and Configuration classes. The only requirement is that the host invokes your component's editor by calling its EditValue method and passes in an IServiceProvider implementation that can be used to obtain a reference to one or more of the host's services. (On a side note, the value argument should be set to a System.Xml.XPath.IXPathNavigable implementation that's positioned on the outer XML of the component's configuration, which includes the <component> element itself.)

Modifying Project Options

The template gathers read-only data as an example and does not actually modify any build settings or project options at runtime. If you want your component implementation to write to the API, then make sure there's a clear relationship between your component and the changes that it's making.

For example, a proprietary AuthorBuildComponent changing the value of the Generate root API topic setting when edited will probably not be obvious to end-users. But it might be appropriate for the same component editor to add external sources if, for example, it were to provide a way for an end-user to create a list of associations between sources and author names, much like the Version management dialog does with version information. In this case, the component's editor could save the input-to-author mappings as its inner XML configuration data and add the external sources as a convenience for the user.

Hosted Components as Plug-Ins

Hosted build components are not meant to be a plug-in mechanism for DocProject, per se, but instead are a plug-in mechanism for Sandcastle. DocProject's API is exposed merely to provide a more user-friendly and integrated experience when editing Sandcastle build components in DocProject.

If you want to create a true DocProject plug-in, then create a custom build engine provider or a build process component, which can provide control over all aspects of DocProject, including the entire build process, engine settings, project options, tool bars, tool windows, menus, custom wizard steps in the New Project Wizard, etc.

DocProject's API for Hosted Components

With the recent release of DocProject 1.10.0 RC, a new interface was added that would provide build components access to DocProject's API, for their graphical editors. The API can be used to gather information about the environment in which the component's editor is being hosted. The component can then provide automatic configuration and apply appropriate editor defaults, simplifying configuration for end-users while also adhering to the project paradigm that DocProjects and DocSites use to store their settings.

The purpose of the gateway interface, IDocProjectHost is to provide components with access to DocProject-specific interfaces and types for the context in which the component's editor is being hosted. Here's the interface's definition:

public interface IDocProjectHost
{
    IDocProject Project { get; }
    BuildSettings Settings { get; }
    DocProjectOptions Options { get; }
    IBuildEngine Engine { get; }
    IEnvironmentHost EnvironmentHost { get; }
    bool RunningInVisualStudio { get; }
}

The Hosted template gets a reference to an IDocProjectHost implementation through the service provider that's passed to the editor's EditValue method. If the host is available then the Configuration class's InitializeForDocProject() method is invoked instead of the fall-back Initialize() method (see above for information about initialization paths).

The InitializeForDocProject method uses the types and interfaces exposed through IDocProjectHost to gather information, which it then stores in private fields. The fields back properties that are used by the template's EditorControl class. They are typed as nullable primitives, such as System.String and bool?, so if the values are never set then they'll remain null, in which case the EditorControl will substitute them with "Unavailable" for its read-only display.

Developers are free to remove this code (actually, it's recommended) and replace it with appropriate code for gathering information that's required by the component being developed. However, the same pattern can be used to safely encapsulate data that can be initialized with or without a host API.

Note: The configuration fields must not be typed as host-specific types or interfaces if you want to be able to use your components in other environments, without the host API installed.

Conclusion

With the release of DocProject 1.10.0 RC and the corresponding Hosted Sandcastle Build Component Item Template 1.1, developers can now have seamless integration in DocProject for their custom build components' editors, providing a more robust platform on which to configure and build documentation while potentially simplifying configuration for end-users through automation and inferred default settings.

DocProject 1.10.0 Release Candidate

Dave Sexton — Sat, 09 Feb 2008 15:32:46 GMT

The DocProject 1.10.0 Release Candidate is now available for download on CodePlex.

It contains lots of bug fixes and some new features that I hope you'll like. You can read my preview post for information on a few of the more important features that have been added, and a comprehensive list of all of DocProject's features is available here.

Be aware that I'm still in the process of updating the wikis on CodePlex, which can take a while.

If you feel like you want to leave a comment here, or tell me about your experiences with the new version of DocProject, good or bad, please go right ahead :)

Oh, and one more thing, Conceptual Content!!!

Now you can use DocProject to build a .CHM and .HxS for conceptual documentation, without the need for auto-generated reference topics.

In other words, DocProject automates the Microsoft HTML Help Workshop and Help 2.x compiler to build conceptual documentation right inside of Visual Studio using Sandcastle's conceptual build process and MAML, so the output looks identical to a presentation style such as Sandcastle's Visual Studio 2005. (Note that I haven't even attempted to build conceptual documentation with the other presentation styles since they were not tested by Microsoft.)

Getting Started With Conceptual Content

Create a new DocProject or DocSite and you can immediately start writing your conceptual documentation in Visual Studio's XML editor, with full IntelliSense for MAML schemas. (Though it seems that you may need to open your project's Help\Schemas\developer.xsd file in the designer first before you'll get IntelliSense.)

To get started, press the Topic Explorer button on the Sandcastle tool bar and then add a conceptual topic by clickingon the Topic Explorer's tool bar. DocProject will ask you which template you want to use. For general documentation use the template named simply, Conceptual. If you don't need auto-generated reference documentation, then you can build the project now and it will produce conceptual-only documentation.

Mixed Documentation

But even better, if you do have APIs that you want documented, DocProject will build all of your topics together as a single conceptual/reference project without any additional requirements. Simply add references to your source projects and build.

If a DocProject or DocSite has one or more sources for documentation (external or project references) then an auto-generated root topic for reference documentation will appear in Topic Explorer. You can add new conceptual topics to the TOC relative to the root reference topic and even drag & drop conceptual topics and the root reference topic to produce the TOC that you want. Add as many conceptual topics and sources as you'd like, then build. That's it!

Enjoy :D

DocProject Roadmap

Dave Sexton — Thu, 17 Jan 2008 13:58:17 GMT

As you may have already heard, Sandcastle [1] was officially released to the web (RTW) through CodePlex on January 15, 2008. The license that was chosen is the Microsoft Public License (Ms-PL) [2], but keep an eye on it because it may change [3]. There are still a few unanswered questions that I have [3] about how Microsoft's work on Sandcastle will continue and how it will affect DocProject, but things are looking very positive.

In this blog post I'd like to express a few of my goals and ideas for DocProject and maybe even try to establish some preliminary timeline. And of course, if you have any thoughts your feedback will be welcomed :)

The End of Phase 1

With the help of community feedback and my propensity for being anti-social in favor of sitting in a dark room, programming, DocProject's long initial development phase is nearing an end. The next release, which you can read about in my blog (DocProject 1.10.0 RC Preview [4]), brings together a few long-awaited features that will hopefully start to make DocProject into a useful help authoring tool (HAT) [5]. I'm going to try for Monday, January 21st, to release 1.10.0 RC, and I'm hoping that the worst-case scenario will be the following Friday.

From there I expect to deploy only one more Release Candidate that contains various outstanding bug fixes and feature requests and then I'll freeze DocProject's feature set for Visual Studio 2005. The following deployment, 1.12.0, should therefore be the first DocProject Production release. Expect that in March, 2008.

Visual Studio 2005 vs. Visual Studio 2008

I expect to have my own licensed copy of VS 2008 Standard edition sometime before the end of February, but until then I've decided that I will not be concentrating on any new deployments for DocProject 2008 Beta, although I'm very excited about using VS 2008 and I'll certainly jump on that bandwagon as soon as I can.

So for now, you can expect development to continue like normal for VS 2005. But once I start concentrating on VS 2008, I'm probably going to freeze the feature set for VS 2005, distribute the first Production release of DocProject 1.x, and then switch gears for .NET 3.5 and, possibly, VS Package development. I intended to eventually release DocProject as a true package, hopefully with its own editors and actual project types [6] (i.e., DocProject and DocSite Templates [7] that are recognized by Visual Studio as distinct project types, with their own property pages, etc.).

After DocProject 1.x goes into stabilization (the end of phase 1) I'll certainly provide support for it and help people whenever I can if they have questions about how to modify the source code or how to add additional features themselves. Although, the only official deployments that you'll see will probably be major releases that fix a large number of bugs.

Well that's my plan anyway because in the last couple of DocProject 2008 releases I've realized that maintaining two versions of the project is almost like double the work; however, since Visual Studio 2008 will allow me to target the .NET 2.0 Framework I may be able to work on both versions of DocProject simultaneously, without much additional effort. If that's true then hopefully I won't feel the need to freeze the DocProject 1.x feature set. Although, technically I can't really freeze DocProject's feature set anyway since it's open source ;)

DocProject Documentation

I plan to distribute compiled help for DocProject 1.x that consists of both API reference and conceptual documentation after the first Production release. I'd say that a week or two should be enough time to author useful, preliminary documentation. After that I'll probably just add content here and there and deploy whenever I reach certain milestones that I define on the fly.

A .chm will be downloadable from CodePlex and the installer will present you with the option to have DocProject's help content (.HxS) merged with Visual Studio's help. I'm even considering hosting a DocSite as an online reference and as a great working example of DocProject's and Sandcastle's capabilities.

Phase 2

The next phase will pickup with the development of DocProject 2008, targeting Visual Studio 2008 and the .NET 3.5 Framework. The timeline will probably start sometime in March, 2008. From there I hope to deploy on a monthly basis as I've done with DocProject for the past year+ (since December, 2006 as a matter of fact).

Planning

Although DocProject, in the next release [4], will provide first-class support for building mixed reference and conceptual documentation, unbounded filtering capabilities, much improved performance and a mostly finalized API, I still see lots of room for improvement. Namely, in the area of content-based features such as for authoring topics and localization. Also, here's a few of the outstanding tasks [8] that I'm going to look into for DocProject 2008:

Running DocProject in areas of heightened security (e.g., Vista with UAC enabled).
SQL Server full-text search provider for the DocSite templates.
Microsoft Word and Adobe PDF output.
The ability to annotate comments with developer notes.
Automatic token replacement.
Some new DocSite skins, maybe including one that makes judicious use of SilverLight. (Documentation might start looking better than the software it documents, if I achieve my goal, that is ;)
Change control and better support for team scenarios; e.g., the ability to have a server that continuously builds live documentation to keep it up-to-date.
The development of a simple community wiki for the DocSite templates, which I guess we can start calling the "DocSite Community Wiki" feature (sure, some might say it's a rip-off of the MSDN Community Content Wiki idea, and I guess they'd be correct ;). This should be very useful in team scenarios for large, volatile, hosted documentation sets.
The ability to register multiple Build Process Components [9] per project, with a management UI as well. I may even turn the Sandcastle/Deployment [10] engine into a BPC that can be added to any DocProject or DocSite.
Other various user-defined tasks (bug fixes and feature requests).

I have even more ideas that I've been tossing around for a while, so I hope to aggregate them into a blog post and eventually add them as work items in CodePlex. And if you have any ideas for DocProject features please let me know!

Development

Development will target Visual Studio 2008 and the .NET 3.5 Framework, and as I mentioned previously, I'm definitely considering rewriting areas of DocProject as a true VS Package with its own custom editors and project types. I'm also considering using WPF for the interfaces. There will be a learning curve but it's one that I'm going to have to accept eventually (and I really do want to learn).

Collaboration

I expect to continue collaborating with community members to find bugs and DocProject's potential for new features. It seems to me that the experience of DocProject users has been positive, so I'd like to continue working on DocProject in the future in the same way as I've been for the last year. But if you feel differently please let me know. Even though it's open source I'd still like to provide an acceptable level of service and support in my free time since the time that I put into helping end-users is also time that I'm putting into DocProject (even if it's just thought), which helps to make a better product even for me to use.

Extensibility

It might also be worth noting that I'm going to maintain the "openness" of DocProject by continuing to introduce new public APIs and areas for extensibility whenever possible. With the limited feedback that I've received, I'd say that DocProject's high level of extensibility was a success. A few people have mentioned to me that their businesses have created custom build engine providers [11] and build process components, and I've even used BPCs to help people debug issues in the past. Actually, my favorite feature of DocProject might actually be the build process component, which, incidentally, doesn't really have anything in particular to do with documentation.

Deployment

It's hard to predict when the first Production release for DocProject 2008 will be deployed, but if I can use the past year as a metric then I'd say another year from now is certainly reasonable, and possibly even longer than might be required. To be honest, I think the summer of 2008 is a reasonable goal as long as I keep my eyes on the prize.

Phase 3

At the start of phase 3 I hope to have already achieved my major goals for DocProject, which includes much better integration into Visual Studio and additional features that will make authoring documentation extremely simple and, in many cases, automated. Thanks to Sandcastle I believe that this goal is attainable.

For the future I think I'm aiming for much better external support so that non-Visual Studio users will be able to benefit from DocProject's features as well. The team-based features that I mentioned previously might get pushed into this phase, but we'll see how it goes. And finally, I'd like to hear your ideas for where you'd like to see DocProject go. After I'm able to meet most of my own goals I'd like to brainstorm with the community to come up with some new and innovative ideas to be a part of DocProject in the future.

References

[1] Sandcastle on CodePlex, http://www.codeplex.com/Sandcastle

[2] Microsoft Public License (Ms-PL), http://opensource.org/licenses/ms-pl.html

[3] CTP, License and Source Code, http://www.codeplex.com/Sandcastle/Thread/View.aspx?ThreadId=20557

[4] Dave Sexton's Blog: DocProject 1.10.0 RC Preview, http://davesexton.com/blog/blogs/blog/archive/2008/01/15/docproject-1-10-0-rc-preview.aspx

[5] Help authoring tool. (2008, January 9). In Wikipedia, The Free Encyclopedia. Retrieved 11:22, January 17, 2008, from http://en.wikipedia.org/w/index.php?title=Help_authoring_tool&oldid=183180723

[6] DocProject Work Items: VS 2008 Shell and Extensibility, http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=14029

[7] DocProject Components, http://www.codeplex.com/DocProject/Wiki/View.aspx?title=DocProject+Components

[8] DocProject Work Items, Advanced List, http://www.codeplex.com/DocProject/WorkItem/AdvancedList.aspx

[9] DocProject's Build Process, Build Process Components, http://www.codeplex.com/DocProject/Wiki/View.aspx?title=Build+Process#BuildProcessComponent

[10] DocProject Sandcastle/Deployment Plug-In, http://www.codeplex.com/DocProject/Wiki/View.aspx?title=Sandcastle+Deployment+Plugin

[11] DocProject tutorial: Creating a Build Engine Provider, http://www.codeplex.com/DocProject/Wiki/View.aspx?title=Creating+a+Build+Engine+Provider