當前位置：首頁 > 编程语言 > java >内容正文

java

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

發布時間：2024/3/26 java 46 豆豆

生活随笔收集整理的這篇文章主要介紹了 dita文档_使用DITADoclet和DITA API专业化生成DITA Java™API参考文档小編覺得挺不錯的,現在分享給大家,幫大家做個參考.

dita文檔

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插件

查找您的Eclipse版本使用的工作空間目錄。通常，它位于名為\ workspace的目錄中，該目錄是在子目錄中安裝Eclipse的。如果使用快捷方式或腳本來啟動Eclipse，則它將位于該快捷方式或腳本的當前工作目錄下的子目錄\ workspace（例如，C：\ eclipse \ workspace）中。

下載org.dita.dost zip文件（請參閱可下載的資源），并將其解壓縮到Eclipse工作區目錄中。這將創建一個名為org.dita.dost的Java項目。

將Java項目org.dita.dost導入到Eclipse工作區中。

可選的安裝步驟

后續步驟是可選的，我無意在這里解釋這些步驟。要完成并測試您的DITA API文件，您需要將.dita文件轉換為.xhtml文件。您可以使用DITA Open Toolkit轉換DITA Java API文件或從DITA API文件生成輸出。您需要同時安裝apiref和javaapiref插件，變壓器才能工作。

可選：下載并安裝DITA Open Toolkit。

可選：下載并安裝DITA Java API專業化版本（apiref-0.8和avaapiref-0.8）。

使用標準Doclet創建Javadoc文檔（Eclipse Javadoc生成向導）

要了解DITADoclet的基本角色和結構，簡要回顧一下Javadoc工具非常有用。 JDK文檔提供了Javadoc工具選項的詳細說明。如果您熟悉Javadoc工具，則可以立即使用DITADoclet。 Javadoc工具（或DITADoclet）解析源文件，提取Javadoc注釋，并建立文檔數據的內部集合。

以下步驟顯示了如何使用標準Javadoc Doclet在Eclipse開發環境中生成Javadoc。

您將使用Eclipse插件之一org.dita.dost來說明該過程。

在Eclipse的Package Explorer視圖的左窗格中，選擇需要為其生成Javadoc的Java源代碼（在本示例中，您使用Eclipse插件之一org.dita.dost。）右鍵單擊在org.dita.dost上 ，然后從下拉列表中選擇導出。將打開“導出”窗口。

選擇Javadoc ，然后單擊下一步 。將打開“生成Javadoc”窗口。

在“ Javadoc命令：配置”窗口中，選擇Javadoc.exe 。通常，Javadoc.exe具有類似C：\ Program Files \ Java \ jdk1.5.0_06 \ bin \ Javadoc.exe的路徑（請參見圖1 ）。

圖1.選擇javadoc.exe路徑

在“生成Javadoc”窗口中，選擇要導出到Javadoc文件的軟件包。該列表由Eclipse工作臺選擇初始化。您只能選擇一個項目，因為在運行Javadoc工具時一次只能使用一個項目類路徑。

要過濾包的成員，請選擇可見性（通常將選擇Public 。）

選擇為： -package，-private，-protected或-public ，如圖2所示。
圖2.選擇成員可見性
表1說明了根據所需可見性選擇的成員。 -public選擇最少的成員， -private選擇最多的成員。

表1.成員可見性

選項記錄這些類

-上市	上市	。	。	。
受保護	上市	受保護的	。	。
-包	上市	受保護的	（包）	。
-私人的	上市	受保護的	（包）	私人的

選擇“ 使用標準Doclet”以標準doclet啟動Javadoc命令（默認）。

目標：選擇標準doclet將生成的文檔寫入的目標。目標是特定于doclet的標準參數，因此在使用自定義doclet時未啟用。標準doclet將寫入的目標可以是例如工作空間子目錄\ workspace \ doc.dita.dost \ output。

單擊“ 下一步”指定其他Javadoc生成選項。

取消選擇Overview ，如圖3所示。如果選中，則此選項指定Javadoc應該從指定的源文件中檢索概述文檔的文本，并將其放在“概述”頁面（index.html）上。

圖3.概述頁面位置

單擊“ 下一步”指定其他Javadoc生成選項。

指定要放置在index.html文件頂部附近的標題。如果未選擇并指定文檔標題，則Javadoc工具不會將其添加到“概述”頁面。

圖4.指定文檔標題

其他Javadoc選項

