Sandcastle 概念帮助：快速入门

Paul Selormey

4.59/5 (10投票s)

2007年12月30日

MIT

8分钟阅读

196778

870

了解如何使用 Sandcastle Help Compiler 编写用户手册。

下载示例 - 2.54 MB

引言

在本文中，我们将介绍 Sandcastle Help Compiler System 的2007 年 10 月 CTP 版本中引入的概念帮助。

Sandcastle 的先前版本支持为基于 .NET XML-Doc 格式的源代码构建 API 参考。虽然这在大多数情况下可能很有用，但完整的软件文档将包含两部分：API 参考文档和“用户手册”。虽然某些软件以 Microsoft Word 或 Adobe PDF 格式提供手册，但我们大多数人更喜欢 HTML 格式。在 HTML 格式中，我们更喜欢与 API 参考文档相似的外观和感觉。许多公司现在只提供在线帮助系统；这不仅方便、更有用且节省成本，而且还能让我们的 Al Gore 感到高兴！

现在，随着 2007 年 10 月 CTP 的发布，即使是最贫穷的 ISV 也可以以他们负担得起的价格——免费——制作专业的文档。好吧，“免费”本身就是一种价格，在这种情况下，是一种非常昂贵的价格。Sandcastle 中的概念帮助支持没有文档（文档工具本身没有文档），这使得当前的 Sandcastle GUI 提供商难以将其集成到他们的工具中。

因此，本文旨在提供以下内容：

对于帮助作者
降低学习使用概念帮助的“免费”成本，以便许多人可以探索这个有用工具的潜力。
对于（GUI）工具作者
提供信息以帮助将概念帮助支持集成到新工具和现有工具中。

基本上，我试图与大家分享我目前在尝试学习和掌握 Sandcastle 中的概念帮助支持时所拥有的一切。我将在此主题上发布一系列文章，但已经提供了随附下载文件中的所有工具和设施，这样您就不必按照我的进度进行工作。

在本文中，我将介绍快速入门，以介绍您并帮助您开始。它还将帮助我收集下一篇文章的信息。

现在，对于 Sandcastle 的概念帮助新手来说，让我给出一个典型的输出的“免费”截图，它实际上是下载文件的一部分。

什么是概念帮助？

概念意味着与概念有关或与形成概念有关，因此概念帮助是对概念或您的软件程序将如何帮助实现某些概念或思想的文档。好了，这是我试图在技术上进行解释，相信我，这并不准确。准确的版本如下……

概念帮助基于 Microsoft Assistance Markup Language (MAML)，这是一种由 Microsoft 用户辅助平台团队开发的基于 XML 的标记语言，用于为 Windows Vista 提供用户辅助。MAML 背后的思想与 DocBook 相似（我不知道哪个更好）。

MAML 由几种不同的内容类型组成，每种类型都针对一种文档类型。MAML 内容类型包括：概念、术语表、过程或操作指南、参考、故障排除等。

“概念帮助”这个术语实际上是不恰当的，因为“概念内容”只是 MAML 定义的内容类型之一。

MAML 规范目前不可用，但 Sandcastle 团队为开发人员提供了派生版本的模式。该模式目前不完整，这增加了我之前提到的“免费”成本。

下面显示了概念内容类型的模式，它是所有内容类型中最通用的。

以下是概念帮助结构的示例（实际情况与模式不同，这表明模式不完整）。

<?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>

重要提示

关于此和其他内容结构，必须注意以下几点：

<title> 标签实际上对于成功编译帮助是必需的，即使它没有包含在模式中。
<topic> 的 ID 必须是 GUID，唯一标识帮助系统中的每个文档。
包含每个文档的文件名称必须与 <topic> 的 ID 值相同。

最后，好消息是：Sandcastle 团队提供了工具，可以将各种内容类型转换为 HtmlHelp 1.x 和 2.x，用于支持的演示样式，并且转换的完整性和准确性程度各不相同。上面显示了使用 VS-2005 演示样式（支持最好的样式）的典型输出。

下载中包含什么？

