DocProject 1.10.0 RC Preview

In this post I'm going to provide details and screen shots of some of the new features in the DocProject 1.10.0 Release Candidate, which includes several bug fixes and new features such as first-class support for conceptual topics (additional content written in MAML markup), some new tool windows for Visual Studio Standard+, and increased performance of the Build Assembler step.

I plan to deploy after the next Sandcastle release, which will give me some more time for additional testing, to ensure compatibility and to finish a few incomplete features.  And BTW, I'm going to try to get back on my monthly deployment schedule again :)

Improved Performance

First, I'd like to start out by saying that performance is something I should have paid closer attention to throughout development, but at some point I just lost focus on it (probably when I started testing exclusively against smaller documentation sets).  So as Sandcastle's performance improved, DocProject's didn't.  I think I may have finally redeemed DocProject in this release though.

A new project option named, Build assembler options allows you to choose from various settings that have a direct affect on the performance of the Build Assembler step:

The options that you have chosen will be used whenever Build Assembler is executed, for all types of builds; e.g., reference, conceptual, help 1.x and 2.x.

The default for new projects is Trace errors only, which should provide the same performance as None for a build that does not fail, while providing diagnostic information if it does.

In testing, a substantial speed increase of approximately 8 times is normal when compared to building in Visual Studio and the External UI in the 1.9.0 RC.  The speed is now similar to that of building a DocProject or DocSite on the command-line with MSBuild.  Although, with informational and warning messages disabled there is no log or trace of the tasks that Build Assembler performs and the UI is not responsive while the Build Assembler step is executing.

Enabling Trace all and Cancelable will provide the same behavior as in previous versions of DocProject; i.e., all information and warnings are traced and the build may be canceled at any time.  And although there's an obvious performance penalty with these options enabled, there will also be a noticeable improvement of approximately 5 times compared to 1.9.0 RC.  The speed is now similar to the speed increase garnered by opening a modal dialog during the Build Assembler step in 1.9.0 RC, as per the discovery by Cis in this discussion.  So if you want the Build Assembler step in 1.10.0 to function the same as in 1.9.0, enable these two options and you should still see a speed increase of up to 5 times.

Build assembler options is located under the Build category in the DocProject Properties window.  It's implemented as an enum type with FlagsAttribute, EnumFlagsConverter and related classes (link is to the 1.9.0 RC codebase).

New Tool Windows

In preparation for first-class support of conceptual content I had previously written an XmlTreeView control that was included in DocProject 1.9.0 RC.  It extended the FCL TreeView control by adding support for internal and external drag & drop operations, an XML data source and a specialized binding manager.  In 1.10.0 RC it has been refactored and new features have been added so that it's now being used to its full extent in the Topic Management dialog (formerly known as the API Topic Management dialog) and the new Topic Explorer tool window (shown at right).

The new Topic Filters and Topic Editor tool windows were also extracted from the old API Topic Management dialog's Topic Filters and XML Comments tabs, respectively, so that they can be used without having to open a modal dialog (in VS Standard or higher).  Both windows are automatically synchronized to the selected topic in Topic Explorer.  They function as documents although since they're actually tool windows there can only be one instance of them opened at any given time, which means that they can only be used to manage one topic at a time.  Their appearance and functionality hasn't changed since DocProject 1.9.0 RC (preview post) so I'm not going to go into any more detail about them here.

Topic Explorer

The new Topic Explorer tool window is only available in Visual Studio Standard edition or higher.  It can be shown by pressing the Topic Management button on the Sandcastle toolbar and supports docking with other tool windows or floating on its own.  It functions the same as the tree view from the old API Topic Management dialog, with additional features.

Table of Contents

You can drag & drop topics to create the table of contents (TOC) that will be used in compiled help and the DocSite templates.  The TOC will be generated exactly as it appears in Topic Explorer.  Its layout is stored in a file named topics.xml, found in your project's Help\Settings folder.

When you save your changes by clicking Visual Studio's Save All command button or menu item, Topic Explorer will rewrite the topics.xml file based on the current organization of its tree.

Auto-Generated Reference Topics

The Namespaces topic, which is the root API reference topic generated by Sandcastle, starts out as a placeholder topic and loads in the background so that you can manage the TOC without having to wait for Sandcastle.  Once Sandcastle has generated the reflection XML document and the reference TOC, the placeholder is automatically replaced with the Namespaces node (for large documentation sets this may freeze the UI for a few seconds while the tree is being updated).

This node does not appear, however, if your project has no valid project references or external sources.

You can drag & drop the Namespaces topic or its placeholder topic at any time to place it within the TOC; however, drag & drop is not allowed for the individual reference topics.  Neither is dropping a conceptual topic anywhere within the hierarchy of the Namespaces topic.

When saved, the placement of the reference TOC is stored as a single <stoc /> element, which may appear anywhere within the Help\Settings\topics.xml file.

Editing Topics

To open the new Topic Editor window for any particular API reference topic, simply double-click the topic in Topic Explorer.  To edit a conceptual topic simply double-click the topic in Topic Explorer and it will be opened in Visual Studio's XML editor.

I really wanted to provide the same editing support for conceptual topics as is available currently for reference topics, however, I discovered after some experimentation that the MAML schemas are a bit too complex for my simple XmlContentEditor control, and not to mention that HTML is not currently passed through into the final HTML topic as of the Sandcastle Oct. CTP, which would make an HTML-based editor kind of pointless.