您可能需要添加更多Javadoc選項，以便Javadoc工具進行處理。這些采用VM optioens的形式， VM optioens是用于控制Javadoc工具處理的系統選項。例如，設置-Xmx512m將為堆分配512 Mb。

為了加快JavaDoc的處理過程并關閉Javadoc中的所有參考消息，我建議使用-quiet選項來幫助創建Javadoc注釋。（提示： -verbose是您可以使用的另一個選項。- verbose選項使編譯器和Javadoc打印出有關正在編譯哪些源文件以及正在記錄哪些類文件的消息。）

圖5.指定VM選項和Javadoc選項

doclet在工作空間子目錄\ workspace \ org.dita.dost \ output \中為插件文檔生成輸出HTML文件，這是您的插件文檔目錄。

單擊完成以生成Javadoc文檔。您可以使用控制臺視圖觀察JavaDoc生成的進度。

Javadoc從Java源文件獲取所有信息和文本，但有兩個例外：概述文本文件和每個包的文本文件。兩種例外都是可選的。 Javadoc創建的文件分別是index.html和package-summary.html。當您使用標準Javadoc時，生成的概述和程序包文件是HTML文件，沒有任何信息。軟件包文檔為開發人員提供了有關使用軟件包的必要信息。軟件包信息對于理解事物如何協同工作很有用，并且可能包括代碼，原型，結構圖，設計模式，編碼標準等。如果選擇在瀏覽器中打開索引文件的選項，則在生成Javadoc之后，您會發現在默認的Web瀏覽器中打開的Javadoc頁面index.html。

既然您已經回顧了Javadoc如何生成Java API參考文件，那么看看DITADoclet如何為Java API參考文檔生成DITA文件。在下一節中，您將看到如何使用Eclipse Javadoc生成向導（DITADoclet）創建Java API參考文檔。

使用DITADoclet創建Java API參考文檔（Eclipse Javadoc生成向導）

DITADoclet解析源文件，提取Javadoc注釋，并直接從Java API源代碼文件構建DITA文件。此設計的目的是使API技術編寫者可以輕松利用他們現有的Eclipse Javadoc Generation向導知識，并且僅需學習很少的DITA文檔特定差異：

DITADoclet生成的文檔的總體結構與標準Doclet生成的文檔相同。
DITADoclet支持標準Doclet提供的所有選項，但僅考慮以下選項： -sourcepath，-d，-doctitle，-overview和-public 。
DITADoclet還支持您可以使用的其他幾個選項： -contributor，-provider，-debug和-nocomment 。
標準doclet通過使用標簽來處理自定義塊標簽，而DITADoclet則不。

以下步驟顯示了如何在Eclipse開發環境中將定制的doclet DITADoclet與Javadoc結合使用：

在Eclipse的左窗格中，選擇org.dita.dost ，您將為其生成Javadoc的源代碼插件。

右鍵單擊所選插件，然后從下拉列表中選擇“ 導出” 。將打開“導出”窗口。

選擇Javadoc ，然后單擊下一步 。將打開“生成Javadoc”窗口。

圖6. Javadoc生成向導（Standard Doclet）打開了Generate Javadoc窗口

在Javadoc命令字段中，指定DITADoclet.exe的路徑。安裝DITADoclet時，它可能已安裝在C：\ DITA \ DITADoclet.exe。

在“ 生成Javadoc”窗口中，選擇要導出到Javadoc文件的軟件包。該列表由Eclipse工作臺初始化。您只能選擇一個項目，因為在運行Javadoc工具時一次只能使用一個項目類路徑。選擇示例項目org.dida.dost 。

由于此版本的DITA Java API專業化版本僅支持Java公共元素，因此請選擇具有可見性Public的成員。

選擇“ 使用標準Doclet”以標準doclet啟動Javadoc命令（默認）。

指定標準doclet將生成的文檔寫入的目標位置。（該目標是特定于doclet的標準參數，因此在使用自定義doclet時未啟用。）標準doclet寫入的目標可以是，例如，工作空間子目錄，指定為.. \ workspace \ doc。 dita.dost \ topics 。

對于“基本選項” ，單擊“ 下一步 ”。

圖7. Javadoc生成向導（Standard Doclet）-選擇基本的Javadoc選項

在“ 文檔標題”字段中，指定要放置在概述摘要文件頂部附近的標題。如果省略文檔標題，則DITADoclet將添加默認標題Building DITA output 。

