dita文檔

2009年12月11日修訂說明：在“ 目標”和“ 安裝org.dita.dost插件 ”標題下添加了兩個指向可下載資源的鏈接。

2014年3月7日，修訂說明：在參考資料中刪除了過時的“ IBM XML認證”鏈接。

2014年3月17日修訂說明：刪除了參考資料中過時的“ DITA FAQ”鏈接。

目標

在本文中，您將學(xué)習(xí)如何使用DITADoclet，DITA Java API專業(yè)化和Eclipse IDE來創(chuàng)建Java API參考文檔，以便于以多種格式輕松分發(fā)。 DITADoclet生成DITA Java API文件，自動為Java API參考文檔創(chuàng)建DITAMAP和MAPLIST文件（DITA Java API專業(yè)化），從Java源代碼中提取開發(fā)人員注釋，并將信息遷移到生成的DITA API文件中。

常用縮略語

• API：應(yīng)用程序編程接口
• CHM：編譯的Windows?HTML幫助
• CSS：級聯(lián)樣式表
• DITA：達爾文信息鍵入體系結(jié)構(gòu)
• DTD：文檔類型定義
• HTML：超文本標記語言
• IDE：集成開發(fā)環(huán)境
• J2EE：Java 2平臺企業(yè)版
• JDK：Java開發(fā)套件
• JSP：Java服務(wù)器頁面
• URI：統(tǒng)一資源標識符
• XHTML：可擴展超文本標記語言
• XML：可擴展標記語言
• XSLT：可擴展樣式表語言轉(zhuǎn)換

通常，Sun Microsystems的Javadoc工具用于從Java源代碼生成Java API參考文檔。 Javadoc工具生成Java API參考文檔的基本結(jié)構(gòu)，但是該文檔通常不完整，并且僅限于開發(fā)人員注釋。 開發(fā)團隊的變更似乎鼓勵從Java API參考文檔過程中完全刪除API編寫者和編輯者。 開發(fā)人員有時間只管理帶有不完整注釋的Java源代碼文件。 這種情況清楚地向API編寫者和其他對產(chǎn)生高質(zhì)量API文檔感興趣的人提出了一些挑戰(zhàn)。

DITADoclet和DITA Java API解決方案為API編寫者提供了生成完整記錄的Java API的工具。 完整記錄的API有多種用途，但是最重要的原因是允許API用戶完全理解，搜索和瀏覽他們可用的API函數(shù)。 為了完全使用API??的功能，軟件用戶需要一個準確且完整記錄的API。

為了了解DITADoclet的工作原理，本文還介紹了Javadoc標準doclet解決方案使用的一些重要概念。 為了使DITADoclet自動提取有效地工作，必須根據(jù)Javadoc嚴格準則記錄Java源代碼。 否則，當您使用DITADoclet提取注釋時，注釋可能無法正確處理，或者生成的API文檔可能不完整。

本文介紹以下內(nèi)容：

• 先決條件
• 什么是DITA Java API專業(yè)化？
• DITADoclet安裝
• 使用Eclipse Javadoc Generation向?qū)?#xff08;標準Doclet）創(chuàng)建Javadoc文檔
• 使用以下方法創(chuàng)建Java API參考文檔：
  • Eclipse Javadoc生成向?qū)?#xff08;DITADoclet）
  • 命令提示符
• DITADoclet的優(yōu)缺點

請參閱可下載資源以下載DITADoclet。

要了解有關(guān)DITA的更多信息，如何創(chuàng)建或編輯DITA文件以及查找更多支持DITA的XML編輯器，請訪問http://dita.xml.org網(wǎng)站。 我強烈建議您使用XML編輯器以避免標記錯誤。 提供了許多不同的XML編輯器：Arbortext Editor?，<oXygen />?XML編輯器，XMLBuddy?（Eclipse插件），Altova?XMLSpy?，OpenOffice.org等。 我建議使用Arbortext Editor作為內(nèi)容發(fā)布系統(tǒng)。

聽眾