In the future I hope to create editors for some of the specific MAML schemas and make them as dynamic as possible.

Toolbar

Topic Explorer's toolbar provides the following functions (from left to right):

Button	Description
	Toggles expansion of all nodes.
	Opens or activates the Topic Filters tool window for the selected topic, which provides a document-like UI for the regular expression and categorical filters that are also present in the Topic Management dialog.  Note that you can also filter topics simply by unchecking them in Topic Explorer.
	Synchronizes the tree with the active project.  Topic Explorer is automatically synchronized with the selected DocProject or DocSite in Solution Explorer, although if the topics.xml file is manually updated then the refresh button must be clicked to update the display immediately.  (This should be automatic though in a subsequent release.)
	Creates a new container topic that does not have an associated file, although as of the Sandcastle Oct. 2007 CTP this doesn't appear to be supported so I'll probably just hide the button for now.
	Creates a new conceptual topic node as a child to the current node and asks the user which conceptual template should be used to create the file on disc.  The file is then opened in Visual Studio's XML editor and the node is placed into edit mode so that the label can be set.  The label is used as the topic's title.
	Imports existing XML topic files into the project.  Note that existing topics must use MAML to be supported by Sandcastle; however, if a topic does not use MAML then you're free to update it using Visual Studio's XML editor, manually, after it's imported.
	Deletes the selected topic after confirmation.  Reference topics cannot be deleted however.  If a container topic (with the folder icon) is currently selected then its entire hierarchy of topics, including itself, will be deleted from the TOC and disc.  If an individual topic is currently selected then only it will be deleted from the TOC and disc, and if it has child topics they will be promoted to children of the deleted topic's parent.

Sandcastle Build Component Editors

I've only actually attempted to create one editor at this time, but expect to see a few more by the time I deploy 1.10.0 RC.  The editor that I've created already is for ResolveReferenceLinksComponent2:

To open this editor simply click the ellipses button (...) of a Reference Link Types component in the DocProject Properties window:

MSDN hyperlink options

These options apply to all hyperlinks that are generated for the MSDN link type.

The Target window option indicates the target for all hyperlinks created by the component for MSDN topics online.  It's implemented as a combo box that accepts the name of a target window (i.e., any string) or one of the values from the drop down list: _blank, _parent, _self or _top.  The default is _blank, which means that clicking the hyperlink to an MSDN topic will open up a new window.

MSDN Locale indicates the default locale to use when generating links to MSDN topics online.  The combo box accepts a custom locale string or you can select one from the drop down list, which is automatically populated with a long list of known locales, none of which are guaranteed to have content on MSDN.  The default value is en-US.

XML reflection file targets

The grid lists each of the individual <targets /> elements of the component, one per row.  You can delete existing rows or add your own.

Base Path is simply concatenated, with respect to file path conventions, to the specified File Pattern.  If a Base Path isn't specified then the current directory is used (most likely being your project's, buildhelp\assembler directory).

File Pattern indicates the XML reflection files from which hyperlinks may be generated.

Recursive indicates whether the Base Path should be searched recursively for files that match the specified File Pattern.

Link Type must be one of the values from the drop down list: None, Local, Index or MSDN.  You can read about the different link types on the Sandcastle blog in this blog post.

Current Tasks

I'm still working on creating some of the Sandcastle Build Component editors and implementing a few work items.

Currently, I've been refactoring the behavior of state persistence for DocProject options.  In previous releases, options are committed immediately when a change is made in the DocProject Properties window and changes are buffered in the Tools Options page.  However, in 1.10.0 RC, options are committed only when the project is saved.  This is done manually by clicking Visual Studio's Save All command button or menu item (and the standard configuration of VS will automatically save the project before each build).  To support this feature, options have been branched into two categories (internally): project and custom.  Project options are those that read and write their state directly using the IAnyProject.Settings property, whereas custom options, for example, might instead persist state to some file.  If you are writing your own DocProjectOptions implementation then you must override the new Save method in order to save changes to custom options.  For your project options (the ones that use IAnyProject.Settings) you shouldn't have to change anything.  The Commit method was used previously for this purpose, but it also was used to commit buffered changes in other situations, without persisting them to disc.  This type of functionality is now only required by the Tools Options page; although, clicking OK on Visual Studio's Options dialog will no longer save the changes to disc - it will only cause Commit to be invoked.  When the project is actually saved, then Save will be called.  In the DocProject Properties window changes are committed immediately, so Commit is never actually called (although that may change - I haven't determined it yet).  To check whether your custom options should be commited immediately have your code read the DocProjectOptions.CommitChangesImmediately property, which is already implemented in 1.9.0 RC.

The purpose of all this is to make sure that the behavior when updating DocProject options is always the same, regardless of whether they are project options or custom options or whether they are being edited in the DocProject Properties window or the Tools Options page.  The difference from previous versions being that changes are committed immediately and only saved to disc when Visual Studio's Save All command is executed.

Conclusion

The next release of DocProject finally provides that long awaited, first-class support for conceptual content.  Now you'll be able to use Visual Studio to easily create, manage and automate the generation of Help 1.x and Help 2.x documentation, optionally in combination with auto-generated API reference documentation.  This feature substantially increases DocProject's potential as a HAT (help authoring tool) and provides a strong foundation for more content-based features in the future.