對于基本的Javadoc選項，請取消選擇復選框，如圖7所示。這些是可用的選項以及DITADoclet如何處理它們：

生成使用頁面 ：DITADoclet不創建使用頁面。
生成層次結構樹 ：DITADoclet將自動創建帶有或不帶有此標志選項輸入的層次結構樹頁面。
生成導航欄 ：DITADoclet將自動為每個頁面創建導航欄，無論是否為此標志選項輸入。
生成索引 ：DITADoclet將自動創建帶有或不帶有此標志選項輸入的索引頁。
每個字母單獨的索引 ：DITADoclet不會為每個字母頁面創建單獨的索引。

對于“ 記錄這些標簽”選項，取消選擇復選框，如圖7所示。

@author ：DITADoclet將自動將作者添加到元頁面，無論此標志選項是否輸入。
@version ：DITADoclet將自動將版本添加到.dita頁面，無論是否為此標志選項輸入。
@deprecated ：DITADoclet將自動將不推薦使用的信息添加到.dita頁面，無論是否為此標志選項輸入。
@不推薦使用的列表：DITADoclet將不會創建不推薦使用的列表頁面。

請記住，DITADoclet工具僅考慮“目標”字段值和“文檔標題”選項。在此示例中，Destination的值為.. \ workspace \ doc.dita.dost \ topics 。文檔標題的值為DITA-OT 。如果沒有為“目標”字段指定指定的值，則DITADoclet工具將在源代碼文件夾（\ src）中創建所有.dita文件。如果您未指定文檔標題字段值，則DITADoclet工具將添加默認標題Building DITA output 。

此時，您尚未創建overview.html文件，因此請不要選中Overview復選框。（當第二次運行該工具時，可以從\ workspace \ src文件夾中選擇新生成的overview.html文件。）

圖8.不指定概述頁面路徑

單擊“ 下一步 ”獲得Extra Javadoc選項（帶空格的路徑名必須用引號引起來）。這些選項是可選的。

圖9.額外的javadoc選項

-貢獻者將作者文本包含在生成的DITA中
-provider指定插件提供程序名稱的詳細信息。
-debug在Javadoc控制臺中提供警告消息

選項-contributor和-provider將向所有DITA生成的文件添加一個序言部分，其中包含編寫者的名稱，貢獻者的名稱，提供者的名稱，生成的日期，等等。請參見下面的示例。

創建者作者<author type="creator">Lian, Li</author>來自源代碼@author javadoc標記。
貢獻者的作者<author type="contributor">Mariana Alupului</author>來自-contributor Javadoc選項，如圖9所示。

清單1.輸出<prolog>

<prolog><author type="creator">Lian, Li</author><author type="contributor">Mariana Alupului</author><source href="org/dita/dost/xxx.Java">org/dita/dost/test/xxx.Java</source><publisher>IBM</publisher><copyright type="primary"><copyryear year="2008"/><copyrholder>IBM</copyrholder></copyright><critdates><created date="Wed, 17-Dec-2008 12:20:16 EST"/><revised modified="Fri, 19-Dec-2008 15:49:48 EST" status="new"/></critdates> </prolog>

單擊“ 完成”以生成DITA API文檔。

其他警告

DITADoclet顯示所有警告，這些警告可能會幫助您檢測Eclipse控制臺中的文檔中的錯誤或遺漏（請參見圖10 ）。默認情況下不打印這些警告。要請求它們，請使用選項-debug 。

圖10. Javadoc控制臺以及示例消息和警告

當日志文件達到一定大小時，您可以自動保存它們。在控制臺中，單擊Ctrl-Break以獲取此輸出。這在執行-debug選項場景中特別有用，因此您可以查看Eclipse系統中文檔生成過程中發生的情況。您還可以將日志文件發送給開發人員，以幫助他們了解哪些源文件缺少信息，警告等。

DITADoclet導航文件

DITADoclet會為插件生成輸出DITA（XML）文件，并在org.dita.dost \ topics \文件夾中生成其他幾個導航文件。 DITADoclet創建的導航文件是：

org.dita.dost.ditamap
org.dita.dost.doc.reltable.ditamap
org.dita.dost.doc.ditaval
org.dita.dost.doc.maplist

org.dita.dost.ditamap

ditamap文件提供Java API參考的名稱以及描述該軟件包或一組軟件包及其組件所必需的所有元素。

圖11. DITA輸出-org.dita.dost.ditamap文件

org.dita.dost.doc.reltable.ditamap

