本文說明 Apache HTTP Server 文件 XML 原始檔的格式,以及轉換成 HTML 的技術。
在手冊的style 目錄中,可以找到一個 DTD。您可以在mod_template.txt中找到一個有詳細註解的範例格式。(一般來說,檔案副檔名會是 xml
。這裡更改為讓線上檢視更為容易。)
可以使用下列幾種不同的格式化語法
關鍵字 | 目的 |
---|---|
<example> ... </example> | 將範例格式化為等寬字型 |
<highlight language="config"> ... </highlight> | 設定範例,語法突顯。也可以使用 language="perl"、"lua" 或 "C" |
查看已轉換文件的最快方式,就是直接開啟新的 MSIE、Netscape 或 Mozilla 版本的 XML 檔。(MSIE 6 看似始終如一。然而,基於 Gecko/Mozilla 的瀏覽器沒有併入所述的 DTD,所以它們無法處理包含字元實體的文件)。這些瀏覽器會讀取 xsl 檔並自動執行轉換,讓您可以看到最後的輸出品看起來會如何。這表示您可以在文件上工作,並在沒有任何特殊轉換設定的情況下檢查您的工作成果。
對於最後的簡報,仍然需要轉換為 HTML,以容納舊瀏覽器。儘管任何相容標準的 XSLT 引擎都應該可以執行,但是變更引擎會導致轉換檔案產生大量差異。因此,我們選擇了基於 Xalan+Xerces Java 和 Ant 的單一建議轉換系統。這些都是 Apache 項目,根據 Apache 授權散布。
轉換的唯一先決條件是 Java 8 或更新版本的 JVM。假設您已經 httpd/httpd/branches/2.4.x/docs/ (或其他分支的等效版本) 從 SVN 檢出,以下是您需要執行的建置動作:(如果您需要 SVN 設定指示,請參閱 此頁面。)
$ cd docs/manual
$ svn co https://svn.apache.org/repos/asf/httpd/docs-build/trunk build
$ cd build
$./build.sh all
如果您在 win32 中執行,如果已安裝 Cygwin,則指令碼 build.sh
會執行。或者,在 Win32 中,您應該可以使用指令碼 build.bat
。
如果您不想從 SVN 取得建置檔案,您可以從我們的 散佈目錄下載當前建置工具的 pkzip 版本。
預設目標僅建置英文文件。若要建置其他文件,您應將語言代碼 (ja、de 等) 指定為引數,或使用 all
目標。若要尋找可用的語言,請參閱我們的 translations page。
您可以輸入以下指令取得所有可能建置目標的概觀
./build.sh -projecthelp
在提交或驗證變更前,您應檢查 XML 是否正確,以及產生的 HTML
./build.sh validate-xml
./build.sh validate-xhtml
在加入新模組時,轉換程序會嘗試在 mod/allmodules.xml
中產生適當的條目,並建立附屬的元檔案 ( newfilename.xml.meta
)。由於這些任務是用 perl 編寫,因此您需要一個運作中的 perl 安裝。如果不是,您應手動執行這些步驟,或在專案郵寄清單上留下備忘,以便其他人可以執行。
PDF版本的說明文件,透過使用「latex-en」Ant目標轉換XML檔案至LaTeX產生。轉換用的XSLT樣式檔位於style/latex/
中。當每個.xml
檔案有了等值的.tex
版本之後,你可以使用pdflatex
將其轉換為PDF檔。建議的pdflatex版本可以從TeTeX(unix)或MikTeX(win32)取得,不過其他版本的TeX(只要夠完整且現代的)應該也可以。若要產生PDF,你應該處理sitemap.tex
檔案,它包含主要的LaTeX文件程式碼,且會包含所有其他檔案。輸出的PDF檔名稱將會是sitemap.pdf
,你可以自行重新命名。
關於XML至LaTeX的轉換,有一些事項需要注意。雖然HTML和LaTeX有許多相似之處,但兩者之間的差異仍足以讓同時支援這兩種輸出的任務變得困難。特別是處理表格的方法就有很大的不同。為了協助將設計成HTML的表格轉換為LaTeX,應該在每個表格中新增一個<columnspec>
區段。在<columnspec>
內,針對表格中的每個欄位加入一個<column width=".xx"/>
,其中xx
是該欄位所佔行寬的百分比。這將協助轉換基本的表格。較為複雜的項目(例如跨欄位或跨行)目前無法轉換。
此外,pdflatex
無法在產生的PDF中加入GIF檔,因此任何圖形都必須以PNG格式提供。
存在於XSLT中的其他各種限制性假設,目前來說對文件有效,但在未來可能需要修改。例如,將HTML樣式連結轉換為LaTeX交叉參照的程式碼,只能用於主目錄和一層的子目錄中。此外,<pre>
區段在LaTeX中通常無法運作良好,因為verbatim
區段中換行和格式化的規則不同。
最後,XML/HTML和LaTeX在換行規則上也有不同的差異。在LaTeX中,有些字元需要使用反斜線進行換行,且所有XML實體(&whatever;)都必須轉換為等值的LaTeX。目前使用XSLT中的巨大且難看的搜尋替換函式,來處理有限的字元集。在未來,這可能需要進行修改,特別是在處理翻譯時。使用perl指令碼和替換表格進行預處理可能會是比較好的解決方案。