第?27?章?docbook 指南 · 開源世界旅行手冊

## 第?27?章?docbook 指南 **目錄** [](ch27.html#id3123080) [XML 簡介](ch27s02.html) [XML 語法](ch27s03.html) [標記](ch27s03.html#id3123193) [元素](ch27s03.html#id3123262) [處理指令](ch27s03.html#id3123298) [文件頭部](ch27s03.html#id3123327) [實體](ch27s03.html#docbook-entity) [DocBook 介紹](ch27s04.html) [搭建 DocBook 環境](ch27s05.html) [創建 DocBook 文檔](ch27s06.html) [結構元素](ch27s07.html) [文檔信息](ch27s08.html) [分子元素](ch27s09.html) [塊元素](ch27s10.html) [行內元素](ch27s11.html) [特殊字符](ch27s12.html) [列表](ch27s13.html) [Callout 列表](ch27s13.html#id3125171) [表格](ch27s14.html) [跨行表格](ch27s14.html#id3125603) [跨列表格](ch27s14.html#id3125784) [鏈接](ch27s15.html) [內部鏈接](ch27s15.html#docbook-ln) [外部鏈接](ch27s15.html#id3126103) [腳注](ch27s15.html#id3126172) [參考](ch27s15.html#id3126216) [告示](ch27s16.html) [圖形](ch27s17.html) [文檔工程](ch27s18.html) [DocBook 編輯軟件](ch27s19.html) [發布](ch27s20.html) [使用 CSS 定制外觀](ch27s21.html) [代碼塊的樣式](ch27s21.html#id3127629) [簡單表格的樣式](ch27s21.html#id3127710) [技巧](ch27s22.html) [關于表格](ch27s22.html#id3127854) [交叉引用](ch27s22.html#id3127875) [calloutlist 自動編號問題](ch27s22.html#id3127890) [斷行符](ch27s22.html#db-linebreak) [內部鏈接](ch27s22.html#id3127988) ## XML 簡介在學習 DocBook 之前，我們需要先了解一下 XML，因為 DocBook 是 XML 的一個 DTD（文檔類型定義） XML 是一種被設計用來存儲、交換數據的通用標記語言為了使它更加的通用，XML 的元標記不具有意義，XML 使用 DTD 賦予某一組標記特定的意義為了便于自動處理，它只包含內容而不包含樣式定義，XSL 便是這樣一種自動處理的機制，它將根據特定規則將 XML 轉換為可以定義樣式的格式 Html 語言不具備以上特點，我們用它對比說明，一份完整的 Html 文檔就是由許多這樣的標記嵌套而成： ``` <html> <head>頭部</head> <body> <p>這是一個段落，這里是 <b>粗體</b> </p> </body> </html> ``` * Html 語言的標記，都有具體的意義，像 `<p>` 表示這是一個段落 * Html 語言的標記，還可以直接定義內容的樣式。比如加粗某處文字，使用標記 `<b>粗體</b>`。 ??`<b>`是開始標記，它告訴瀏覽器，從這個標記開始，后面內容用粗體顯示； ??`</b>`是結束標記，它告訴瀏覽器，粗體顯示到這里結束由于 Html 語言的標記都有具體的意義，都和網頁顯示有關，所以它也只能用來顯示網頁。如果在 DTD 中定義 `<b> <p>` 這些標記的意義，XML 也可以顯示網頁（xhtml）假設有一段文字，里面提到一個文件名和一個軟件名，由于 Html 的標記指定的是樣式而不是內容，作為變通，我們可以使用粗體來表示它們，但是不能準確的區分它們。而 XML 定義的是內容，把它們分別定義為 filename 和 application，然后通過 XSL 給它們指定不同的樣式，便可以很容易的區分 ## XML 語法 ### 標記 XML 使用 `< >` 來定義標記所有的 XML 標記必須結束。`<para>`必須有一個與之配對的`</para>`；或者使用空標記，例如`<para/>` XML 標記大小寫敏感。`<para>`和`<PARA>`是兩個不同的標記；在 Docbook 中，所有的標記都是小寫的標記必須正確的嵌套，不允許相互嵌套 ``` <section><para></section></para> 錯誤 <section><para></para></section> 正確 ``` ### 元素 XML 使用開始標記和結束標記來定義元素。例如`<para>段落</para>`；或者使用空標記，例如`<xref linkend="ln"/>` 元素可以帶有一個或多個屬性，也可以不帶屬性。屬性值必須加引號，例如`<para id="p1">` ### 處理指令使用`<? ?>`括起來，例如：`<?linebreak?>`插入一個斷行符[參見](ch27s22.html#db-linebreak "斷行符") ### 文件頭部 ``` <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5/zh_cn" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s03.html#docbook09) 處理指令 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s03.html#docbook11) XML 的版本是1.0 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s03.html#docbook12) 文檔的編碼是 UTF-8 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s03.html#docbook10) 開始聲明 DTD(文檔類型定義) > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s03.html#docbook13) 聲明文檔的根元素是 article > [![6](https://box.kancloud.cn/2016-01-06_568cdb4f32753.png)](ch27s03.html#docbook15) 公共標識 > [![7](https://box.kancloud.cn/2016-01-06_568cdb4f41fcc.png)](ch27s03.html#docbook14) 系統標識 ### 實體給內容指定一個名稱，通過名稱引用。引用時以`&`起始，`;`結束。這樣定義一個實體 ``` <!ENTITY x "XML"> ``` 輸入`&x;`，XML 會用 `XML` 替換它以上是內部實體，可以通過定義外部實體來引用外部文檔 ``` <!ENTITY docbook SYSTEM "docbook.xml"> ``` 輸入`&docbook;`，會將`docbook.xml`文件中的內容插入到當前位置內部實體和外部實體都是普通實體，只能夠在 DTD 中定義 ``` <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5/zh_cn" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY x "XML"> <!ENTITY docbook SYSTEM "docbook.xml"> ]> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s03.html#docbook21) 這里聲明 DTD 的方法是引用外部 DTD > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s03.html#docbook22) 自己定義的實體為內部 DTD * 內部 DTD 的定義優先于外部 DTD，如果你定義的實體外部 DTD 中已包含，引用時使用的是你自己的定義有一些特殊字符不能直接插入 XML 中，例如`<`、`&`、`空格字符`[[50](ch27s03.html#ftn.id3123601)]，使用`<`、`&`、` `[[51](ch27s03.html#ftn.id3123623)]輸入這些字符 * * * > [[50](ch27s03.html#id3123601)] 不管有多個空格，XML 都認為只有一個 > [[51](ch27s03.html#id3123623)] 它們預先定義在外部 DTD 中參見`/usr/share/xml/docbook/xml-dtd-4.5/ent/isonum.ent` ## DocBook 介紹前面已經講了，DocBook 是 XML 的一個 DTD[[52](ch27s04.html#ftn.id3123652)]。 DocBook 主要用來寫文檔，尤其適合寫科技文檔。 * 盡管它的語法不如 reStructuredText 之類文檔語言簡明清晰，但是它的表現能力足夠強大 * 它的結構控制能力十分強悍，對于大型的文檔工程，DocBook 幾乎是不二的選擇 * DocBook 足夠通用，它已經成為一種事實上的標準，可以生成多種格式的文檔，并為多種文檔工具所支持，它特別適合作為原始文檔來生成其它格式文檔 * * * > [[52](ch27s04.html#id3123652)] 它相當龐大，有400個左右的標記；當然常用的也就幾十個 ## 搭建 DocBook 環境在 Linux 系統中，DocBook 環境主要由以下幾個軟件包提供 | | | | --- | --- | | libxml2 | XML 解析器 | | docbook-xml | DocBook 的 DTD 定義 | | libxslt | XSL 轉換程序![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png) | | docbook-xsl | 用來處理 DocBook-XML 的樣式表 | > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s05.html#docbook-01) xsltproc 這個轉換程序就在這個軟件包中 > 還有兩個 JAVA 的轉換程序 saxon、 xalan，不推薦例如，在 Archlinux 中可以這樣安裝： ``` sudo pacman -S docbook-xml docbook-xsl libxslt libxml2 ``` ## 創建 DocBook 文檔這是一個最基本的 Docbook 文檔 ``` <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5/zh_cn" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <article> <info> <title>文章</title> <author>作者</author> <address>地址</address> <copyright><year>2008</year><holder>所有者</holder></copyright> </info> <sect1> <title>標題</title> <para> 內容 </para> </sect1> </article> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s06.html#docbook-create01) 文件頭，其實不需要深入的了解它，因為它的變動通常很小 ??留意一下系統支持的 DocBook DTD 最高版本**ls /usr/share/xml/docbook** > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s06.html#docbook-create02) 文檔的根元素，要緊跟文件頭 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s06.html#docbook-create03) 文檔信息 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s06.html#docbook-create04) 文檔主體，[“分子元素”一節](ch27s09.html "分子元素")中詳細介紹將上面代碼保存為`docbook.xml，`試著[發布](ch27s20.html "發布") ## 結構元素 DocBook 中的一些元素，在發布的時候會作為條目被收進目錄。它們表示的是文檔內部的結構，所以它們是結構元素,如下： ``` <set> <book> <part> <chapter> <sect1> <sect2> ………… </sect2> </sect1> </chapter> </part> </book> </set> ``` 如果 DocBook 的根元素是**article**，那么可以允許這種結構： ``` <article> <sect1> <sect2> ………… </sect2> </sect1> </article> ``` * 結構元素可以擁有標題，**title**、**titleabbrev**、**subtitle**任選一個，還可以擁有**info** 可以看出，無論是 Book 還是 Article，自 **sect1**[[53](ch27s07.html#ftn.id3124008)]而下的結構都是相同的。如果把**sect1**元素的內容放在一個單獨的文件中，那么無論是 Book 還是 Article 都可以不加改動的引用這個文件，參見[“文檔工程”一節](ch27s18.html "文檔工程") 以下是常用的結構元素 | 元素 | 說明 | | --- | --- | | set | 集 | | book | 書 | | part | 部 | | chapter | 章 | | article | 文章 | | sections | 節 | * * * > [[53](ch27s07.html#id3124008)] section 與 sect1、sect2……sect5 的區別在于，section 可以無限嵌套，sect1 到 sect5 只能逐級嵌套 > 推薦使用 sect1~5，這樣可以使文檔的結構更加清晰，而且通常5級也夠用了；如果超過5級，那樣的文章估計也沒法讀 ## 文檔信息 **info**跟在根元素之后，用來放置一些文件信息 ``` <info> <title>文章</title> <author>作者</author> <address>地址</address> <copyright><year>2008</year><holder>所有者</holder></copyright> </info> ``` ## 分子元素 DocBook 最基本的元素是 **para** 和塊元素，比它們大的是結構元素，比它們小的是行內元素。 | 元素 | 說明 | | --- | --- | --- | | sect1 | 節 | ![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png) | | section | 節 | ![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png) | | para | 段落 | ![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png) | | formalpara | 帶標題段落 | ![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png) | > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s09.html#dbk21) sect1-5逐級嵌套 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s09.html#dbk22) 可無限嵌套 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s09.html#dbk23) 簡單段落 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s09.html#dbk24) 復雜段落，可以帶標題 **section**其實屬于結構元素，它的標題會被收錄到目錄中。把它們放在這里，因為它們是放進單獨文件的最佳元素 ## 塊元素塊元素是和**para**同級的元素，它們比較復雜，后面會分別介紹 | 類別 | 元素 | 說明 | | --- | --- | --- | | 列表 | calloutlist | | bibliolist | 書目列表 | | glosslist | 詞匯列表 | | itemizedlist | 無序列表 | | orderedlist | 有序列表 | | segmentedlist | 成分列表 | | simplelist | 簡單列表 | | variablelist | 定義列表 | | 告示 | caution | 小心 | | important | 重要 | | note | 注意 | | tip | 提示 | | warning | 警告 | | 文本 | address | 地址 | | literallayout | 純文本 | | programlisting | 代碼 | | screen | 文本抓屏 | | synopsis | 命令、函數綱要 | | 例子，圖片和表格 | example | | informalexample | | figure | | informalfigure | | table | | informaltable | | 媒體文件 | audioobject | 音頻對象 | | imageobject | 圖片對象 | | imageobjectco | 帶 callout 的圖片對象 | | videoobject | 視頻對象 | | textobject | 文本對象 | | 其他 | blockquote | 引用 | | epigraph | 題記 | | msgset | 有關的錯誤信息 | | sidebar | 側邊欄 | ## 行內元素假如你想用特殊的格式表示諸如短語、用戶輸入、命令、軟件、文件，盡量不要使用 emphasis(強調)，它們有專門的元素來表示。盡管使用了這些元素，得到的效果可能和強調一樣是粗體，而且還要考慮使用哪種類型，比較麻煩。不過等到你想用紅色表示命令、綠色表示文件……，這個時候，如果你一直用的是 emphasis，你將會為你的草率付出代價。 | 元素名 | 含義 | 示例 | | --- | --- | --- | | abbrev | 略寫，一般后面帶有一個點('.') | <abbr class="abbrev">abbrev</abbr> | | emphasis | 強調 | _強調_ | | phrase | 短語 | 短語 | | quote | 用引號引起來 | “用引號引起來” | | trademark | 注冊商標 | 注冊商標? | | literal | 文字的字面含義 | `文字的字面含義` | | prompt | 提示符 | `提示符` | | userinput | 用戶輸入 | `用戶輸入` | | subscript | 下標 | <sub>下標</sub> | | superscript | 上標 | 上標 | | application | 軟件名 | 軟件名 | | command | 命令 | **命令** | | envar | 環境變量 | `環境變量` | | filename | 文件名 | `文件名` | | database | 數據庫 | 數據庫 | | email | 電子郵件 | `<[電子郵件](mailto:%E7%94%B5%E5%AD%90%E9%82%AE%E4%BB%B6)>` | ## 特殊字符一些字符在 XML 中有特殊的含義，只能夠通過其實體名稱輸入 | 字符 | 寫法 | 縮寫涵義 | | --- | --- | --- | | < | < | less than | | > | > | greater than | | & | & | ampersand | | " | " | quote | | ' | ' | apostrophe | | 空格 |   | none-break?space | * 通常需要使用實體輸入的字符包括`<`、`&`、`空格` ??XML 會將任意數量的空格解析為一個，如果想通過多個空格控制縮進，就要使用` ` ??`]]>`這個字符序列也不能直接輸入，這樣輸入它`]]>` 也可以不使用實體輸入特殊字符，通過**CDATA**直接引用： ``` <![CDATA[ `<&` ]]> ``` ## 列表最普通的列表為無序列表和有序列表： ``` <itemizedlist> <listitem> 列表項內容，可以使用**para**、**formalpara**等 </listitem> </itemizedlist> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s13.html#docbook-li-01) 無序列表；有序列表為**orderedlist**，每個項自動編號 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s13.html#docbook-li-02) 列表項詞匯列表詞匯列表每一項包括一個詞匯標題和詞匯定義，標題粗體，定義縮進。這本身就是一個詞匯列表 ``` <glosslist> <glossentry> <glossterm>詞匯標題</glossterm> <glossdef> <para>詞匯定義</para> </glossdef> </glossentry> </glosslist> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s13.html#docbook-li-11) 詞匯列表 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s13.html#docbook-li-12) 列表項 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s13.html#docbook-li-13) 詞匯標題 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s13.html#docbook-li-14) 詞匯定義 > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s13.html#docbook-li-15) 詞匯定義必須為**para**元素 ### Callout 列表在引用的代碼塊中加記號，并在外部注釋。如果你要解釋一個比較復雜的概念，**calloutlist**通常是最好的選擇 ``` <screen> 這里會有一個數字`1`<co id="1"/>的記號它就是 callout <co id="2"/> </screen> <calloutlist> <callout arearefs="1">這里是記號`1`的說明</callout> <callout arearefs="2">第二個記號的說明</callout> </calloutlist> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s13.html#docbook-cl01) 使用`<co id="1"/>`作記號 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s13.html#docbook-cl03) 第二個記號 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s13.html#docbook-cl04) calloutlist 列表，每一個項都用數字編號 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s13.html#docbook-cl02) callout 元素作為解釋，使用`arearefs=""`引用 ## 表格表格更適合用可視化方式來生成；因為它有兩個維度，使用線性的標記語言來生成，自然比較麻煩。 DocBook 生成表格雖然麻煩，但是相對 reStructuredText 等使用空間方位生成的方式，卻更容易控制表格分為兩種**table**和**informaltable**，區別在于**table**可以有標題，能夠被收錄到目錄中。下面是表格的實例： **表?27.1.?表格實例** | | 表頭 | | --- | --- | --- | | | 表底 | | 單元格一 | 單元格二 | 單元格三 | | 11 | 12 | 13 | | | 22 | 23 | | 31 | | | ``` <table> <title>表格實例</title> <tgroup cols="3"> <thead><row><entry></entry><entry>表頭</entry></row></thead> <tfoot><row><entry></entry><entry></entry><entry>表底</entry></row></tfoot> <tbody> <row> <entry>單元格一</entry> <entry>單元格二</entry> <entry>單元格三</entry> </row> <row> <entry>11</entry> <entry>12</entry> <entry>13</entry> </row> <row> <entry></entry> <entry>22</entry> <entry>23</entry> </row> <row> <entry>31</entry> </row> </tbody> </tgroup> </table> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s14.html#docbook-table01) 說明使用的是何種表格，**table**還是**informaltable** > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s14.html#docbook-table02) 表格標題 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s14.html#docbook-table03) 定義表格寬度（有多少列），必需！ > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s14.html#docbook-table04) 表頭，表格的第一行，用粗體顯示，非必需 > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s14.html#docbook-table05) 表底，其實我從來沒見過有人用它 > [![6](https://box.kancloud.cn/2016-01-06_568cdb4f32753.png)](ch27s14.html#docbook-table06) 表體，表格的主體部分 > [![7](https://box.kancloud.cn/2016-01-06_568cdb4f41fcc.png)](ch27s14.html#docbook-table07) 行，每一行可以擁有的單元格不能超過表格寬度的定義 > [![8](https://box.kancloud.cn/2016-01-06_568cdb4f5948a.png)](ch27s14.html#docbook-table08) 單元格。**entry**元素的內容從該行第一格開始排列 > [![9](https://box.kancloud.cn/2016-01-06_568cdb4f68749.png)](ch27s14.html#docbook-table09) 第一格留空的話，要用`<entry></entry>`占一個位置 > [![10](https://box.kancloud.cn/2016-01-06_568cdb4f83cf0.png)](ch27s14.html#docbook-table10) 留空的單元格之后沒有有內容的單元格，可以省略`<entry></entry>` ### 跨行表格 **表?27.2.?跨行表格** | | | | --- | --- | | 跨兩行 | 12 | 13 | | 22 | 23 | | 31 | 跨三行 | 33 | | 41 | 跨兩行 | | 51 | ``` <table> <title>跨行表格</title> <tgroup cols="3"> <tbody> <row> <entry morerows="1">跨兩行</entry><entry>12</entry><entry>13</entry> </row> <row> <entry>22</entry><entry>23</entry> </row> <row> <entry>31</entry><entry morerows="2">跨三行</entry><entry>33</entry> </row> <row> <entry>41</entry><entry morerows="1">跨兩行</entry> </row> <row> <entry>51</entry> </row> </tbody> </tgroup> </table> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s14.html#docbook-table21) 使用`morerows="N"`合并下方的N個單元格； > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s14.html#docbook-table22) 由于該行第一個單元格已經被合并，所以應在這里出現的**entry**元素取消 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s14.html#docbook-table23) 這里有一個**entry**被取消 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s14.html#docbook-table24) 這里有兩個**entry**被取消 ### 跨列表格 **表?27.3.?跨列表格** | | | | --- | --- | | 第一個單元格 | 第三個單元格 | 第四個單元格 | | 第一個單元格 | 第二個單元格 | | 第一個單元格 | 第二個單元格 | 第三個單元格 | 第四個單元格 | ``` <table> <title>跨列表格</title> <tgroup cols="4"> <colspec colnum="1" colname="1"/> <colspec colnum="2" colname="2"/> <colspec colnum="3" colname="3"/> <colspec colnum="4" colname="4"/> <tbody> <row> <entry namest="1" nameend="2">第一個單元格</entry><entry>第三個單元格</entry><entry>第四個單元格</entry> </row> <row> <entry>第一個單元格</entry><entry namest="2" nameend="4">第二個單元格</entry> </row> <row> <entry>第一個單元格</entry><entry>第二個單元格</entry><entry>第三個單元格</entry><entry>第四個單元格</entry> </row> </tbody> </tgroup> </table> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s14.html#docbook-table31) 先給每列取個名 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s14.html#docbook-table32) 列編號 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s14.html#docbook-table33) 列名。可以任意取，但為了清晰，我用編號作為列名 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s14.html#docbook-table34) 跨列單元格的起始列，用列名指定 > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s14.html#docbook-table35) 跨列單元格的結束列 ## 鏈接 ### 內部鏈接轉到[內部鏈接](ch27s15.html#docbook-ln "內部鏈接") ``` <sect1 id="target">被鏈接章節</sect1> 轉到<link linkend="target">被鏈接章節</link> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s15.html#docbook-ln01) 給被鏈接的部分指定一個 id > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s15.html#docbook-ln02) 給**link**元素添加**linkend**屬性，指向剛才定義的 id > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s15.html#docbook-ln03) **link**元素內容為鏈接文字如果想更精細的控制跳轉的目標，可以設置錨點 ``` 這里是一個錨點<anchor id="anchor"/> 點擊跳轉到<link linkend="anchor">錨點</link> ``` 點擊跳轉到[錨點](ch27s15.html#anchor) ### 外部鏈接訪問[linuxtoy.org](http://linuxtoy.org) ``` 訪問<ulink url="http://linuxtoy.org">linuxtoy.org</ulink> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s15.html#docbook-ln11) 協議不能省略 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s15.html#docbook-ln12) 外部地址 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s15.html#docbook-ln13) 鏈接文字 ### 腳注這是腳注<sup>[[54](ch27s15.html#ftn.id3126178)]</sup>的寫法 ``` <para>這是腳注<footnote><para>腳注示例</para></footnote>的寫法</para> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s15.html#docbook-ln21) 腳注內容必須為**para**元素或塊元素 ### 參考參考[“內部鏈接”一節](ch27s15.html#docbook-ln "內部鏈接") ``` 參考<xref linkend="docbook-ln"/> ``` * * * > [[54](ch27s15.html#id3126178)] 腳注示例 ## 告示告示往往比較有用，它的使用很簡單： ``` <note>note</note> <tip>tip</tip> <caution>caution</caution> <important>important</important> <warning>warning</warning> ``` > 注意：note > 提示：tip > 小心：caution > 重要：important > 警告：warning ## 圖形插入圖形的方法 ![](https://box.kancloud.cn/2016-08-07_57a6a93581b95.png) ``` <graphic fileref="img/warning.png"/> <imagedata fileref="img/warning.png"/> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s17.html#docbook-image) DocBook DTD 5.0 將統一使用**imagedata** 使用**figure**作為圖形的父元素可以進行編號 **圖?27.1.?** ![](https://box.kancloud.cn/2016-08-07_57a6a93581b95.png) ``` <figure> <imagedata fileref="img/warning.png"/> </figure> ``` ## 文檔工程如果你在作一個比較大的文檔，建議每個章節使用一個單獨的文件存儲，便于管理[[55](ch27s18.html#ftn.id3126372)] 前面講到的[實體](ch27s03.html#docbook-entity "實體")可以用來作這件事情有兩個文件一個是主文件`docbook.xml`，包含文件頭和文檔信息；另一個文件`file.xml`是文檔內容，主文件如下： ``` <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5/zh_cn" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY file SYSTEM "file.xml"> ]> <article> <info></info> &file; </article> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s18.html#docbook-project01) 定義外部實體 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s18.html#docbook-project02) 通過外部實體引用文檔 `file.xml`文件內容如下： ``` <sect1> <para> …… </para> </sect1> ``` * 參見[“分子元素”一節](ch27s09.html "分子元素") 如果把引用文件的列表放在外部文件中，則更加容易管理。但是 XML 不允許在 DTD 中引用普通實體[[56](ch27s18.html#ftn.id3126489)]，這就要定義參數實體： ``` <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5/zh_cn" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % list SYSTEM "list.xml"> %list; ]> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s18.html#docbook-project11) 在定義參數實體時，這里多了一個`%` > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s18.html#docbook-project12) 引用參數實體時使用`%`而不是`&` `list.xml`文件內容如下： ``` <!ENTITY file SYSTEM "file.xml"> <!ENTITY file1 SYSTEM "file1.xml"> <!ENTITY file2 SYSTEM "file2.xml"> ``` 這樣就可以在正文引用`list.xml`文件中定義的普通實體了 * * * > [[55](ch27s18.html#id3126372)] 即便文檔規模不是很大，把內容獨立出來也有好處，比如： > 每部分單獨發布，修改，節省時間 > 如果出錯便于排查 > [[56](ch27s18.html#id3126489)] 在 DTD 中能夠定義外部文件作為普通實體，但是只能在正文中引用，不能在 DTD 中引用 ## DocBook 編輯軟件我使用 Emacs 編輯 DocBook 源文件，使用`docbook-xml-mode.el`這個擴展，在`.emacs`文件中加入下面配置： ``` ;---------- Docbook (require 'docbook-xml-mode) (add-hook 'docbook-xml-mode-hook (function (lambda () (setq outline-regexp "<!\\-\\-\\*+") (outline-minor-mode) (hide-body)))) ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s19.html#docbook-edit01) 加載 docbook-xml-mode > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s19.html#docbook-edit02) 添加 docbook-xml-mode 鉤子，運行下面代碼 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s19.html#docbook-edit03) 將` <xsl:import href="/usr/share/xml/docbook/xsl-stylesheets-1.73.2/html/chunk.xsl"/> <xsl:param name="chunker.output.encoding" select="'utf-8'"/>  <xsl:param name="l10n.gentext.language" select="'zh_cn'"/>  <xsl:param name="html.stylesheet" select="'docbook.css'"/>  <xsl:param name="admon.graphics" select="1"/>    <xsl:param name="chunker.output.indent" select="'yes'"/>  <xsl:param name="section.autolabel" select="0"/>  <xsl:param name="section.label.includes.component.label" select="1"/>  <xsl:param name="table.borders.with.css" select="0"/>  <xsl:param name="bibliography.numbered" select="1"></xsl:param>  <xsl:param name="toc.max.depth" select="2"/>  <xsl:param name="generate.section.toc.level" select="0"/>  <xsl:param name="toc.section.depth" select="2"/>    <xsl:param name="generate.toc"> appendix toc article/appendix nop article toc,title book toc,title,example chapter toc,title part toc,title preface toc,title qandadiv toc qandaset toc reference toc,title sect1 toc sect2 toc sect3 toc sect4 toc sect5 toc section toc set toc,title </xsl:param>  <xsl:template match="processing-instruction('linebreak')"> <br/> </xsl:template> </xsl:stylesheet> ``` 將偷懶進行到底，使用下面 `Makefile`，在工作目錄下鍵入**make**就可以了[[57](ch27s20.html#ftn.id3127148)] ``` OBJECT = all SOURCE = docbook.xml PARAM = param.xsl ARG = --output html/ COMPILER = xsltproc $(OBJECT):$(SOURCE) $(PARAM) $(COMPILER) $(ARG) $(PARAM) $(SOURCE) clean: rm -rf ../html/*.html ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s20.html#docbook-mf) 這里一定要用 TAB，而不能用空格字符 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s20.html#docbook-mf1) 同上 * * * > [[57](ch27s20.html#id3127148)] 在 Emacs 中 **M-x compile** 效果更好，如果有錯誤還能夠直接定位 ## 使用 CSS 定制外觀 DocBook 輸出為 Html 時，如果不使用 CSS 控制，那么它的外觀將比較“樸素” 如果自己寫一個 CSS 未免太麻煩，可以隨便找一個 DocBook 寫的文檔，將里面的 CSS 文件拿來修改[[58](ch27s21.html#ftn.id3127223)] 通過例子簡單介紹下 CSS ``` body { font-family: verdana, tahoma, helvetica, arial, sans-serif; text-align: left; background: #fff; color: #222; margin: 1em; padding: 0; font-size: 1em; line-height: 1.2em } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css01) 選擇符，**body**標記中的內容如果沒有專門指定，都應用花括號中定義的樣式 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s21.html#docbook-css10) 花括號中的內容為樣式定義 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s21.html#docbook-css02) 字體 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s21.html#docbook-css03) 文字左對齊 > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s21.html#docbook-css04) 背景色 > [![6](https://box.kancloud.cn/2016-01-06_568cdb4f32753.png)](ch27s21.html#docbook-css05) 文字色 > [![7](https://box.kancloud.cn/2016-01-06_568cdb4f41fcc.png)](ch27s21.html#docbook-css06) 頁邊距 > [![8](https://box.kancloud.cn/2016-01-06_568cdb4f5948a.png)](ch27s21.html#docbook-css07) 內部頁邊距 > [![9](https://box.kancloud.cn/2016-01-06_568cdb4f68749.png)](ch27s21.html#docbook-css08) 行高 > [![10](https://box.kancloud.cn/2016-01-06_568cdb4f83cf0.png)](ch27s21.html#docbook-css09) 行距 * **em**是相對尺寸，當前字體的尺寸=1em；**px**是絕對尺寸，像素，由顯示器分辨率決定； ??字體默認為 16px 大小，也就是說 1em=16px 看看我們生成的 Html 文件的源碼 ``` <div class="navheader"> <div class="navfooter"> ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css11) 給一個元素指定一個類這里的頁眉和頁腳，使用的都是**div**標記，只不過類不同，怎么樣為它們分別指定樣式呢？在 CSS 文件中找到相關段落： ``` div`.`navheader { border-bottom: 1px solid #dbddec; } div.navfooter { border-top: 1px solid #dbddec; } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css12) 類選擇符，表示類為**navheader**的**div**標記，應用花括號中的樣式如果想對包含某一類的所有標記定義樣式，可以單獨使用類選擇符 ``` .command { color: red; } ``` * 不管**command**這個類出現在什么標記中，它都應用該樣式如果需要對多個不同的標記定義同一個樣式，使用分組選擇符 ``` div.navheader`,` div.navfooter { background: #ecedef; margin: 0; padding: 0.1em .5em; } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css13) 分組選擇符空格為包含選擇符 ``` table tr td { border:dashed #999; text-align: left; } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css14) 表示**table**標記中的**tr**標記中的**rd**標記 ### 代碼塊的樣式我在 DocBook 中使用 **screen** 輸出代碼塊，看看如何定義它的樣式 ``` .screen { color: #000; background-color: #e9e9e9; font-weight: normal; border: 1px dotted #666699; max-height:20em; overflow:auto; } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css20) 定義邊框粗細、類型、顏色。[[59](ch27s21.html#ftn.id3127683)] > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s21.html#docbook-css21) 定義最大高度 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s21.html#docbook-css22) 代碼塊超出上面定義的最大高度時，加入一個滾動條 ### 簡單表格的樣式我用簡單表格來放置一些需要排列整齊的文字 ``` .informaltable table { border:0; border-top:dashed #999; border-width:1px 1px 1px 1px; margin-left: 10px; margin-right: auto; } .informaltable table th, .informaltable table tr td { border-right:0; border-bottom:dashed #999; border-width: 0 1px 1px 0; padding: 0.2em 0.4em 0.2em 0.8em; text-align: left; } ``` > [![1](https://box.kancloud.cn/2015-10-12_561bcb76795ae.png)](ch27s21.html#docbook-css23) 包含選擇符，類為`informaltable`的(div)標記，包含的`table`標記，應用下面的樣式 > [![2](https://box.kancloud.cn/2015-10-12_561bcb768596e.png)](ch27s21.html#docbook-css24) **table**標記設定的邊框為表格頂部和左邊的邊框，取消 > [![3](https://box.kancloud.cn/2015-10-12_561bcb94ee26f.png)](ch27s21.html#docbook-css25) 設定頂部的邊框為點劃線 > [![4](https://box.kancloud.cn/2015-10-12_561bcb9508b82.png)](ch27s21.html#docbook-css26) 分組選擇符，分別選中表頭和表體的單元格 > [![5](https://box.kancloud.cn/2015-10-12_561bcb95133e7.png)](ch27s21.html#docbook-css27) 表格底部和右邊的邊框由單元格設定[[60](ch27s21.html#ftn.id3127830)] > [![6](https://box.kancloud.cn/2016-01-06_568cdb4f32753.png)](ch27s21.html#docbook-css28) 文字對齊 * * * > [[58](ch27s21.html#id3127223)] 這個東西你不想要的時候滿地都是，一旦你想找一個，可能還真找不到，沒關系，可以用我的改。我也是改別人的：） > [[59](ch27s21.html#id3127683)] 邊框類型包括：solid實線、dashed點劃線、dotted虛線、double雙線、groove槽狀、ridge脊狀、inset凹陷、outset凸出 > [[60](ch27s21.html#id3127830)] 確實很別扭，但這不關 DocBook 的事，別忘了我們是通過 CSS 對 Html 進行定義 ## 技巧 ### 關于表格在目錄頁中，會用每個表格的標題來生成表格清單。不希望被收錄的可以使用 informaltable 可以通過在 CSS 中指定 table 和 informaltable 的樣式來定義兩種表格 ### 交叉引用可以放心的先引用，然后再定義被引用的部分。如果被引用的部分沒有被定義，發布的時候 xsltproc 會給出提示 ### calloutlist 自動編號問題 callout 如果不是定義在 screen、programlisting、synopsis 等塊元素中，則下一個 calloutlist 中編號并不會重新開始，而是繼續上次的。經測試，callout 并不需要定義在 screen 等元素中，只要兩個 calloutlist 中間有這些元素隔開就可以了。可以定義一個不常用的元素，如 synopsis，來進行分隔。只要在兩個 calloutlist 之間的任何位置插入一個空標記 <synopsis/> 就可以了當然了，生成的 Html 效果有一點怪異。在 CSS 中加入下面代碼可以隱藏。 ``` .synopsis {display:none;} ``` 盡量把這個標記放在不影響顯示的地方，例如兩個 section 之間；這樣即便意外的顯示，也只顯示在目錄中 ### 斷行符在 param.xsl 文件中加入 ``` <xsl:template match="processing-instruction('linebreak')"> <br/> </xsl:template> ``` 在源文件中加入 ``` <?linebreak?> ``` 生成 Html 時替換為<br> 這里是演示 ### 內部鏈接內部鏈接時，要給結構元素定義 ID，而不要給 title 定義 ID，不然跳轉時會到達錯誤的位置