reltable文件定義關系表以管理內部類和接口。如果沒有內部類或接口，則DITADoclet將不會創建reltable。

org.dita.dost.doc.ditaval

您可以通過以下屬性來過濾DITA的DITA元素：受眾群體，平臺，產品和其他屬性。您可以在DITA源中的元素上為這些屬性中的一個或多個指定值。使用這些屬性，您可以打開或關閉文本。也就是說，根據您聲明的屬性隱藏文本或顯示文本。如果您不使用文件中的屬性值，則可以從ditaval文件中完全刪除該屬性。如果您使用文件中的值，但現在不想標記它，請將操作從標志更改為包含在ditaval文件中（請參見圖12 ）。

圖12. DITA輸出-org.dita.dost.doc.ditaval文件中的Properties選項卡

org.dita.dost.doc.maplist

映射列表允許您包括ditamap和reltable.ditamap文件。地圖列表的作用類似于主文件，并調用地圖列表，而地圖列表又稱為DITA主題。

圖13. DITA輸出-org.dita.dost.doc.maplist文件

層次結構文件

DITADoclet生成三個文件，這些文件描述類的層次結構，類和接口的列表以及類，接口，構造函數，方法和字段的索引。

樹
allnames.dita
allclasses.dita

Java API參考頁面包含每個視圖的鏈接：

圖14. Java API Reference頁面上指向層次結構和索引頁面的鏈接

查看三個文件及其內容。

樹

tree.dita文件中的Class Hierarchy頁面（圖15 ）包含一個類列表和一個接口列表（對于所有軟件包）。這些類是從Java.lang.Object開始的繼承結構組織的。

圖15. tree.dita文件中的類層次結構

allnames.dita

allnames.dita文件中的Index （圖16 ）包含所有類，接口，構造函數，方法和字段的字母列表。

圖16. allnames.dita文件中的索引

allclasses.dita

allclasses.dita文件中的類和接口索引 （圖17 ）包含所有類和接口的字母列表。

圖17. allclasses.dita文件中的類/接口索引

您不需要編輯tree.dita，allnames.dita或allclasses.dita文件。僅在運行變壓器時出現錯誤或警告時才編輯它們。

DITA輸出中的輔助文件

javastyle.fos是DITADoclet創建的輔助文件，可以與Epic Editor一起使用。該文件為編寫者提供了Java源代碼中缺少的信息的直觀表示，編寫者可以在其中直接在DITA Java API文件或Java源代碼中輸入缺少的信息。

如果使用Epic編輯生成的DITA文件，則可以直接利用Java源代碼利用DITADoclet（fos文件）生成的綠色突出顯示的文本。它以綠色突出顯示缺少的注釋，并提供了可能的文檔替代方法。圖18顯示了使用DITADoclet生成并在Epic Editor中打開的DITA文件。

圖18. DITADoclet生成的fos文件中的示例輸出

首次運行DITADoclet時，該工具將創建overview.html文件（清單2 ）并將其保存在工作空間子目錄/workspace/org.dita.dost/src中。它還創建了overview-summary.dita文件（圖19 ），并將其保存在子目錄/workspace/org.dita.dost/topics中。

清單2. overview.html

<html><head><title>Building DITA output</title> <heading refname="" type="major" back-to-top="no">Headings</heading></head><body>Overview short description added in source code src\overview.html template.<h2>Overview Specification</h2>Overview specification added in source code src\overview.html template.</body> </html>

圖19.帶評論草案的summary.dita概述

第二次運行DITADoclet時，您已經生成了Overview（概述）（overview.html）。現在，您可以指定DITADoclet應該從overview.html文件中檢索此頁面的文本。 DITADoclet將所有信息（開發人員評論）復制到overview-summary.dita文件中。

再次運行DITADoclet時，輸出文件將如圖20所示。

圖20. Overview-summary.dita（不帶評論草案）

您可以編輯overview.html文件，也可以直接在overview-summary.dita文件中進行編輯。在記錄文件時，為避免再次運行DITADoclet時覆蓋此信息，請右鍵單擊overview-summary.dita文件。選擇“ 屬性” ，然后為“屬性”選擇“ 只讀” 。

首次運行DITADoclet工具時，該工具將創建package.html和package-summary.dita文件。如果Java源代碼中不存在該工具，則該工具將生成package.html文件。有關package-summary.dita文件生成的模板的示例，請參見圖21 。（為防止DITADoclet覆蓋package-summary.dita信息，請在package-summary.dita文件上單擊鼠標右鍵。選擇“ 屬性” ，然后為“屬性”選擇“ 只讀” 。這將鎖定文件內容。）