本材料面向API編寫者，并假定您熟悉Java軟件，Java API引用文檔結(jié)構(gòu)，Javadoc生成，并且作為API編寫者，您想了解更多有關(guān)如何提供改進的Java API引用文檔的信息。

API編寫者應(yīng)理解開發(fā)人員編寫的代碼，并提取要在API文檔中發(fā)布的相關(guān)信息。 使用DITADoclet生成DITA Java API文檔所獲得的成功取決于您對Java源代碼的熟悉程度。

先決條件

本文介紹了直接從Java源代碼生成Java API參考DITA文件所需的先決條件，以及如何使用Eclipse轉(zhuǎn)換文件。 在使用DITADoclet和DITA Java API專業(yè)化之前，您需要熟悉以下概念：

• Java API參考文檔過程和Javadoc生成
• 蝕
  • Java IDE和編輯器的觀點和觀點
  • Eclipse基本概念，例如體系結(jié)構(gòu)，插件和插入工作臺
  • 最小插件的元素，例如項目，Eclipse視圖和編輯器
  • 如何使用Eclipse Java IDE創(chuàng)建，安裝和運行簡單的插件
• Eclipse是基??本的IDE，但是有許多與Java相關(guān)的Eclipse插件，以及在Eclipse之上構(gòu)建的幾種商業(yè)IDE：
  • Rational?Software Architect是一個全面的集成開發(fā)環(huán)境，用于可視化地設(shè)計，構(gòu)建，測試，分析和部署應(yīng)用程序
  • Rational Application Developer for WebSphere Software通過可視化開發(fā)功能擴展了Eclipse
  • IBM?WebSphere?Studio是來自IBM的功能強大且流行的J2EE IDE
  • 用于Java的IBM WebSphere Studio Site Developer是用于Windows和Linux的Java IDE
  • Sun Java Studio Creator
  • JBuilder的

要下載這些插件，請參閱參考資料 。 我建議使用Eclipse構(gòu)建工具或直接從命令提示符行運行DITADoclet。

什么是DITA Java API專業(yè)化？

如果您熟悉DITA，則可以跳過此說明并轉(zhuǎn)到下面的DITADoclet安裝 。

DITA強制執(zhí)行一致，完整和正確的技術(shù)文檔。 DITA API專業(yè)化表示產(chǎn)生Java API文檔文件的DITA主題類型的包。 DITADoclet直接從Java源代碼生成DITA文件。 您可以從命令提示符或使用Eclipse運行它。

達爾文信息鍵入架構(gòu)（DITA）

維基百科上提到的DITA的簡要歷史

• 2001年3月：IBM推出了DITA
• 2002年5月：將領(lǐng)域?qū)I(yè)化添加到主題專業(yè)化
• 2004年4月：成立了OASIS DITA技術(shù)委員會
• 2005年2月：SourceForge開始支持DITA Open Toolkit
• 2005年6月：DITA v1.0被批準為OASIS標準
• 2005年8月：DITA Open Toolkit v1.1發(fā)布了
• 2006年3月：OASIS啟動DITA.XML.org
• 2007年8月：DITA V1.1已獲得OASIS的批準，包括Bookmap專業(yè)化認證

DITA代表一種開放的，OASIS標準，基于XML的體系結(jié)構(gòu)，用于創(chuàng)作，生成和交付技術(shù)信息。 盡管您可以在任何文本編輯器中編輯DITA文件，但是XML編輯器使您可以輕松插入和修改標簽，同時符合DITA DTD和模式。 我確實建議您使用XML編輯器來消除標記中的錯誤。 可用的XML編輯器包括Arbortext編輯器，oXygen，XML Buddy（Eclipse插件），Altova XML Spy等。

要了解更多關(guān)于DITA以及如何創(chuàng)建或編輯DITA文件，尋找更多的XML編輯器，支持DITA，請參閱鏈接到DITA組織網(wǎng)站相關(guān)主題 。

