manual.tm

\use(translator)

\lang[zh-tw]
\title[Text Markup Processor 使用手冊]

\filetoc
\pagelist
\project[manual]

\body[[

\page[0]

\h1(1.)[Text Markup Processor 簡介]

Text Markup Processor (以下簡稱 tmp) 是個以 \link(Python)[http://www.python.
org/] 撰寫的轉譯器架構。

透過 Markup Pack (以下簡稱 pack，同樣以 Python 撰寫) 的協助，它能將
純文字輸入檔轉為各式各樣的輸出內容。

目前唯一隨附的 pack 是 \c[translator]，它能處理最初開發這套工具想要
解決的最主要問題 \mdash 以簡潔的語法，使用 HTML 格式輸出漂亮的中間翻譯稿件。

\h2(1.1.)[輸出入格式]

輸出檔隨 pack 的設計而有所不同，不過輸入檔一概是 UTF-8 編碼的純文字
檔案；檔名可任意選用，但建議以 \c[.tm] 作為原始檔附檔名。

\h2(1.2.)[執行方式]

\boxHead[語法]
\code[[
tmp \b[<輸入檔名>] \[\b[<輸入檔名>], ...\]
]]

\boxHead[範例]
\code[[
tmp manual.tm
tmp toc.tm ch1.tm ch2.tm
tmp *.tm
]]

第一行是將 \c[manual.tm] 轉換成 \c[manual.htm]，也就是輸出本說明檔時必須執行
的指令。

第二行則會將三個指定的檔案一次轉換好，分別存成不同的 \c[.htm] 檔。

第三行則會轉換現行目錄之內，所有副檔名是 \c[.tm] 的檔案。

轉換的過程中，每處理好一個檔案就會顯示對應的檔名；處理檔案的時候如果遇到錯誤
的話，則會顯示第一個發生錯誤的位置，並且繼續處理下一個檔案。目前的架構設計沒有
辦法一次抓出檔案之內所有可能錯誤的地方

\h2(1.3.)[主要語法]

TMP 的語法標籤只有以下兩種主要格式:

\code[[
\\標籤\i[(參數1,參數2,...)]\b[\[]內容\b[\]]

\\標籤\i[(參數1,參數2,...)]\b[\[\[]內容\b[\]\]]
]]

其中只有 \c[\\標籤] 的部分是必要的，參數以及內容都只有在需要用到的時候才需要
附上。

第二種語法 (雙方括號) 的內容之中，如果出現單獨一個

\h3(1.3.1.)[需要跳脫 (escape) 的部分]

tmp 原始碼內需要進行跳脫動作的，只有下面幾個地方:

\ul[
\li[參數列部分]
  \ul[
    \li[如果參數內容用到 \c[,] (逗號)、\c[)] (右圓括號)、\c[\\] (反斜線) 這三個符號的時候，前面必須加上 \c[\\]。]
  ]
\li[單方括號內容部分 (放在 \b[\[] ... \b[\]] 之內的部分)]
  \ul[
    \li[內容用到 \c[\\] 符號的話，前面必須再加上一個 \c[\\] 符號 (避免被解讀成標籤呼叫)。]
    \li[如果內容第一個字是 \c[\[] 的話，可以在前面加上空白或是 \c[\\] 符號 (避免被解讀成雙方括號內容)。]
    \li[內容用到 \c[\]] (右方括號) 的時候，前面必須加上 \c[\\] 符號 (避免提早結束作用範圍)。]
  ]
\li[雙方括號內容部分 (放在 \b[\[\[] ... \b[\]\]] 之內的部分)]
  \ul[
    \li[內容用到 \c[\\] 符號的話，前面必須再加上一個 \c[\\] 符號 (避免被解讀成標籤呼叫)。]
    \li[內容出現連續兩個 \c[\]] 符號 (也就是 \c[\]\]]) 的時候，必須在前面加上一個 \c[\\] 符號 (避免提早結束作用範圍)。]
  ]
