本節內含有關由 FDP 所管理的特定文件的特定注意事項。
操作手冊是以使用 FreeBSD DocBook 擴充 DTD 的 DocBook XML 所撰寫。
使用手冊使用 DocBook book
來組織,整個手冊區分成數個部份 (part
),每個部份中內含數個章 (chapter
),而章 (chapter
) 又更進一步的細分成數個節 (sect1
) 與小節 (sect2
, sect3
) 以此類推。
在 handbook
目錄中有數個檔案及目錄。
使用手冊的組織結構可能會隨時改變,本文件所詳述的組織結構可能會與現況不盡相同。有關使用手冊組織結構的問題可張貼到 FreeBSD documentation project mailing list。
Makefile
定義了一些會影響 XML 原始碼要如何轉換至其他格式的變數,並列出產生使用手冊所需的各原始檔,接著會引用可處理在各種文件格式轉換的標準 doc.project.mk
程式碼。
此為使用手冊的最上層文件,其中包含了使用手冊的 DOCTYPE 宣告以及用來描述使用手冊結構的元素。
book.xml
會使用 參數 Entities 來載入 .ent
副檔名的檔案。這些檔案 (稍後會詳述) 接著會定義使用手冊剩下篇幅會使用的 一般 Entities。
每個在使用手冊的章會儲存成名稱為 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>。