dita文档_使用DITADoclet和DITA API专业化生成DITA Java™API参考文档

2009年12月11日修订说明：在“ 目标”和“ 安装org.dita.dost插件 ”标题下为“可下载资源”添加了两个链接。

2014年3月7日，修订说明：在参考资料中删除了过时的“ IBM XML认证”链接。

2014年3月17日修订说明：删除了参考资料中过时的“ DITA FAQ”链接。

目标

在本文中，您将学习如何使用DITADoclet，DITA Java API专业化和Eclipse IDE来创建Java API参考文档，以便于以多种格式轻松分发。 DITADoclet生成DITA Java API文件，自动为Java API参考文档创建DITAMAP和MAPLIST文件（DITA Java API专业化），从Java源代码中提取开发人员注释，并将信息迁移到生成的DITA API文件中。

常用缩略语

• API：应用程序编程接口
• CHM：编译的Windows®HTML帮助
• CSS：级联样式表
• DITA：达尔文信息键入体系结构
• DTD：文档类型定义
• HTML：超文本标记语言
• IDE：集成开发环境
• J2EE：Java 2平台企业版
• JDK：Java开发套件
• JSP：Java服务器页面
• URI：统一资源标识符
• XHTML：可扩展超文本标记语言
• XML：可扩展标记语言
• XSLT：可扩展样式表语言转换

通常，Sun Microsystems的Javadoc工具用于从Java源代码生成Java API参考文档。 Javadoc工具生成Java API参考文档的基本结构，但是该文档通常不完整，并且仅限于开发人员注释。 开发团队的变更似乎鼓励从Java API参考文档过程中完全删除API编写者和编辑者。 开发人员有时间只管理带有不完整注释的Java源代码文件。 这种情况清楚地向API编写者和其他对产生高质量API文档感兴趣的人提出了一些挑战。

DITADoclet和DITA Java API解决方案为API编写者提供了生成完整记录的Java API的工具。 完整记录的API有多种用途，但是最重要的原因是允许API用户完全理解，搜索和浏览他们可用的API函数。 为了完全使用API​​的功能，软件用户需要一个准确且完整记录的API。

为了了解DITADoclet的工作原理，本文还介绍了Javadoc标准doclet解决方案使用的一些重要概念。 为了使DITADoclet自动提取有效地工作，必须根据Javadoc严格准则记录Java源代码。 否则，当您使用DITADoclet提取注释时，注释可能无法正确处理，或者生成的API文档可能不完整。

本文介绍以下内容：

• 先决条件
• 什么是DITA Java API专业化？
• DITADoclet安装
• 使用Eclipse Javadoc Generation向导（标准Doclet）创建Javadoc文档
• 使用以下方法创建Java API参考文档：
  • Eclipse Javadoc生成向导（DITADoclet）
  • 命令提示符
• DITADoclet的优缺点

请参阅可下载资源以下载DITADoclet。

要了解有关DITA的更多信息，如何创建或编辑DITA文件以及查找更多支持DITA的XML编辑器，请访问http://dita.xml.org网站。 我强烈建议您使用XML编辑器以避免标记错误。 提供了许多不同的XML编辑器：Arbortext Editor™，<oXygen />®XML编辑器，XMLBuddy™（Eclipse插件），Altova®XMLSpy®，OpenOffice.org等。 我建议使用Arbortext Editor作为内容发布系统。

听众

本材料适用于API编写者，并假定您熟悉Java软件，Java API引用文档结构，Javadoc生成，并且作为API编写者，您想了解更多有关如何提供改进的Java API引用文档的信息。

API编写者应理解开发人员编写的代码，并提取要在API文档中发布的相关信息。 使用DITADoclet生成DITA Java API文档所获得的成功取决于您对Java源代码的熟悉程度。

先决条件

本文介绍了直接从Java源代码生成Java API参考DITA文件所需的先决条件，以及如何使用Eclipse转换文件。 在使用DITADoclet和DITA Java API专业化之前，您需要熟悉以下概念：

• Java API参考文档过程和Javadoc生成
• 蚀
  • Java IDE和编辑器的观点和观点
  • Eclipse基本概念，例如体系结构，插件和插入工作台
  • 最小插件的元素，例如项目，Eclipse视图和编辑器
  • 如何使用Eclipse Java IDE创建，安装和运行简单的插件
• Eclipse是基​​本的IDE，但是有许多与Java相关的Eclipse插件，以及在Eclipse之上构建的几种商业IDE：
  • Rational®Software Architect是一个全面的集成开发环境，用于可视化地设计，构建，测试，分析和部署应用程序
  • Rational Application Developer for WebSphere Software通过可视化开发功能扩展了Eclipse
  • IBM®WebSphere®Studio是来自IBM的功能强大且流行的J2EE IDE
  • 用于Java的IBM WebSphere Studio Site Developer是用于Windows和Linux的Java IDE
  • Sun Java Studio Creator
  • JBuilder的

要下载这些插件，请参阅参考资料 。 我建议使用Eclipse构建工具或直接从命令提示符行运行DITADoclet。

什么是DITA Java API专业化？

如果您熟悉DITA，则可以跳过此说明并转到下面的DITADoclet安装 。

DITA强制执行一致，完整和正确的技术文档。 DITA API专业化表示产生Java API文档文件的DITA主题类型的包。 DITADoclet直接从Java源代码生成DITA文件。 您可以从命令提示符或使用Eclipse运行它。

达尔文信息键入架构（DITA）

