Sandcastle Conceptual Help: Quick Start

• Download sample - 2.54 MB

Introduction

In this article, we will present the conceptual help introduced in the October 2007 CTP release of the Sandcastle Help Compiler System.

The previous release of the Sandcastle provided support for building API references for source codes based on the .NET XML-Doc format. While this may be useful in most cases, a complete software documentation will include two parts: the API reference documentation, and the "User Manual". While some software provide the manual in the Microsoft Word or Adobe PDF formats, most of us prefer the HTML format. In the HTML format, we prefer a look and feel similar to the API reference documentation. Many companies are now providing only online help systems; not only is this convenience, more useful, and cost saving, but it also makes our Al Gore happy!

Now, with the release of the October 2007 CTP, even the poorest ISV can produce professional documentations at a price they can afford - free. Well, "free" itself is a price, and in this case, a very expensive one. The conceptual help support in the Sandcastle came without a documentation (the documenter is not documented), making it difficult for the current Sandcastle GUI providers to integrate it into their tools.

This article, therefore, aims to provide the following:

1. For the Help Author

   Reduce the "free" cost of learning to use the conceptual help so that many can explore the potentials of this useful tool.

2. For the (GUI) Tool Author

   Provide information to help integrate the conceptual help support in new and existing tools.

Basically, I am trying to share with you all I have, currently, in my attempt to learn and master the conceptual help support in Sandcastle. I will be releasing a series of articles on this, but have provided all the tools and facilities in the accompanying download files, so that you will not have to work at my pace.

In this article, I will present the Quick Start to both introduce you and get you started. It will also help me gather information for the next article.

Now, for those new to Sandcastle's conceptual help, let me give a "free" screenshot of a typical output, which is actually part of the download files.

What is Conceptual Help?

Conceptual means pertaining to concepts or to the forming of concepts, so a conceptual help is a documentation of the concepts or how your software program will help to realize some concepts or ideas. Well, that is me trying to be technical, and believe me, it is not accurate. The accurate version follows...

The conceptual help is based on the Microsoft Assistance Markup Language or MAML, an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance for Windows Vista. The idea behind MAML is similar to DocBook (I do not know which is better).

MAML consists of several distinct content types, each one specific to a type of document. The MAML content types include: conceptual, glossary, procedural or how-to, reference, troubleshooting, etc.

The term "conceptual help" is actually out of place since the "conceptual content" is just one of the content types defined by MAML.

The MAML specification is currently not available, but the Sandcastle Team provides the schema of a derived version for developers. The schema is currently incomplete, which is adding to the "free" cost I mentioned earlier.

The schema for the conceptual content type, which is the most generic of all the content types, is shown below:

Here is an example of the conceptual help structure (the reality is different from the schema, an indication of an incomplete schema):

<?xml version="1.0" encoding="utf-8"?>
<topic id="GUID" revisionNumber="">
    <developerConceptualDocument
        xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
        xmlns:xlink="http://www.w3.org/1999/xlink">
        <title>...</title>
        <summary>
            <para>...</para>
        </summary>
        
        <introduction>
            <para>...</para>
        </introduction>

        <section>
            <title>...</title>
            <content>
                <para>...</para>
            </content>
        </section>

        <section>
            <title>...</title>
            <content>
                <para>...</para>
            </content>
        </section>
        <relatedTopics>
        </relatedTopics>
    </developerConceptualDocument>
</topic>

Important Note

The following must be noted about this and other content structures:

• The <title> tag is actually required for a successful compilation of the help, even thought not included in the schema.
• The <topic>'s ID must be a GUID, uniquely identifying each document in the help system.
• The file containing each document must be named with the <topic>'s ID value.

Finally, the good news: the Sandcastle Team provided the tool to transform, with a varying degree of completion and accuracy, the various content types to both HtmlHelp 1.x and 2.x for the presentation styles supported. A typical output using the VS-2005 presentation style, which is the best supported style, is shown above.

What is Included in the Download?