DITA開放平臺是免費軟件，您可以根據(jù)自由軟件基金會發(fā)布的GNU通用公共許可的條款進行重新分發(fā)和修改。 發(fā)行DITA開放平臺是希望它會有用，但沒有任何保證。 請參閱相關(guān)主題的更多細節(jié)。

DITA API專業(yè)化

DITA API專業(yè)化文檔通過用于通用（所有編程語言）和Java編程語言的DTD元素描述了基于XML的DITA架構(gòu)。 DITA API專長包括主題類型和元素，用于記錄通用和Java API參考。 每個特定于語言的DITA API專長都包含模塊。 模塊是為特定任務(wù)（例如描述API包或類）設(shè)計的主題類型。 每個模塊都包含適當?shù)腦ML元素，以描述編程語言的特定部分。

在本文中，您將學(xué)習(xí)如何運行DITADoclet來生成DITA Java API參考文件，以及如何使用DITA Java API解決方案來記錄引用。

您可以使用DITA通用API專長來創(chuàng)作和生成Java，Visual Basic和其他編程語言的API參考文檔。

DITADoclet安裝

要運行DITADoclet，您需要安裝Java開發(fā)工具包（JDK）和Eclipse。

安裝JDK

• 如果系統(tǒng)路徑中不包含Java二進制文件，或者未定義JAVA_HOME環(huán)境變量，則運行此工具可能會失敗。 您需要JDK來運行DITADoclet。
• 建議使用Java 5 JDK。 通常，Java安裝的路徑類似于C：\ Program Files \ Java \ jdk1.5.0_06 \。 要確定系統(tǒng)上已安裝的Java版本，請在命令提示符下鍵入： Java -version
• 如果您的Java版本不是最新，下載JDK，J2RE或JRE從Sun下載站點（請參閱相關(guān)信息的鏈接。）

安裝Eclipse Classic

• 下載適用于Windows的Eclipse Classic，IBM Rational Developer或Rational Software Architect Standard Edition，然后將zip文件解壓縮到您選擇的目錄中（例如，在Windows上為C：\ eclipse \）。 請參閱相關(guān)主題的鏈接。
• 最重要的是確保Eclipse安裝路徑在Windows平臺上不包含任何空格。 有關(guān)不同工具安裝的更多詳細信息，請參考官方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 \）。 它將創(chuàng)建一個目錄\ DITA，其中包含DITADoclet.exe，ReadeMe.txt和一個\ demo子目錄。
  • \ demo子目錄包含\ src資源目錄，選項和軟件包。
  • \ src資源目錄包含您將用作示例的Java源文件。 您可以直接從SourceForge網(wǎng)站下載源文件（DITA-OT1.4_src.zip）。

安裝org.dita.dost插件

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

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

將Java項目org.dita.dost導(dǎo)入到Eclipse工作區(qū)中。

可選的安裝步驟

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

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

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

使用標準Doclet創(chuàng)建Javadoc文檔（Eclipse Javadoc生成向?qū)?#xff09;

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

以下步驟顯示了如何使用標準Javadoc Doclet在Eclipse開發(fā)環(huán)境中生成Javadoc。

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

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

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

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

圖1.選擇javadoc.exe路徑

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

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

• 選擇為： -package，-private，-protected或-public ， 如圖2所示 。

  圖2.選擇成員可見性

• 表1說明了根據(jù)所需可見性選擇的成員。 -public選擇最少的成員， -private選擇最多的成員。

表1.成員可見性

選項 記錄這些類

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

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

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

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

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

圖3.概述頁面位置

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

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

圖4.指定文檔標題

其他Javadoc選項

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

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

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

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

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

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

既然您已經(jīng)回顧了Javadoc如何生成Java API參考文件，那么看看DITADoclet如何為Java API參考文檔生成DITA文件。 在下一節(jié)中，您將看到如何使用Eclipse Javadoc生成向?qū)?#xff08;DITADoclet）創(chuàng)建Java API參考文檔。

使用DITADoclet創(chuàng)建Java API參考文檔（Eclipse Javadoc生成向?qū)?#xff09;

