4.3. 文件特定資訊

本節內含有關由 FDP 所管理的特定文件的特定注意事項。

4.3.1. 使用手冊 (Handbook)

books/handbook/

操作手冊是以使用 FreeBSD DocBook 擴充 DTD 的 DocBook XML 所撰寫。

使用手冊使用 DocBook book 來組織,整個手冊區分成數個部份 (part),每個部份中內含數個章 (chapter),而章 (chapter) 又更進一步的細分成數個節 (sect1) 與小節 (sect2, sect3) 以此類推。

4.3.1.1. 實體組織結構

handbook 目錄中有數個檔案及目錄。

注意:

使用手冊的組織結構可能會隨時改變,本文件所詳述的組織結構可能會與現況不盡相同。有關使用手冊組織結構的問題可張貼到 FreeBSD documentation project mailing list

4.3.1.1.1. Makefile

Makefile 定義了一些會影響 XML 原始碼要如何轉換至其他格式的變數,並列出產生使用手冊所需的各原始檔,接著會引用可處理在各種文件格式轉換的標準 doc.project.mk 程式碼。

4.3.1.1.2. book.xml

此為使用手冊的最上層文件,其中包含了使用手冊的 DOCTYPE 宣告以及用來描述使用手冊結構的元素。

book.xml 會使用 參數 Entities 來載入 .ent 副檔名的檔案。這些檔案 (稍後會詳述) 接著會定義使用手冊剩下篇幅會使用的 一般 Entities

4.3.1.1.3. directory/chapter.xml

每個在使用手冊的章會儲存成名稱為 chapter.xml 的檔案,分別放在不同的目錄中。每個目錄均是以在 chapter 元素中 id 屬性中的值來命名。

例如,若有一章的檔案內容為:

<chapter id="kernelconfig">
...
</chapter>

那麼放置這個 chapter.xml 的目錄則會命名為 kernelconfig。一般來說一章的所有內容會存放在這一個檔案。

當有 XHTML 版本的使用手冊之後,會用該檔產出 kernelconfig.html,而這個名稱也是根據 id 的值而定,與目錄名稱無關。

在早期版本的使用手冊,檔案皆儲存在與 book.xml 相同的目錄中,而名稱會以 chapter 元素中的 id 屬性的值來命名。現在可在每個章節之中引用圖片,每個使用手冊章節的圖片會儲存在 share/images/books/handbook,而在地化版本的圖片應放在與每個章節 XML 原始碼相同的目錄。命名空間會衝突是必然的,但以目錄多、檔案少與目錄少、檔案多的結構相比,目錄多、檔案少會較容易處理命名空間衝突的問題。

簡單來說會有很多個內含 chapter.xml 檔案的目錄,例如 basics/chapter.xml, introduction/chapter.xml 以及 printing/chapter.xml

重要:

請勿以在使用手冊中的章節順序來命名章節或目錄,因為順序是會隨使用手冊重新組織後的內容改變的。重新組織結構應不需要去重新命名檔案,除非整個章節的階層被提升或下降。

chapter.xml 檔案並不是可以被單獨建置的完整 XML 文件,只能結合成整本使用手冊之後再一併建置。

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。