\li[標籤部分]
  \ul[
    \li[如果往後緊接著 \c[(] 或是 \c[\[] 符號，卻又不想讓它被解釋成參數列、內容區的話，同樣在前面加上 \c[\\] 即可。]
  ]
]

簡單來說，就是內容使用到語法內的特殊符號、有可能造成疑義誤判的情形之下，就需要
在前面加上 \c[\\] 符號進行跳脫動作。乍看之下有些複雜，不過只需要選對編輯器 (
比如說用 \link(vim)[http://www.vim.org/] 配上語法彩色檔)，進行跳脫就會變得十分
簡易 \mdash 因為會造成誤判的地方，原始碼就會顯示成預期之外的顏色；適當地
補上 \c[\\] 符號之後，原始碼的色彩才會恢復正常。

因此雙方括號很適合在標註程式碼之類，內含不少方括號的內容時使用，如此只需跳脫
連續的右方括號即可，不需要為每個方括號加上 \c[\\]。

\h4(1.3.1.1.)[提早結束標籤判斷範圍]

舉例來說，假設您想以 \c[translator] 這套內附的 markup pack 排出這段文字:

\box[
\lt[]test\gt[]
]

由於 \c[translator] 允許在內容之中使用 XHTML 標籤，因此不能直接依原樣輸入左右
尖括號，而必須以對應的 \c[\\lt]、\c[\\gt] 替代才行。不過，直接寫成 \c[\\lttest
\\gt] 的話，前段會被當成單獨一個標籤解釋；單純以空白隔開、輸入成 \c[\\lt test
 \\gt] 的話，又會在內容之中插入額外的空白:

\box[
\lt test \gt
]

遇到這種情形的時候，有兩種方法可以解決: 使用空白參數或是空白內容。
也就是說，寫成下面這兩行的形式，都可以達成預期的效果:

\code[[
\\lt[]test\\gt
\\lt()test\\gt
]]

兩種寫法的效果完全相同。差異之處只有第一行輸入的時候不必按 \k[SHIFT] 而已 ...
 (所以有人真的會想用第二種寫法嗎)

\h4(1.3.1.2.)[省略方括弧]

寫 HTML 的時候，常常會需要用好幾組標籤同時修飾一段內容，比如說這樣:

\box[
\b\i\u[some fancy styles]
]

在以往這得用上三層巢狀標籤才有辦法解決！就算是拿 \c[translator] 提供的標籤
來寫，堆起來之後也可能會變成這樣:

\code[[
\\b[\\i[\\u[some fancy styles\]\]]
]]

為了簡化這類內容的輸入動作，因此在這種特殊的情形下 \mdash 也就是\b[標籤作用
範圍之內剛好只有一個標籤]的狀況下，允許省略開頭、結尾的方括號，此時標籤會
直接以下一個標籤的全部內容當成作用範圍！

因此現在可以簡寫成這樣，得到相同的效果:

\code[[
\\b\\i\\u[some fancy styles]
]]

當然，這只對\b[具備作用範圍]的標籤才有作用；直接輸出特殊符號、文字的標籤
 (比如說 \c[translator] 的 \c[\\euro] 標籤) 不需要也不受這項功能的影響，後面
可以直接放上其他標籤。

如果因為某些原因，您不希望連寫在一起的幾個標籤被解釋成巢狀關係、而這些標籤
又不具備任何內容的話，您可依樣畫葫蘆用前面提過的標籤範圍結束法把標籤的處理範圍
打斷:

\code[[
\\b[]\\i\\u[some fancy styles]
]]

處理之後會變成下面的結果:

\box[[
\b[]\i\u[some fancy styles]
]]

粗體不見了！但是檢視原始碼會發現，原來 \c[\\b] 標籤裡面沒有任何內容、跑到前面
去了 ... 這樣到底有什麼意義呢？

\h3(1.3.2.)[內建標籤]

tmp 本身內建兩個標籤，其餘功能均由針對特定問題撰寫的 pack 負責提供。

\h4(1.3.2.1.)[\\include]

\boxHead[語法]
\code[[
\\include(\b[\lt[]檔名\gt])
]]

使用這個標籤，就像是以 \c[\b[\lt[]檔名\gt]] 檔案的內容替換掉這個標籤之後再進行處理
一樣。您可使用這個標籤，在許多檔案之內共享一段經常用到，或是有需要同步變更、
維持一致的內容。

\boxHead[範例]
\code[[
\\include(copyright.tm)
]]

\h4(1.3.2.2.)[\\use]

\boxHead[語法]
\code[[
\\use(\b[\lt[]pack 名稱\gt])
]]

此指令會載入指定名稱的 pack 以便應用其中提供的功能。大部分原始碼應該都會
在檔案開頭以這個標籤載入某個 pack，之後再使用這個 pack 所提供的
標籤繼續撰寫往後的內容。

您不能重複載入相同的 pack，此舉將會導致錯誤；但您的確可以載入
複數 pack 並且交替使用其中的功能。pack 的搭配使用法則請參閱各個 pack 所提供的
參考文件。

\h1(2.)[Translator Markup Pack]

這個 markup pack 具備最基本的 XHTML 輔助製作功能，同時還提供一些產生書稿標示
內容的特殊能力 \mdash 因為最初的開發目標，就是讓本程式的作者能快速、簡易地
排出自己希望的書稿樣式。

由於輸出格式採用 XHTML 的關係，標籤組織刻意設計地十分貼近 XHTML，只提供一層
薄薄的包裝、並透過一些預設樣式表達到效果，可說是為了便利現在已在使用 XHTML 的
人所設計的；如果您是這種人的話，可能會發現文稿架構非常、非常地眼熟。

使用 \c[translator] pack 的 tm 檔案典型架構如下 (直接取用本說明檔原始碼
作為範例):

\code[[
\\use(translator)
\\lang[zh-tw]

\\title[Text Markup Processor 使用手冊]

\\filetoc
\\pagelist

\\body[[
  ...
\]]
]]

首先取用 \c[translator] pack，接著指定文件的語系 (\c[\\lang])、
標題 (\c[\\title])，並且打開自動產生目錄 (\c[\\filetoc])、打開分頁模式
產生頁面連結 (\c[\\pagelist]) 等等功能；最後再以 \c[\\body] 組織全篇頁面內容。

由於輸出格式是 XHTML，為了便利起見，除了在特別提及的幾個標籤範圍之內 (比如
說 \c[\\code])，其它地方都可以直接使用 XHTML 標籤；而大多數常用的標籤也
都以 tmp 標籤的形式包裝提供 (如 \c[\\br]、\c[\\b]、\c[\\lt] 等等)，便於您快速
輸入相關內容。

\h2(2.1.)[內文分段]

在處理文字內容的時候，換行會被忽略，連續的兩行會被接在一起；空行則代表新段落
開始。如此有助於原始碼整理。段落的開頭會自動縮排；如果您不希望段落縮排的話，
您可以直接使用 \c[\\p] 標記整個段落。

必須注意的是，為了不加入多餘的換行、段落，因此對於段落開頭、結尾處遇上標籤的
情形會進行特殊處理。大部分情形下應會輸出與您預期相同的結果；如果遇上分段錯誤
 (漏分段) 等等的情形，可嘗試在段落的開頭、結尾各加上一個空白再試試看。

\boxHead[範例]
\code[[
第一段
第二行

第二段

很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段

\\p[
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
]

]]

\boxHead[處理結果]
\box[
第一段
第二行

第二段

很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段
很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段很長的一段

\p[
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落不內縮的段落
]

]

\h2(2.2.)[標籤說明]

\h3(2.2.1.)[頁面選項設定]

\h4(2.2.1.1.)[選擇語系]

您必須使用 \c[\\lang] 標籤指定文件所使用的語系。儘管檔案內容一定以 UTF-8 儲存，
仍然需要設定正確的檔案語系，因為這會影響瀏覽器選用的預設字型、以及文字避頭尾
原則等語系相關特性。如果沒有指定語系的話，就會在處理時產生錯誤訊息。

下面是幾個常用語系的設定:

\table[
\caption[語系範例]
\tr[\th[語系]\th[說明]]
\tr[\th[zh-tw]\td[繁體中文]]
\tr[\th[zh-cn]\td[簡體中文]]
\tr[\th[ja]\td[日文]]
\tr[\th[en]\td[英文]]
]

\boxHead[範例]
\code[[
\\lang[zh-tw]
]]

\h4(2.2.1.2.)[文件標題]

您必須以 \c[\\title] 標籤指定整份文件的標題。如果沒有指定標題的話，就會在
處理時產生錯誤訊息。

\boxHead[範例]
\code[[
\\title[Text Markup Processor 使用手冊]
]]

\h4(2.2.1.3.)[內容組織功能]

 \c[translator] 內建了一些自動組織內容的處理功能，預設不會開啟；若您想要使用
這些功能的話，必須手動加上對應的標籤。

\ul[
\li[\c[\\filetoc]: 自動產生目錄 (→ 請參閱「標題」)]
\li[\c[\\pagelist]: 分頁模式 (→ 請參閱「頁數編碼」)]
]

\h4(2.2.1.4.)[專案]

您可使用 \c[\\project] 標籤指定檔案所屬的專案，此時會在同一目錄下
建立檔名是 \c[<指定名稱>.tpd] 的專案資料檔。

專案資料檔內，會記錄專案內所有檔案的標題別名、頁碼、索引關鍵詞等資料，每次處理
檔案時都會自動更新，便利您在檔案之間進行交叉索引、重複取用專有名詞解釋。
詳情請參閱「\link[=2.2.2.]」以及「\link[=2.2.4.]」等段落。

專案之內的所有檔案必須位於相同目錄之內，此版本尚未支援專案目錄結構。

\h3(2.2.2.)[標題]

標題是以 \c[\\h1] 到 \c[\\h6] 六種標籤加以定義的。如果您先前以 \c[\\build
toc] 打開目錄產生功能的話，頁首的 Metadata 資料區之內就會多出 \b[Table of
 Contents] 這個段落，而所有文內標題都會自動依照階層順序在此建立對應的連結，
方便往後閱覽。

\boxHead[範例]
\code[[
\\h1[Translator Markup Pack]
\\h2[標籤說明]
\\h3[頁面選項設定]
\\h4[標題 4]
\\h5[標題 5]
\\h6[標題 6]
]]

\boxHead[處理結果 (前三大標題的效果請直接參考前段內容)]

\h4[標題 4]
\h5[標題 5]
\h6[標題 6]

在啟動專案功能之後，您可為標題標籤加上參數設定別名，並且稍後在同一個專案之內的
檔案裡面以 \c[\\link] 連結回此一標題。

為標題加上的別名，會變色顯示在標題之前；您可利用這項特點，直接將標題的序號部分
編為別名使用。

\code[[
\\h1(1.)[大標題一]
...
\\link[=1.]
]]

使用上的注意事項則請參照 \link[=2.2.4.] 一節所述。

\h3(2.2.3.)[頁數編碼]

您可以在內容之中以 \c[\\page] 標籤標示目前頁次，頁次會出現在左邊的黃色頁邊範圍
之內。如果您在檔案開頭加上 \c[\\pagelist] 標籤的話，還會自動在頁首建立 \b[Page
 Link] 區域並產生連往各頁開頭的連結，讓您能夠直接跳躍到指定的頁面。

如果在同一個 \c[\\page] 標籤內以逗號列出許多個頁碼的話，即可連續列出這些頁碼，
並且略去這些頁碼之間的頁面分隔線 (作者在遇到橫跨多頁的表格、操作步驟清單等內容
的時候，不想把表格切斷，卻又想保留中途頁碼連結時常用)。

Page Link 位於頁首的 Metadata 資料區之內，您可點選黃色的 Show/Hide
 Metadata 標籤切換本區域顯示與否。

小技巧: 您隨時都能使用瀏覽器的 \k[Home] 鍵跳回頁首資料區。

\boxHead[範例]
\code[[
\\page[i]
\\page[xv]
\\page[1]
\\page[23]
\\page[456]
\\page[7890]
\\page[5,6,7,8,9]
]]

\boxHead[處理結果 (請看左邊)]

\page[i]
\page[xv]
\page[1]
\page[23]
\page[456]
\page[7890]
\page[5,6,7,8,9]

\h3(2.2.4.)[連結]

連結功能由 \c[\\link] 標籤提供。它的作用範圍即是要連結的網址，如果您希望自訂
連結顯示文字的話，只要以參數的形式提供即可。

\boxHead[範例]
\code[[
\\link[http://www.google.com/], \\link(Python 程式語言)[http://www.python.org/]
]]

\boxHead[處理結果]
\box[
\link[http://www.google.com/], \link(Python 程式語言)[http://www.python.org/]
]

在啟動專案功能時，\c[\\link] 標籤也能用來連結加了別名的標題；此時連結文字將
自動取用對應別名的標題全文內容。連結標題別名的語法如下:

\code[[
\\link[=\b[<標題別名>]]
]]

如果所指定的別名還不存在 (別名輸入錯誤；或者是別名所屬的檔案尚未處理，以致於
別名尚未儲存至專案資料檔之內)，就會在處理完成的檔案開頭顯示錯誤訊息，方便您
進行除錯工作。

\boxHead[範例]
\code[[
\\link[=2.2.5.]
]]

\boxHead[處理結果]
\box[
\link[=2.2.5.]
]

\h4(2.2.4.1.)[專案檔案的處理順序]

專案檔案的處理順序是有影響的。簡單來說，在使用 \c[\\link] 標籤造出連結之前，
必須先處理好連結目標所在的檔案，如此才能產生正確的連結內容；然而檔案之間的
交互參照通常十分複雜，整理出適當的處理順序似乎不切實際。

其實有個簡單的做法，那就是\b[處理全部的檔案兩次] \dash 第一次處理將會造出
完整的標題別名、所屬檔案表，第二次處理時則會正確完成所有的連結動作 (而那些真的
錯誤的連結還是會留下警告訊息)。

\h3(2.2.5.)[HTML 特殊字元實體]

 \c[translator] 將 HTML 常用的特殊字元實體改以標籤的形式提供，便於使用。

\table[
\caption[HTML 特殊字元實體]
\tr[
  \th[標籤]
  \th[名稱]
  \th[字元外觀]
  \th[使用例]
  \th[處理結果]
]
\tr[
  \th\b\c[\\br]
  \td[換行]
  \td[&nbsp;]
  \td\c[[A\\br[]B]]
  \td[[A\br[]B]]
]
\tr[
  \th\b\c[\\cent]
  \td[分]
  \td[\cent]
  \td\c[[5\\cent]]
  \td[5\cent]
]
\tr[
  \th\b\c[\\copy]
  \td[版權]
  \td[\copy]
  \td\c[[\\copy 2000 SBT]]
  \td[\copy 2000 SBT]
]
\tr[
  \th[\b[\c[\\deg]]]
  \td[角度量]
  \td[\deg]
  \td\c[[90\\deg]]
  \td[90\deg]
]
\tr[
  \th\b\c[\\euro]
  \td[歐元符號]
  \td[\euro]
  \td\c[[\\euro 50]]
  \td[\euro 50]
]
\tr[
  \th[\b\c[\\lt], \b\c[\\gt]]
  \td[大於、小於符號]
  \td[\lt \gt]
  \td\c[[\\lt[]html\\gt]]
  \td[\lt[]html\gt]
]
\tr[
  \th[\b\c[\\mdash], \b\c[\\dash]]
  \td[長破折號]
  \td[\mdash]
  \td\c[[It's a test \\mdash yeah, really a test.]]
  \td[It's a test \mdash yeah, really a test.]
]
\tr[
  \th\b\c[\\ndash]
  \td[短破折號]
  \td[\ndash]
  \td\c[[I'm at 177\\ndash[]1]]
  \td[I'm at 177\ndash[]1]
]
\tr[
  \th\b\c[\\permil]
  \td[千分比]
  \td[\permil]
  \td\c[[25\\permil]]
  \td[25\permil]
]
\tr[
  \th\b\c[\\plusmn]
  \td[正負]
  \td[\plusmn]
  \td\c[[\\plusmn[]12V]]
  \td[\plusmn[]12V]
]
\tr[
  \th\b\c[\\pound]
  \td[英鎊符號]
  \td[\pound]
  \td\c[[\\pound[]500]]
  \td[\pound[]500]
]
\tr[
  \th\b\c[\\reg]
  \td[註冊商標]
  \td[\reg]
  \td\c[[Linux\\reg]]
  \td[Linux\reg]
]
\tr[
  \th\b\c[\\yen]
  \td[日圓符號]
  \td[\yen]
  \td\c[[\\yen[]7,140]]
  \td[\yen[]7,140]
]
]

\h3(2.2.6.)[簡單的標記]

以下是一些簡單的標記。「簡單」的意思是指，它們只改變一小段文字的外觀，使用時
不進行額外的特殊處理、也不須想太多對版面佈局產生的衝擊。它們大部分也
都與 HTML 直接對應。

\table[
\caption[簡單的標記]
\tr[
  \th[標籤]
  \th[名稱]
  \th[使用例]
  \th[處理結果]
]
\tr[
  \th(l)\b\c[\\b]
  \td[粗體]
  \td\c[\\b\[bold\]]
  \td\b[bold]
]
\tr[
  \th(l)\b\c[\\c]
  \td[定寬 (程式碼)\br[]範圍內的 HTML 會被自動跳脫]
  \td\c[\\c\[<html><title>Hello!</title></html>\]]
  \td\c[<html><title>Hello!</title></html>]
]
\tr[
  \th(l)\b\c[\\i]
  \td[斜體]
  \td\c[\\i\[italic\]]
  \td\i[italic]
]
\tr[
  \th(l)\b\c[\\k]
  \td[模擬鍵盤按鍵]
  \td\c[\\k\[Enter\]]
  \td\k[Enter]
]
\tr[
  \th(l)\b\c[\\nobr]
  \td[標籤範圍之內不斷行]
  \td(c2)[(略)]
]
\tr[
  \th(l)\b\c[\\quote]
  \td[引言]
  \td\c[\\quote\[If it ain't broken, don't fix it.\]]
  \td\quote[If it ain't broken, don't fix it.]
]
\tr[
  \th(l)\b\c[\\r]
  \td[粗體紅標 (強調、警告事項等)]
  \td\c[\\r\[redmark\]]
  \td\r[redmark]
]
\tr[
  \th(l)\b\c[\\u]
  \td[加底線]
  \td\c[\\u\[underline\]]
  \td\u[underline]
]
\tr[
  \th(l)\b\c[\\y]
  \td[黃色底]
  \td\c[\\y\[yellow background\]]
  \td\y[yellow background]
]
\tr[
  \th(l)\b\c[\\o]
  \td[橘色字]
  \td\c[\\o\[orange bold\]]
  \td\o[orange bold]
]
]

\h3(2.2.7.)[表格]

表格是以 \c[\\table] 標籤進行標記的。一份表格是由許多以 \c[\\tr] 標籤
標記的\b[表格橫列]所構成，表格橫列則又是以 \c[\\th]、\c[\\td] 等
標籤所標記的\b[資料格]所組成的。

這兩種資料格之中，\c[\\td] 是一般的資料格；\c[\\th] 則是欄、列的標題，會自動
根據出現的位置顯示成正確的標題外觀。

緊接在 \c[\\table] 標籤之後，您可接著使用 \c[\\caption] 標籤標記整個表格的
標題。這個標題的外觀刻意與 \c[\\boxHead] 設計得十分類似，如此能夠維持內容風格
的一致性。

\h4(2.2.7.1.)[格式化字串]

為了簡潔地控制資料格之內的資料對齊方式，以及資料格的跨欄、跨列設定，此處引入
「格式化字串」的概念；如果以參數的形式為資料格標籤加上格式化字串的話，就會依照
指定的格式顯示資料格的內容。

資料格的格式化字串主要以四個部分構成，分別控制跨欄、跨列、上下對齊、左右對齊；
此四個部分必須\b[依照順序]出現，不需用到相關功能的部分則可直接跳過。如果覺得
格式化字串之內的指定順序不好記憶，不妨試試看「橫豎上下左右」這個口訣 :)

\table[
\caption(c3)[表格的格式化字串]
\tr[
  \th[功能]
  \th[語法]
  \th[意義]
]
\tr[
  \th[跨欄 (column)]
  \td\b\c[c<欄數>]
  \td[使資料格\b[向右]橫跨指定的格數]
]
\tr[
  \th[跨列 (row)]
  \td\b\c[r<列數>]
  \td[使資料格\b[向下]橫跨指定的格數]
]
\tr[
  \th(r3m)[上下對齊]
  \td\b\c[t]
  \td[內容貼齊資料格頂端 (top)]
]
\tr[
  \td\b\c[m]
  \td[內容上下對齊資料格中間 (middle)]
]
\tr[
  \td\b\c[b]
  \td[內容貼齊資料格底部 (bottom)]
]
\tr[
  \th(r3m)[左右對齊]
  \td\b\c[l]
  \td[內容貼齊資料格左側 (left)]
]
\tr[
  \td\b\c[c]
  \td[內容左右對齊資料格中間 (center)]
]
\tr[
  \td\b\c[r]
  \td[內容貼齊資料格右側 (right)]
]
]

\h5[格式化字串，舉例]

 \c[\\th(r)] → 內容靠右對齊的標題。

 \c[\\td(c3c)] → 橫跨三格 (總共佔三格空間)，內容左右正中排列的資料格。

 \c[\\th(r2c2br)] → 橫跨兩欄兩列 (佔用田字形四格)，內容靠右靠下顯示的標題。

\h5[實際表格舉例]

\boxHead[原始碼]
\code[[
\\table[
  \\caption[Table title!]
  \\tr[
    \\th[a long long long long content]
    \\th(r2b)[rowspan 2, bottom]
    \\th[blahugh]
  ]
  \\tr[
    \\th(r)[so this right\\br[]line 2\\br[]line 3]
    \\td(t)[on the top]
  ]
  \\tr[
    \\th[row header]
    \\td[normal data cell?]
    \\td[another one]
  ]
]
]]

\boxHead[處理結果]
\box[
\table[
  \caption(c3)[Table title!]
  \tr[
    \th[a long long long long content]
    \th(r2b)[rowspan 2, bottom]
    \th[blahugh]
  ]
  \tr[
    \th(r)[so this right\br[]line 2\br[]line 3]
    \td(t)[on the top]
  ]
  \tr[
    \th[row header]
    \td[normal data cell?]
    \td[another one]
  ]
]
]

\h3(2.2.8.)[清單]

\h4(2.2.8.1.)[一般清單]

一般清單的功能由 \c[\\ul]、\c[\\ol]、\c[\\li] 這三個與同名 XHTML 標籤功能一樣
的標籤提供。\c[\\ul] 代表無序清單，\c[\\ol] 代表有序清單，而 \c[\\li] 則代表
清單之內的項目。如果需要多層清單的話，只要把清單擺在清單裡面就可以了 (也就是
「巢狀」使用清單)。

\boxHead[範例]
\code[[
\\ul[
  \\li[A]
  \\li[B]
  \\ol[
    \\li[C]
    \\li[D]
  ]
  \\li[E]
  \\li[F]
]
]]

\boxHead[處理結果]
\box[
\ul[
  \li[A]
  \li[B]
  \ol[
    \li[C]
    \li[D]
  ]
  \li[E]
  \li[F]
]
]

\h4(2.2.8.2.)[定義清單]

定義清單，顧名思義，就是用來為一群詞語提供定義、解釋用的。這部分一共以三個
標籤構成: 標記清單本體的 \c[\\dl] 標籤、標記詞語 (term) 的 \c[\\dt] 標籤、
以及標記定義內容 (definition) 的 \c[\\dd] 標籤。

\boxHead[範例]
\code[[
\\dl[
\\dt[TMP]
\\dd[
Text Markup Processor 的縮寫 (或許也隱含著「暫時性解決方案、不嚴謹」之類的
意思？
]
]
]]

\boxHead[處理結果]
\box[
\dl[
\dt[TMP]
\dd[
Text Markup Processor 的縮寫 (或許也隱含著「暫時性解決方案、不嚴謹」之類的
意思？
]
]
]

\h3(2.2.9.)[方塊]

在 \c[translator] 之中的方塊功能是由 \c[\\boxHead] (方塊標題)、\c[\\box] (方塊
本體) 與 \c[\\code] (程式碼方塊) 這三個標籤配合提供的。

由於未必每個方塊都會需要標題，同時顧慮到方塊標題之內使用其他標籤、以及方塊標題
配合其他「類方塊」內容使用的便利性，因此方塊標題並不是 \c[\\box] 標籤的參數，
而是個獨立的標籤。

這幾個標籤除了 \c[\\box] 之外都不需參數，而包含 \c[\\box] 在內的所有標籤，都是
將作用範圍直接變為內容。\c[\\box] 只有一個可以省略的參數，如果指定了這個參數
的話，就會出現與之對應的方塊類型；否則就只會出現一個單調的黑色外框。
目前程式所提供的方塊類型實例、名稱請參閱稍後提供的應用示範。

\h4(2.2.9.1.)[方塊標題與方塊的組合]

方塊標題與方塊的設計並未強迫兩者搭配使用，事實上的確也經常遇到內文出現一個
無標題註解框，或是圖片內容不須多加說明、只須提供標題即可的情形；
而 \c[\\boxHead] 與 \c[\\box] 事實上的確也可以獨立應用。

儘管如此，如果遇到想為方塊加上標題的情形，只要直接將 \c[\\boxHead] 放在
 \c[\\box] 前面，使兩者位於同一行，或是分別放到兩行裡、中間不要留下空行即可
 \dash 如此一來方塊標題與方塊就會自動「黏」在一起，無須多加費心！

\h4(2.2.9.2.)[程式碼方塊]

以 \c[\\code] 標籤標記的程式碼區塊會改用定寬文字顯示，同時保留所有空白、換行
等特殊字元，以便清楚顯示程式碼的內容。

由於忠實保留所有特殊字元的緣故，程式碼區塊之內無法使用 XHTML 語法。不過，稍早
在「簡單的標記」一節內介紹過的標籤不受這個限制影響，在程式碼區塊內仍然可以用來
強調、標記原始碼內容！ (當然，這也代表您仍然必須留意前述的特殊字元跳脫規則，
比如說反斜線前面要記得補上反斜線之類的 ... 仍然沒什麼概念的話，麻煩請回頭複習
一下。)

\boxHead[原始碼]
\code[[
\\code[[
import sys

if __name__ == '__main__':
  if sys.argc < 3:
    print 'Usage: blahblah\\\\n'
    return 1

  if sys.argv[1] && sys.argv[2]:
    \\b[print 'Oh yeah!']
\]]
]]

\boxHead[處理結果]
\box[
\code[[
import sys

if __name__ == '__main__':
  if sys.argc < 3:
    print 'Usage: blahblah\\n'
    return 1

  if sys.argv[1] && sys.argv[2]:
    \b[print 'Oh yeah!']
]]
]

\h4(2.2.9.3.)[各種方塊的應用示範]

\boxHead[原始碼]
\code[[
\\boxHead[程式碼方塊]
\\code[[
#include <iostream>

int main (int argc, char *argv[])
{
    cout << "Hello World!" << endl;
    return 0;
}
\]]

\\boxHead[一般方塊 \\dash 標題裡頭要\\b[耍]\\i[特]\\u[效]當然沒問題]
\\box[
沒加任何參數，所以沒啥特殊的
]

\\boxHead[註解方塊 (comment)]
\\box(comment)[
這是正文的註解內容
]

\\boxHead[編輯註解方塊 (editor)]
\\box(editor)[
這是給編輯部看的註解
]

一小段文字

\\boxHead[圖表內容方塊 (figure)]
\\box(figure)[
這是圖表內容的翻譯、說明
]

又一段文字

\\box(comment)[一個註解方塊 \\dash 請觀察文字段落與方塊、方塊標題之間的排列關係。]

另一段文字

\\boxHead[這是獨立的方塊標題]

再來一行文字

]]

\boxHead[處理結果]
\box[
\boxHead[程式碼方塊]
\code[[
#include <iostream>

int main (int argc, char *argv[])
{
    cout << "Hello World!" << endl;
    \y[return 0;]
}
]]

\boxHead[一般方塊 \dash 標題裡頭要\b[耍]\i[特]\u[效]當然沒問題]
\box[
沒加任何參數，所以沒啥特殊的
]

\boxHead[註解方塊 (comment)]
\box(comment)[
這是正文的註解內容
]

\boxHead[編輯註解方塊 (editor)]
\box(editor)[
這是給編輯部看的註解
]

一小段文字

\boxHead[圖表內容方塊 (figure)]
\box(figure)[
這是圖表內容的翻譯、說明
]

又一段文字

\box(comment)[一個註解方塊 \dash 請觀察文字段落與方塊、方塊標題之間的排列關係。]

另一段文字

\boxHead[這是獨立的方塊標題]

再來一行文字

]

\h3(2.2.10.)[註腳]

文內可使用 \c[\\fn] (footnote) 安插註腳。

註腳會自動進行編號，並且每段統整之後浮動顯示於段落右方。

如果需要特殊註腳標籤的話，只要以第一個參數提供即可，自動編號不會跟著跳號哦！

\boxHead[範例]
\code[[
這是段落\\fn[第一個註腳]這是段落這是段落這是段落這是段落這是段落
這是段落這是段落
這是段落這是段落這是段落這是段落這是段落這是段落這是段落這是段落
這是段落\\fn[很長的註腳\\br[]很長的註腳\\br[]很長的註腳\\br[]很長的註腳\\br[]很長的註腳
很長的註腳很長的註腳]這是段落這是段落這\\fn(譯註)[測試譯註]是段落這\\fn[another]是段落這\\fn(譯註)[再來一個]是段落
這是段落這是段落

下一段\\fn[第三個註腳，應該要躲開上一段的註腳]下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
]]

\boxHead[處理結果]
\box[
這是段落\fn[第一個註腳]這是段落這是段落這是段落這是段落這是段落
這是段落這是段落
這是段落這是段落這是段落這是段落這是段落這是段落這是段落這是段落
這是段落\fn[很長的註腳\br[]很長的註腳\br[]很長的註腳\br[]很長的註腳\br[]很長的註腳
很長的註腳很長的註腳]這是段落這是段落這\fn(譯註)[測試譯註]是段落這\fn[another]是段落這\fn(譯註)[再來一個]是段落
這是段落這是段落

下一段\fn[第三個註腳，應該要躲開上一段的註腳]下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段
下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段下一段

]

文內註腳編號與註腳內容可交互連結，方便查閱。

\h3(2.2.11.)[連結項目]

測試

\link(Python,1)[http://www.python.org/]

測試

\h3(2.2.12.)[TODO: 自動索引]

以 \c[\\kw] (keyword) 指定文內需要排入索引的關鍵字。

\h3(2.2.13.)[TODO: 內嵌數學式]

 \c[\\math] 透過 mimeTeX 輔助，以 TeX 語法內嵌數學式圖檔。

\h3(2.2.14.)[TODO: 專欄]

\column(note)[
沒有標題的備註

]

\column(note,測試)[
有標題的備註

]

\column(tip)[
小技巧

]

\column(caution)[
注意

]

\column(transnote)[
譯註

]

]]