• Help Builder Library

  This is an easy to use library that will help you concentrate on the content types instead of how to build your help files.

  1. It will create the copies of your files with the the GUID names extracted from the topic ID in the directory required by the Sandcastle configuration file.
  2. It will create various files including the table of contents.
  3. It will help you compile your file and log the output.
• Schema Documentations

  Even MAML is well-documented. The version included in the October 2007 CTP version of the Sandcastle is not complete, making it difficult to extract the documentation. I have managed to extract a documentation of the provided schema, not very nice, but useful. It is named Maml.chm and located in the Builder folder.

• Quick Start Samples

  The sample sources, in C# and VB.NET, of the tutorial presented below.

• (The) Sample
  1. This is not just another example, but the main thing, and what I really want you to have.
  2. It is an illustrative example that shows you what you can do with Sandcastle, and then you take a look at the source to see how it was done.
  3. It aims to be a guide, a tutorial, and a cookbook! In fact, this article is extracted from it.
  4. A copy of the output named Manual.chm is located in the Builder folder, the same thing you will get if you compile and run this sample. The screenshot of the output is shown above.

Now, let's move to the tutorial or quick start section to begin some real work.

The Tutorial

This section presents simple steps to help you start using the provided builder library. We will create a simple help file that will display the conceptual help equivalent of "Hello, World".

The output will be as shown below:

Important Note

The library is for .NET 2.x or later, and using it requires VS.NET 2005. VS.NET is being used so that you can easily edit your XML files required by the conceptual help compiler.

Creating the Contents

1. Start your VS.NET 2005 (or later) and create a new Console Application in C# or VB.NET.
2. We need to add a reference to the builder library to simplify the build process. Locate where you downloaded and unzipped the sources accompanying this article. The conceptual help builder to simplify the build process is located in the Builder folder. In the Builder folder, there is a an Output sub-directory that contains the builder library, named Conceptual.Builder.dll. Add a reference to this library in your newly created console project.
3. Also from the Builder folder, copy the configuration file, Project.config and the batch file, Project.bat to your project directory and add them to your project.

   Note: The contents of the Project.config and the Project.bat files can be automatically generated and will be done in later articles. However, in this article, it is made available so that you can modify them and control the build process.

4. Now, right click the project in the IDE and add two folders, naming them Documents and Media.

   Note: The Media folder and its contents (to be added later) is not required by this tutorial, but the "fixed" configuration file requires it.

We have now prepared the project and are ready to add the contents required to define our document structure.

Creating the Contents

1. We need to add a conceptual document file. Right click on the "Documents" folder, select Add and then New Item.... From the displayed dialog, select XML File and give it the name Document.xml (for this tutorial, but it can be anything). Change the contents of this file to look like this...
   XML

   <?xml version="1.0" encoding="utf-8"?>
   <topic id="2aca5da4-6f94-43a0-9817-5f413d16f100" revisionNumber="1">
       <developerConceptualDocument
           xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" 
           xmlns:xlink="http://www.w3.org/1999/xlink">
           <title>Quick Start</title>
           <summary>
               <para>
                   A quick start tutorial for the Sandcastle Conceptual Help 
                   Compiler System.
               </para>
           </summary>
           
           <introduction>
               <para>
                   Introducing the Conceptual Help...
               </para>
           </introduction>
           
           <section>
               <title>Section - Quick Start</title>
               <content>
                   <para>
                       Hello, Conceptual Help!
                   </para>
               </content>
           </section>
       </developerConceptualDocument>
   </topic>

   Note: The "id" attribute of the <topic> tag must be a GUID, you can create a new one or just use the one provided for the demo.

2. Similarly, add MediaContent.xml to the Media folder, and modify the contents to be the following...
   XML

   <?xml version="1.0" encoding="utf-8"?>
   <stockSharedContentDefinitions fileAssetGuid="" assetTypeId="">
   </stockSharedContentDefinitions>

3. Finally, let's build a table of contents. Add the Project.xml file to the project and change the contents to the following...
   XML

   <?xml version="1.0" encoding="utf-8"?>
   <files>
       <file name="Document.xml"/>
   </files>