维基百科上提到的DITA的简要历史

• 2001年3月：IBM推出了DITA
• 2002年5月：将领域专业化添加到主题专业化
• 2004年4月：成立了OASIS DITA技术委员会
• 2005年2月：SourceForge开始支持DITA Open Toolkit
• 2005年6月：DITA v1.0被批准为OASIS标准
• 2005年8月：DITA Open Toolkit v1.1发布了
• 2006年3月：OASIS启动DITA.XML.org
• 2007年8月：DITA V1.1已获得OASIS的批准，包括Bookmap专业化认证

DITA代表一种开放的，OASIS标准，基于XML的体系结构，用于创作，生成和交付技术信息。 尽管您可以在任何文本编辑器中编辑DITA文件，但是XML编辑器使您可以轻松插入和修改标签，同时符合DITA DTD和模式。 我确实建议您使用XML编辑器来消除标记中的错误。 可用的XML编辑器包括Arbortext编辑器，oXygen，XML Buddy（Eclipse插件），Altova XML Spy等。

要了解更多关于DITA以及如何创建或编辑DITA文件，寻找更多的XML编辑器，支持DITA，请参阅链接到DITA组织网站相关主题 。

DITA开放平台是免费软件，您可以根据自由软件基金会发布的GNU通用公共许可的条款进行重新分发和修改。 发行DITA开放平台是希望它会有用，但没有任何保证。 请参阅相关主题的更多细节。

DITA API专业化

DITA API专业化文档通过用于通用（所有编程语言）和Java编程语言的DTD元素描述了基于XML的DITA架构。 DITA API专长包括主题类型和元素，用于记录通用和Java API参考。 每个特定于语言的DITA API专长都包含模块。 模块是为特定任务（例如描述API包或类）设计的主题类型。 每个模块都包含适当的XML元素，以描述编程语言的特定部分。

在本文中，您将学习如何运行DITADoclet来生成DITA Java API参考文件，以及如何使用DITA Java API解决方案来记录引用。

您可以使用DITA通用API专长来创作和生成Java，Visual Basic和其他编程语言的API参考文档。

DITADoclet安装

要运行DITADoclet，您需要安装Java开发工具包（JDK）和Eclipse。

安装JDK

• 如果系统路径中不包含Java二进制文件，或者未定义JAVA_HOME环境变量，则运行此工具可能会失败。 您需要JDK来运行DITADoclet。
• 建议使用Java 5 JDK。 通常，Java安装的路径类似于C：\ Program Files \ Java \ jdk1.5.0_06 \。 要确定系统上已安装的Java版本，请在命令提示符下键入： Java -version
• 如果您的Java版本不是最新，下载JDK，J2RE或JRE从Sun下载站点（请参阅相关信息的链接。）

安装Eclipse Classic

• 下载适用于Windows的Eclipse Classic，IBM Rational Developer或Rational Software Architect Standard Edition，然后将zip文件解压缩到您选择的目录中（例如，在Windows上为C：\ eclipse \）。 请参阅相关主题的链接。
• 最重要的是确保Eclipse安装路径在Windows平台上不包含任何空格。 有关不同工具安装的更多详细信息，请参考官方Eclipse文档。 要检查您是否安装了Javadoc工具，请打开命令提示符并键入Javadoc 。 如果收到错误，则说明您没有Javadoc（jdk1.5.0_xx），并且需要从Sun站点下载jdk1.5.0_xx，并将目录添加到Windows路径：C：\ Program Files \ Java \ jdk1.5.0_xx。

安装DITADoclet

• 下载DITADoclet工具zip文件并将其解压缩到您选择的目录中（例如，在Windows上为C：\ DITA \）。 它将创建一个目录\ DITA，其中包含DITADoclet.exe，ReadeMe.txt和一个\ demo子目录。
  • \ demo子目录包含\ src资源目录，选项和软件包。
  • \ src资源目录包含您将用作示例的Java源文件。 您可以直接从SourceForge网站下载源文件（DITA-OT1.4_src.zip）。

安装org.dita.dost插件

1. 查找您的Eclipse版本使用的工作空间目录。 通常，它位于名为\ workspace的目录中，该目录是在子目录中安装Eclipse的。 如果使用快捷方式或脚本来启动Eclipse，则它将位于该快捷方式或脚本的当前工作目录下的子目录\ workspace（例如，C：\ eclipse \ workspace）中。
2. 下载org.dita.dost zip文件（请参阅可下载的资源 ），并将其解压缩到Eclipse工作区目录中。 这将创建一个名为org.dita.dost的Java项目。
3. 将Java项目org.dita.dost导入到Eclipse工作区中。

可选的安装步骤

后续步骤是可选的，我无意在这里解释这些步骤。 要完成并测试您的DITA API文件，您需要将.dita文件转换为.xhtml文件。 您可以使用DITA Open Toolkit转换DITA Java API文件或从DITA API文件生成输出。 您需要同时安装apiref和javaapiref插件，变压器才能工作。

1. 可选：下载并安装DITA Open Toolkit。
2. 可选：下载并安装DITA Java API专业化版本（apiref-0.8和avaapiref-0.8）。

使用标准Doclet创建Javadoc文档（Eclipse Javadoc生成向导）

要了解DITADoclet的基本角色和结构，简要回顾一下Javadoc工具非常有用。 JDK文档提供了Javadoc工具选项的详细说明。 如果您熟悉Javadoc工具，则可以立即使用DI