圖21.第一次運行DITADoclet工具后的package-summary.dita

第二次運行DITADoclet工具時，您的Java源代碼中已經存在package.html文件，該工具將從該文件中獲取所有信息并將其遷移到package-summary.dita文件。現在，您可以在這些文件中完成軟件包的信息。有關示例，請參見圖22 。

圖22.第二次運行DITADoclet工具后的package-summary.dita

現在，您可以選擇包的模板（第一次運行該工具時生成的package.html文件），DITADoclet將自動檢索該頁面的開發人員注釋并將所有信息復制到package-summary.dita文件中。。

請參見圖23中的示例，以獲取已記錄的軟件包，您可以在瀏覽器中查看它：

圖23.瀏覽器中顯示的文檔

[簡短的介紹]

主軟件包org.dita.dost.log包含類DITAOTBuildLogger，該類負責將消息記錄在屏幕上和日志文件中。

詳細說明：

屏幕上的消息向用戶提供狀態信息，警告，錯誤和致命錯誤消息。日志文件中的消息為用戶提供了有關轉換過程的更多詳細信息。通過分析這些消息，用戶可以了解導致問題的原因以及解決方法。
日志記錄方法基于Ant的Logger＆Listener接口。默認情況下，此日志記錄方法是禁用的，并且所有消息都與以前的版本一樣出現在屏幕上。

增強的Ant命令：

要啟動這種新的日志記錄方法，您需要遵循以下用法：

在Ant命令提示符處，通過在命令參數中附加-logger org.dita.dost.log.DITAOTBuildLogger來指定記錄器，例如： ant sample.web -logger org.dita.dost.log.DITAOTBuildLogger
在Java命令提示符處，記錄器是在內部指定的，因此您無需再次指定它。

重要更改和未來更新：

DITA-OT 1.2 offers new error handling and logging system. If you invoke your transformation with the Java command line where new error handling and logging system is mandatory, you need to set the CLASSPATH Environment Variable for dost.jar. If you invoke your transformation with an ant script, you need to do one more step after the above setting. That is, add a parameter in your command to invoke an ant script. 例如，使用： ant -f ant\sample_xhtml.xml -logger org.dita.dost.log.DITAOTBuildLogger
instead of: ant -f ant\sample_xhtml.xml
to start a transformation defined in ant script file ant\sample_xhtml.xml.

DITADoclet records all output files into the root output directory specified with the -d command option, and into subdirectories of the root output directory. DITADoclet automatically creates the root output directory and all of the subdirectories. Figure 24 shows the directory structure and the names of the default files created by the DITADoclet using an example of the directory structure generated for your sample package, org.dita.dost. The left side shows the Java source code and its component files. In the right side, you can see the DITA files generated from this Java source code folder.

Figure 24. Directory structure and names of default files

When you run the DITADoclet tool for the first time, the tool creates all DITA files. After that, it will create a copy of the initially generated DITA files as #0.xxx.dita, #1.xxx.dita, and so on until you reach #64.

Keeping different versions of the files can help during the debugging and verification process of the documentation after changes to Javadoc comments are made in Java source code.

Creating Java API reference documentation using DITADoclet and command prompt line

It is important to know what parameters Javadoc reads and uses, and the parameters that DITADoclet reads and uses. If you run Javadoc -help , you will see that the Javadoc tool has two sets of command-line options. One set is generic and will work with any doclet. The second set of options is specific to the standard doclet. Options in this second set will not be available when you use custom doclets. Your custom doclets can also define their own command prompt line options. This documentation contains only detailed descriptions of all options provided for DITADoclet. A detailed description of the Javadoc tool options is provided with the JDK documentation.

DITADoclet release 1.1.3 (see Related topics for a link) provides a command line interface as an alternative so users with little knowledge of Eclipse can easily use the toolkit.

Running Javadoc for the org.dita.dost example

See if Javadoc is installed on your path. Typically, Javadoc will have a path like C:\Program Files\Java\jdk1.5.0_06\bin.

Use the @options option to place the options in a separate file (documentation for this is provided with the JDK.)

Use the @packages option to place the packages' fully qualified names in a separate file.

Run the following command from your DITA directory C:\DITA\>: Javadoc @options @packages

Figure 25. Options and packages using the example

Java文檔 DITADoclet

