简介
在这篇文章中,我们将目前的概念有助于在2007年10月CTP发布的Sandcastle的帮助编译器系统推出。
Sandcastle的建设的基础上。NET中的XML - DOC格式的源代码API参考提供的支持以前的版本。虽然这可能是有用的,在大多数情况下,一个完整的软件文档将包括两部分:API参考文档,以及quot;用户Manualquot;虽然有些软件提供了在Microsoft Word或Adobe PDF格式的,我们最喜欢的HTML格式的手册。在HTML格式的,我们喜欢一个外观类似的API参考文档。很多企业现在只提供在线帮助系统,不仅是方便,更实用,节省成本,但它也使我们的戈尔高兴!
现在,与2007年10月CTP发布,即使是最贫穷的独立软件开发商可以在他们可以负担得起的价格生产专业documentations - 免费。好了,"freequot;本身的价格,在这种情况下,一个非常昂贵的。在Sandcastle的概念帮助支持,没有一个文档(文档管理是没有记录),因此很难对当前Sandcastle的GUI商融入自己的工具。
这篇文章,因此,旨在提供以下:为帮助作者
减少quot; freequot;学习使用概念的帮助,使许多可以探讨这一有用的工具的潜力成本。对于(GUI)工具作者
提供的信息,以帮助整合新的和现有工具的概念帮助支持。
基本上,我想与你我共享,目前,在我试图去学习和掌握Sandcastle的概念帮助支持。我会发布了一系列关于这个的文章,但提供的所有工具和设施,在附带的下载文件,让你不会有工作,我的步伐。
在这篇文章中,我将目前都介绍你和你可以开始快速启动。这也将有助于我在下一篇文章中收集的信息。
现在,这些新的沙堡的概念帮助,让我给一个quot; freequot;一个典型的输出,这实际上是下载文件的一部分的屏幕截图。
{S0}什么是概念上的帮助?
概念是指有关概念或概念的形成,帮助这样一个概念,是一个文档的概念,或您的软件程序将如何帮助实现一些概念或想法。嗯,这是我尝试的技术,相信我,这是不准确的。准确的版本如下... ...
的概念帮助是基于微软协助标记语言或MAML,由微软用户援助平台团队为Windows Vista用户援助开发一个基于XML的标记语言。 MAML背后的想法是类似的DocBook(我不知道哪个更好)。
MAML由几个不同的内容类型,每一个特定的文档类型。 MAML内容类型包括:概念,术语,程序或如何做,参考,故障排除等
长期quot;概念helpquot;实际上是出自quot;概念contentquot; MAML定义的内容类型之一。
MAML规范是目前无法使用,但Sandcastle的团队提供了一个衍生版本为开发模式。架构目前是不完整的,这是添加到quot; freequot;成本我前面提到的。
概念的内容类型的模式,这是最通用的所有内容类型,如下所示:
下面是一个结构(现实的情况是不同的模式,表明一个不完整的架构)的概念帮助的例子:
重要注意事项
<?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>
以下必须指出关于这个问题和其他内容结构:LT; titlegt标签实际上是一个编译成功的帮助,甚至认为不包括架构。LT; topicgt的ID必须是一个GUID,在帮助系统中唯一标识每个文档。包含每个文件的文件必须命名为LT; topicgt的ID值。
最后,一个好消息:Sandcastle的团队提供的工具进行改造,与不同程度的完成和准确性,各种内容类型为表示支持的样式都HTMLHELP 1.x和2.x。典型的输出使用的VS - 2005年的演讲风格,这是最好的支持风格,如上图所示。
包含在下载是什么呢?帮助Builder库
这是一个易于使用的库,这将有助于你集中精力,而不是如何建立你的帮助文件的内容类型。这将创建与Sandcastle的配置文件所需要的目录中的主题ID中提取的GUID名称的文件的副本。这将创建的各种文件,包括表的内容。这将帮助您编译的文件和日志输出。架构Documentations
MAML即使是良好的记录。在2007年10月CTP版的Sandcastle的版本是不完整的,使其难以提取的文档。我已成功地提取文档中所提供的架构,而不是很漂亮,但很有用。它被命名Maml.chm在Builder文件夹中。快速入门示例
样品来源,在C#和VB.NET的教程,介绍如下。()样品这是不是只是另一个例子,但最主要的,我真的希望你有什么。这是一个例证表明您与Sandcastle的你可以做什么,然后你看看源代码,看看它是怎么做。它的目的是一个指南,教程,和食谱!事实上,这篇文章是从中提取。一个名为Manual.chm输出的副本位于Builder文件夹,你会得到同样的事情,如果你编译并运行此示例。以上显示的是输出的截图。
现在,让我们继续前进的教程或快速启动部分开始一些实实在在的工作。本教程
本节介绍简单的步骤,以帮助您开始使用所提供的Builder库。我们将创建一个简单的帮助文件,将显示quot概念帮助相当于你好,Worldquot;
输出将如下所示:
{S2}重要注意事项
库。NET 2.x或更高版本,并使用它需要VS.NET 2005年。正在使用VS.NET,让您可以轻松编辑您的概念帮助编译器所需的XML文件。创建内容启动您的VS.NET 2005(或更高),并创建一个新的控制台应用程序,在C#或VB.NET。我们需要添加的引用Builder库,以简化构建过程。找到你下载并解压缩本文附带的源。位于Builder文件夹的概念帮助建设者,以简化构建过程。在Builder文件夹中,有一个输出子目录包含Builder库,名为Conceptual.Builder.dll。添加到该库在新创建的控制台项目的参考。
从Builder文件夹中,复制的配置文件,Project.config到项目目录和批处理文件,Project.bat,并把它们添加到您的项目。
注意:Project.config Project.bat文件的内容可以自动生成,将在以后的文章。然而,在这篇文章中,它是提供这样您就可以对其进行修改和控制生成过程。现在,右键单击IDE中的项目,并添加两个文件夹,命名文件和媒体。
注:媒体文件夹及其内容(稍后添加)不是本教程所需要的,但"; fixedquot;配置文件需要它。
我们现在已经准备的项目,并准备添加需要定义我们的文档结构的内容。创建内容我们需要添加一个概念性的文档文件。 "; Documentsquot;文件夹上右击,选择添加,然后新项目... ...从显示的对话框中,选择"XML文件",并给它的名称document.xml中(本教程,但它可以是任何东西)。更改这个文件的内容看起来像这样... ...{C}
注:quot; idquot的LT topicgt;属性标签必须是一个GUID,你可以创建一个新的或刚使用提供的演示。
同样,MediaContent.xml添加到Media文件夹,并修改的内容为以下...
最后,让我们建立一个表的内容。 project.xml文件添加到项目和改变以下内容... ...
<?xml version="1.0" encoding="utf-8"?>
<stockSharedContentDefinitions fileAssetGuid="" assetTypeId="">
</stockSharedContentDefinitions>
<?xml version="1.0" encoding="utf-8"?>
<files>
<file name="Document.xml"/>
</files>
按照同样的步骤,添加更多的文件文件添加到项目。
我们现在定义文档结构和准备配置构建过程,这是Builder库的用武之地。使用Builder库Builder库添加到本文章将用于编译的帮助文件,我们需要配置它。打开一个C#项目,或为VB.NET项目的Module1.vb你的Program.cs。导入Conceptual.Builder命名空间,并在下面的代码段显示,改变Program.cs文件中的内容。
下面的C#和VB.NET代码演示了如何创建,初始化,使用Builder库和编译帮助文件:C#代码
VB.NET代码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());
}
}
}
}
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库(如有必要)和你的项目。然后,运行该项目,如果一切顺利成功,编译的帮助文件会自动显示。输出位于"帮助"子文件夹。有用的链接下载Sandcastle的2007年10月CTP {A}。
Sandcastle的相关文章:{A6}历史2007年12月30日 - 初始版本 - 0.1版说。
2007年12月31日 - 固定格式。