DITADoclet解析源文件，提取Javadoc注釋，并直接從Java API源代碼文件構(gòu)建DITA文件。 此設(shè)計的目的是使API技術(shù)編寫者可以輕松利用他們現(xiàn)有的Eclipse Javadoc Generation向?qū)еR，并且僅需學(xué)習(xí)很少的DITA文檔特定差異：

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

以下步驟顯示了如何在Eclipse開發(fā)環(huán)境中將定制的doclet DITADoclet與Javadoc結(jié)合使用：

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

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

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

圖6. Javadoc生成向?qū)?#xff08;Standard Doclet）打開了Generate Javadoc窗口

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

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

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

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

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

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

圖7. Javadoc生成向?qū)?#xff08;Standard Doclet）-選擇基本的Javadoc選項

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

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

• 生成使用頁面 ：DITADoclet不創(chuàng)建使用頁面。
• 生成層次結(jié)構(gòu)樹 ：DITADoclet將自動創(chuàng)建帶有或不帶有此標志選項輸入的層次結(jié)構(gòu)樹頁面。
• 生成導(dǎo)航欄 ：DITADoclet將自動為每個頁面創(chuàng)建導(dǎo)航欄，無論是否為此標志選項輸入。
• 生成索引 ：DITADoclet將自動創(chuàng)建帶有或不帶有此標志選項輸入的索引頁。
• 每個字母單獨的索引 ：DITADoclet不會為每個字母頁面創(chuàng)建單獨的索引。

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

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

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

此時，您尚未創(chuàng)建overview.html文件，因此請不要選中Overview復(fù)選框。 （當?shù)诙芜\行該工具時，可以從\ workspace \ src文件夾中選擇新生成的overview.html文件。）

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

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

圖9.額外的javadoc選項

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

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

• 創(chuàng)建者作者<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以獲取此輸出。 這在執(zhí)行-debug選項場景中特別有用，因此您可以查看Eclipse系統(tǒng)中文檔生成過程中發(fā)生的情況。 您還可以將日志文件發(fā)送給開發(fā)人員，以幫助他們了解哪些源文件缺少信息，警告等。

DITADoclet導(dǎo)航文件

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

• 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文件定義關(guān)系表以管理內(nèi)部類和接口。 如果沒有內(nèi)部類或接口，則DITADoclet將不會創(chuàng)建reltable。

org.dita.dost.doc.ditaval

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

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

org.dita.dost.doc.maplist

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

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

層次結(jié)構(gòu)文件

DITADoclet生成三個文件，這些文件描述類的層次結(jié)構(gòu)，類和接口的列表以及類，接口，構(gòu)造函數(shù)，方法和字段的索引。

• 樹
• allnames.dita
• allclasses.dita

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

圖14. Java API Reference頁面上指向?qū)哟谓Y(jié)構(gòu)和索引頁面的鏈接

查看三個文件及其內(nèi)容。

樹

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

圖15. tree.dita文件中的類層次結(jié)構(gòu)

allnames.dita

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

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

allclasses.dita

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

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

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

DITA輸出中的輔助文件

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

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

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

首次運行DITADoclet時，該工具將創(chuàng)建overview.html文件（ 清單2 ）并將其保存在工作空間子目錄/workspace/org.dita.dost/src中。 它還創(chuàng)建了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時，您已經(jīng)生成了Overview（概述）（overview.html）。 現(xiàn)在，您可以指定DITADoclet應(yīng)該從overview.html文件中檢索此頁面的文本。 DITADoclet將所有信息（開發(fā)人員評論）復(fù)制到overview-summary.dita文件中。

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

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

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

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

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

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

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

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

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

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

[簡短的介紹]

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

詳細說明：

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

增強的Ant命令：

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

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

重要更改和未來更新：

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.

指數(shù)

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

dita文檔

總結(jié)

以上是生活随笔為你收集整理的dita文档_使用DITADoclet和DITA API专业化生成DITA Java™API参考文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。