Follow the same steps to add more document files to the project.

We have now defined the document structure and are ready to configure the build process; this is where the Builder library comes in.

Using the Builder Library

1. The builder library added to this article will be used to compile the help file, and we need to configure it. Open your Program.cs for a C# project, or the Module1.vb for a VB.NET project.
2. Import the Conceptual.Builder namespace, and change the contents of the Program.cs file to that shown in the code section below.

The following C# and VB.NET codes illustrate how to create, initialize, and compile the help file using the Builder library:

C# Code

using System;
using System.IO;

using Conceptual.Builder;

namespace QuickStartCS
{
    class Program
    {
        static void Main(string[] args)
        {
            // 1. Set the working directory, which is the same as 
            //    your project directory
            string workingDir = @"..\..\";

            // 2. Prepare the documents and project file paths 
            string projectFile = Path.Combine(workingDir, "Project.xml");
            string documentsDir = Path.Combine(workingDir, "Documents");

            // 3. Create a new instance of the conceptual project
            Project project = new Project();

            // 4. Lets begin the build process...
            try
            {
                // First signal a beginning of a build process
                project.BeginInitialize(documentsDir, projectFile);

                // Second, initialize the working (or your project directory)
                // and build...
                if (project.Initialize(workingDir))
                {
                    // Third, build, only the batch build is implemented.
                    project.CompileBatch("Project.bat");
                }

                // Last, clean up...setting the parameter to "true" will delete
                // all the directories and files created for the build process.
                // NOTE: The HTML help files are not deleted.
                project.EndInitialize(true);
                project = null;
            }
            catch (Exception ex)
            {
                if (project != null)
                {
                    project.EndInitialize(false);
                    project = null;
                }

                Console.WriteLine(ex.ToString());
            }
        }
    }
}

VB.NET Code

Imports System.IO
Imports Conceptual.Builder

Module ModuleMain

    Sub Main()
        ' 1. Set the working directory, which is the same as 
        '    your project directory        
        Dim workingDir As String = "..."
        ' BUG in the CP syntax coloring will not let me write this correctly!

        ' 2. Prepare the documents and project file paths 
        Dim projectFile As String = Path.Combine(workingDir, "Project.xml")
        Dim documentsDir As String = Path.Combine(workingDir, "Documents")

        ' 3. Create a new instance of the conceptual project
        Dim project As Project = New Project()

        ' 4. Lets begin the build process...
        Try
            ' First signal a beginning of a build process
            project.BeginInitialize(documentsDir, projectFile)

            ' Second, initialize the working (or your project directory)
            ' and build...
            If project.Initialize(workingDir) Then

                ' Third, build, only the batch build is implemented.
                project.CompileBatch("Project.bat")
            End If

            ' Last, clean up...setting the parameter to "true" will delete
            ' all the directories and files created for the build process.
            ' NOTE: The HTML help files are not deleted.
            project.EndInitialize(True)
            project = Nothing
        Catch ex As Exception
            If project IsNot Nothing Then
                project.EndInitialize(False)
                project = Nothing
                Console.WriteLine(ex.ToString())
            End If
        End Try

    End Sub

End Module

Both the C# and the VB.NET codes are taken from working examples. The codes and all the steps outlined in this document are provided in the QuickStartCS and QuickStartVB samples.

Compiling the Code

No special build or compilation instruction is required, just compile the Builder library (if necessary) and your project. Then, run the project; if everything went successfully, the compiled help file will be automatically displayed. The output is located in the Help sub-folder.

Useful Links

• Download the Sandcastle October 2007 CTP here....
• The Sandcastle Wiki
• The Sandcastle Blog
• Microsoft Developer Documentation and Help System forum

Sandcastle related articles:

• Sandcastle Help File Builder
• Creating Custom Build Components for Sandcastle

History

• December 30, 2007 - Initial release - say version 0.1.
• December 31, 2007 - Fixed formatting.