帮助生成器库
这是一个易于使用的库，可以帮助您专注于内容类型，而不是如何构建帮助文件。
1. 它将创建您的文件副本，并将 GUID 名称从 topic ID 提取到 Sandcastle 配置文件所需的目录中。
2. 它将创建各种文件，包括目录。
3. 它将帮助您编译文件并记录输出。
模式文档
即使 MAML 文档也很完善。Sandcastle 的 2007 年 10 月 CTP 版本中包含的版本不完整，这使得提取文档变得困难。我已经设法提取了所提供模式的文档，虽然不太漂亮，但很有用。它被命名为Maml.chm，位于Builder文件夹中。
快速入门示例
教程中介绍的示例源，用 C# 和 VB.NET 编写。
（这个）示例
1. 这不仅仅是另一个例子，而是主要的东西，也是我真正想让您拥有的。
2. 它是一个说明性示例，向您展示了 Sandcastle 的用途，然后您可以查看源文件以了解它是如何实现的。
3. 它旨在成为一本指南、一本教程和一本食谱！事实上，本文就是从它中提取的。
4. 名为Manual.chm的输出副本位于Builder文件夹中，这与您编译和运行此示例将得到的结果相同。输出的屏幕截图如上所示。

现在，让我们转到教程或快速入门部分，开始一些实际工作。

教程

本节介绍简单的步骤，以帮助您开始使用提供的生成器库。我们将创建一个简单的帮助文件，该文件将显示“Hello, World”的概念帮助。

输出将如下图所示：

重要提示

该库适用于 .NET 2.x 或更高版本，并且使用它需要 VS.NET 2005。使用 VS.NET 是为了方便您编辑概念帮助编译器所需的 XML 文件。

创建内容

启动您的 VS.NET 2005（或更高版本），然后创建 C# 或 VB.NET 的新控制台应用程序。
我们需要添加对生成器库的引用，以简化构建过程。找到您下载并解压缩本文随附的源文件的位置。用于简化构建过程的概念帮助生成器位于Builder文件夹中。在Builder文件夹中，有一个名为Conceptual.Builder.dll的Output子目录，其中包含生成器库。在您新创建的控制台项目中添加对此库的引用。
同样，从Builder文件夹中，将配置文件Project.config和批处理文件Project.bat复制到您的项目目录并添加到您的项目中。
注意：Project.config和Project.bat文件的内容可以自动生成，并且将在后续文章中完成。然而，在本文中，我们提供了它们，以便您可以修改它们并控制构建过程。
现在，在 IDE 中右键单击项目，然后添加两个文件夹，分别命名为Documents和Media。
注意：本教程不需要Media文件夹及其内容（稍后添加），但“固定”的配置文件需要它。

我们现在已经准备好了项目，并准备添加定义文档结构所需的内容。

创建内容

我们需要添加一个概念文档文件。右键单击“Documents”文件夹，选择添加，然后选择新建项…。在显示的对话框中，选择XML 文件，然后将其命名为Document.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>

注意：<topic> 标签的“id”属性必须是 GUID，您可以创建一个新的，也可以只使用演示中提供的。

同样，将MediaContent.xml添加到Media文件夹，并将其内容修改为以下内容……

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

最后，让我们构建一个目录。将Project.xml文件添加到项目中，并将内容更改为以下内容……
```
<?xml version="1.0" encoding="utf-8"?>
<files>
    <file name="Document.xml"/>
</files>
```

按照相同的步骤将更多文档文件添加到项目中。

我们现在已经定义了文档结构，并准备配置构建过程；这就是 Builder 库的用武之地。

使用生成器库

添加到本文的生成器库将用于编译帮助文件，我们需要对其进行配置。打开 C# 项目的Program.cs文件，或 VB.NET 项目的Module1.vb文件。
导入 Conceptual.Builder 命名空间，并将Program.cs文件的内容更改为下面的代码部分所示。

以下 C# 和 VB.NET 代码说明了如何使用 Builder 库创建、初始化和编译帮助文件。

C# 代码

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 代码

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

C# 和 VB.NET 代码均取自可工作的示例。代码和本文档中概述的所有步骤都包含在QuickStartCS和QuickStartVB示例中。

编译代码

不需要特殊的生成或编译说明，只需编译 Builder 库（如果需要）和您的项目。然后，运行项目；如果一切顺利，编译后的帮助文件将自动显示。输出位于Help子文件夹中。

有用链接

在此处下载 Sandcastle 2007 年 10 月 CTP …。
Sandcastle Wiki
Sandcastle 博客
Microsoft Developer Documentation and Help System 论坛

Sandcastle 相关文章

历史

2007 年 12 月 30 日 - 初始发布 - 版本号 0.1。
2007 年 12 月 31 日 - 修复了格式。

Sandcastle 概念帮助： 快速入门

引言

什么是概念帮助？

重要提示

下载中包含什么？

教程

重要提示

创建内容

创建内容

使用生成器库

C# 代码

VB.NET 代码

编译代码

有用链接

历史

Sandcastle 概念帮助：快速入门