.NET中XML 注释 SandCastle 帮助文件.hhp 使用HTML Help Workshop生成CHM文件
一.摘要
在本系列的第一篇文章介绍了.NET中XML注释的用途, 本篇文章将讲解如何使用XML注释生成与MSDN一样的帮助文件.主要介绍NDoc的继承者:SandCastle.
.SandCastle简介
在上一篇文章中的帮助文件截图都是使用SandCastle生成的,比如下面的截图:
SandCastle是一个微软发布的工具,它通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。 这个工具的源代码可以在CodePlex中以微软公开许可协议(Microsoft Public License)下获得。SandCastle 主要特性有:
- 兼容署名或未署名的注释
- 支持范型以及.NET 2.0框架
- 支持所有的.NET语言
- 支持.NET Compact Framework 项目
- 简单编译接口和Visual Studio插件
四.SandCastle工作原理
从CodePlex上下载SandCastle的源代码,打开后会找到如下项目:
有关这几个项目的关系可以用下图表示:
上图中各部分的作用:
- SandCastle中主要有三个组件:MrefBuilder、Build Assembler和XslTransform。
- HTML Help 1.x compiler(hhc.exe) 或者 Microsoft Help 2.0 compiler(hxcomp.exe) 用来生成 .chm 或者 .hxs 文件
- Help Viewer 用于查看帮助文件.
MrefBuilder和XslTransform
MrefBuilder使用CCI从程序集中生成输出文件
XslTransform使用上面输出的文件生成 Reflection.xml 文档和Manifest文件.其中Reflection.xml包含所有无表现元素的数据.
BuildAssembler
Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释(保存在独立的XML文件中),生成按逻辑分组的HTML文件。
HTML Help Compiler(1.x , 2.0 ) 再利用这些HTML文件生成最终结果。
除了上面介绍的核心的三个组件,还有一些用于生成最终文件的工具.比如 HTML Help Complier 这个角色是使用HTML Help Workshop工具完成的.HTML Help Workshop并不在SandCastle项目中,需要单独下载.要生成最终的.chm格式的文档,必须安装HTML Help Workshop.
我们注意到源代码中有一个ChmBuilder, 它的作用是生成可以供HTML Help Workshop使用的.hhc一类的文件,这些文件都是.chm格式文件的元数据.HTML Help Workshop的作用就是根据这些文件生成最终文档.
五.快速上手SandCastle
本篇文章只从我所掌握的知识上,讲解如何快速简单的使用SandCastle.方法可能有些繁琐.要想如鱼得水的使用它现在看来必须要使用第三方开发的SandCastle辅助工具.在本系列以后的文章中我会抽出时间进行研究.
(1)准备软件
首先需要我们准备如下软件:
SandCastle, 下载地址:http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx
说明:上面的连接会链接到CodePlex上的SandCastle项目的最新Release版本.其中页面上会有如下图两种下载方式:
请下载SandCastle.msi文件,这里包含我们即将使用的一些比如GUI工具等.而下面的源代码zip中则不包含,从大小也能看出来.知道如何使用SVN和TFS的用户也可以从源代码服务器上获取最新的开发中的SandCastle版本,我获取了其SVN上的版本,获取后也包括全部内容和工具.
HTML Help Workshop,下载地址:
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en
(2)准备项目文件
准备好程序的dll文件和注释的xml文件.比如本文实例的两个文件:XmlCommentClassDemo.dll 和 XmlCommentClassDemo.XML
注意如果我们的项目关联多个dll,则需要将相关的项目的dll和注释xml文件都准备好.否则的话在帮助文件中将不能点击相关的类.(如果添加了一个类所在的项目dll和xml文件,则此类在chm文件中可以被点击,点击后跳转到此类的说明页面.)
(3)使用GUI生成帮助文件元数据
安装完SandCastle后,会在其generic目录中找到GUI工具:SandcastleGui.exe,运行界面如图:
如上图所示,在Name处输入"XmlCommentDemo"后,点击Build,首先会提示保存一个sproj文件.
默认会在创建文件夹: C:\Program Files\Sandcastle\\Examples\XmlCommentDemo
经过SandCastle我们已经生成了chm文件的元数据文件,路径保存在:
C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中.
(4)使用HTML Help Workshop生成CHM文件
在C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中有这三个文件:
XmlCommentDemo.hhc
XmlCommentDemo.hhk
XmlCommentDemo.hhp
运行HTML Help Workshop,可以打开XmlCommentDemo.hhp文件.单开文件后,单击"File"->"Compile...",弹出如下图的界面:
单击"Compile",则会在.hhp的目录下生成.chm文件,如下图所示:
XmlCommentDemo.chm就是最终文档.
五.总结
经过本篇文章的介绍将使用.NET注释的XML格式文件和程序的DLL文件,生成类似MSDN的文档.对于注释在帮助文档中的作用,请查看本系列的第一篇文章.
由于研究有限我目前也只能粗略的使用SandCastle,后续文章中将陆续深入的学习SandCastle的使用.希望大家能够一起讨论,一起研究,一起进步.
六.相关资源
微软SandCastle博客: http://blogs.msdn.com/sandcastle/default.aspx
SandCastle项目:http://www.codeplex.com/Sandcastle
原文链接:http://www.cnblogs.com/zhangziqiu/archive/2009/01/31/XmlComment-SandCastle-1.html
.NET中XML 注释 SandCastle 帮助文件.hhp 使用HTML Help Workshop生成CHM文件的更多相关文章
- 使用Teleport Ultra批量克隆网站,使用Easy CHM合并生成chm文件
1.要下载的页面 http://www.howsoftworks.net/javaapi/ 2. 下载Teleport Ultra 3.使用Teleport Ultra批量克隆网站 4.下载Easy ...
- 【Visual Studio】Visual C# 中XML注释的使用(含注释在开发时显示换行)
为函数方法注释说明要用到 xml 语句 <summary> 段落说明 </summary> .<para> 新段示例说明 </para>.<par ...
- django生成文件txt、pdf(在生成 PDF 文件之前,需要安装 ReportLab 库)
from django.http import HttpResponse def download_file(request): # Text file #response = HttpRespons ...
- c#创建目录和文件夹,数据写入并生成txt文件
c#创建目录: // 获取程序的基目录.System.AppDomain.CurrentDomain.BaseDirectory // 获取模块的完整路径.System.Diagnostics.Pro ...
- 使用.NET中的XML注释(二) -- 创建帮助文档入门篇
一.摘要 在本系列的第一篇文章介绍了.NET中XML注释的用途, 本篇文章将讲解如何使用XML注释生成与MSDN一样的帮助文件.主要介绍NDoc的继承者:SandCastle. 二.背景 要生成帮助文 ...
- C# 如何生成CHM帮助文件
原文:C# 如何生成CHM帮助文件 前一段时间应公司要求,让我开发一个数据库字段信息CHM帮助文件生成软件.结果当时我就二了,这个东西我只用过,不知道咋做啊.没想到老大很随意说一句:"没事, ...
- Java中的注释
代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下Javadoc注释规范以及楼主在J2EE ...
- hibernate自动生成映射文件
映射文件是O/R Mapping的关键,相当于控制中心.当数据库表较多时,手动配置该映射文件非常耗时.为了快速开发程序,使开发人员的注意力集中到业务逻辑上来,Hibernate官方提供的MiddleG ...
- C# 怎么生成DLL文件(转)
有两种方法: 但是一般这个使用 打开VS2008,依次点击:菜单->文件->新建项目->项目类型visual C#(这里假设为该项目所取的名字是DllBuild)-& ...
随机推荐
- maven学习(九)——maven中的坐标、依赖以及仓库
一.Maven坐标 1.1.什么是坐标? 在平面几何中坐标(x,y)可以标识平面中唯一的一点. 1.2.Maven坐标主要组成 groupId:组织标识(包名) artifactId:项目名称 ver ...
- PAT A+B格式
A + B格式(20) 时间限制 400毫秒 内存限制 65536 kB 代码长度限制 16000 B. 判断程序 标准 作者 陈,岳 计算a + b并以标准格式输出总和 - 即数字必须用逗号分隔成三 ...
- Python获取程序运行目录和脚本目录
Python获取程序运行目录和脚本目录 import os import sys #获取脚本所在目录 print os.path.split( os.path.realpath( sys.argv[0 ...
- 【CCF】 Markdown 模拟
#include<iostream> #include<cstdio> #include<string> #include<cstring> #incl ...
- ffmpeg nmb
搞了一个下午的raw bitstream封装无果然后转战mp4box一秒搞定了 优秀啊..
- 【14】redux 之 redux-actions
redux-actions有两大法宝createAction和handleActions. createAction http://www.jianshu.com/p/6ba5cd795077 原来创 ...
- div 的相对定位与绝对定位
网 上也有不少使用div + css进行布局的教程,却存在很多缺陷,一是对css的布局模型讲解不清楚,让人很难理解相对定位.浮动等概念:二是虽然避免了“表格套表格”的缺点,却 带来了“div 套 di ...
- bzoj 1396 识别子串 后缀树+线段树
题目大意 给定一个长度\(\le100000\)的字符串 求每一个位置的最短识别子串 对于位置\(x\),能识别子串\(s[i...j]\)的条件是 1.\(i\le x \le j\) 2.\(s[ ...
- ThickBox弹出框的使用方法
原文发布时间为:2009-08-22 -- 来源于本人的百度文章 [由搬家工具导入] 请访问:http://www.blueidea.com/articleimg/2007/12/5182/tickb ...
- 【Visual Studio】error c4996: 'fopen': This function or variable may be unsafe(转)
原文转自 http://blog.csdn.net/zhangyuehuan/article/details/12012635 [解决方案]项目 =>属性 =>c/c++ =>预处 ...