C:\\DITA\>Javadoc @options @packages	C:\\DITA\>DITADoclet.exe @options @packages
選件 -sourcepath demo/src -d demo/output/org.dita.dost.doc -overview demo/src/overview-summary.html -doctitle 'Building DITA output' -use -tree -navbar -index -noauthor -version -deprecated -public	選件 -sourcepath demo/src -d demo/dita/org.dita.dost.doc -overview demo/src/overview-summary.html -doctitle 'Building DITA output' -provider IBM -contributor "Mariana Alupului" -public
配套 org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception	配套 org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

Running DITADoclet for the org.dita.dost example

Running DITADoclet from the command prompt is the same as running Javadoc:

If you add DITADoclet.exe to your path, use the @packages option to place the packages' fully qualified names in a separate file, and use the @options option to put the options in a file, you can run the following command from your directory C:\DITA\: DITADoclet @options @packages

If you choose to type the entire command in the command line, it will look something like this:

DITADoclet.exe -sourcepath demo/src -d demo/output/org.dita.dost.doc -overview demo/src/overview-summary.html -doctitle 'Building DITA output' -provider IBM -contributor "Mariana Alupului" org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

Using the DITADoclet for your project

You can modify the @options and @packages files by opening them with the WordPad editor.
Run the command: DITADoclet.exe @options @packages .

Running DITA-OT transformer to generate XHTML files from DITA

With the DITADoclet presented in this article, you produce Java API reference help documentation based on DITA files and a small number of additional documentation elements. Using DITADoclet, it is easy to create Eclipse platform documentation, which can then be used to produce XML and XHTML output formats for the existing Eclipse help systems. Over time, you can expect the addition of more output formats.

DITA-OT transformer has the capability to generate HTMLHelp (CHM). See Figures 26 and 27 for screen captures of DITA-OT transformer examples of CHM files, the first with draft comments, and the second without.

Figure 26. CHM with draft comments

Figure 27. CHM without draft comments

The API writer needs to resolve all draft comments (see Figure 26 ). A complete and fully documented set of Java API reference documentation will not contain any draft comments highlighted in green (see Figure 27 ).

API writers can use the DITADoclet testing solution to identify the missing information from the Java source code, and also test their work for complete and fully documented reference files before they deliver the source code to the online Help.

You can run the DITA-OT transformer to generate XHTML files from the DITA Java API files in an Eclipse environment. The example in Figure 28 was generated in this fashion.

Figure 28. Eclipse on-line help

DITADoclet advantages

The advantages of using the DITADoclet to generate DITA Java API documentation are:

搜索

Provides an efficient way to retrieve methods and classes/or interfaces. The Javadoc system does not provide such a search mechanism for the table of contents (TOC).

Navigation

Provides a TOC navigation that is generated automatically directly from the Java source code.

指數

The indexes complement the keyword search. Indexes are created by the API writer and can therefore give valuable additional information.
The index lists all packages, classes, interfaces, methods and fields, sets them into context (for example, gives the containing class for a method or field) and links to the document describing the entry.

Links

DITA shows the missing links that are hard to find without using DITA. For this demo project (org.dita.dost), you have 108 topics with 3567 local links that DITA automatically checks.

DITADoclet disadvantages

You can use the tool to create DITA Java API files only from Java source files version 1.4. The next version of DITA API specialization and DITADoclet will support Java version 1.5 and 1.6 (including annotations, enumeration, generics, and so on.)

Specialization contributors

I want to acknowledge and extend a special thanks to all the key people that contributed to the development of the DITA API specialization:

Type architect: Michael Priestley - Senior Technical Staff Member (STSM) Lead IBM DITA Architect
Document structures and processing: Erik Hennum - XML, DITA, XSLT, Perl; Web technologies: JSP, Java Servlet, JavaScript, CSS; User Assistance: Eclipse, JavaHelp
Subject matter experts: Mariana Alupului
Information developers: Mariana Alupului, Rob Pierce, Nigel Hopper, Dennis Grace, Ian Hartshorn
Information architect: Erik Hennum
Authoring Tools (Information Development Workbench): Robert D Anderson
Translation Tool Development and Globalization Support: David Walters
Java API pilot project lead: Mariana Alupului
Editor: Michelle C Carey
IDWBWIN Help and Guidelines Documentation: Mariana Alupului
Guidelines and standards (style guidelines for output): Michelle C Carey

翻譯自: https://www.ibm.com/developerworks/xml/library/x-DITAdoclet/index.html