-
Notifications
You must be signed in to change notification settings - Fork 1
/
userguide.cht.txt
5169 lines (4069 loc) · 196 KB
/
userguide.cht.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
= AsciiDoc 使用者指南(中文版) =
Stuart Rackham <[email protected]>
:Author Initials: SJR
AsciiDoc為一個純文字文件的格式，我們可以用這個格式來來撰寫文件如,
短篇文章(articles),說明手冊(manuals),書籍(book)或是UNIX man pages。
所寫成的AsciiDoc檔可以使用asciidoc(1)命令來轉譯成HTML或DocBook之類的標記
AsciiDoc可根據你的需求進行高度的調教、及組態的設定：不論是AsciiDoc源碼檔的語法
或是後端輸出的標記(這些標記幾乎可以是任何一種形式的SGML/XML標記)都可以由使用者
自行客製化或自行擴充。
.關於本文件
**********************************************************************
這實在是一份非常大的文件，我想它應該是有需要重整成入門手冊、FAQ、快速
參考文件、正式參考文件…等等。
如果你還是個AsciiDoc的新手的話，你可讀這一段跟<<X6,讓我們開始吧！>>這
一段，然後看一下AsciiDoc源碼檔( `.txt` 檔)的一些範例。這些範例可以在我
們釋出的發行版本裡面的 `doc` 目錄下找到。
**********************************************************************
== 導論 ==
AsciiDoc是一個純文字格式、一個人們可以輕易的讀/寫的格式，只要使用
asciidoc(1)命令，可以轉成DocBook或HTML格式。
你可以直接透過asciidoc(1)指令將AsciiDoc文件直接轉成HTML格式。或者使用
asciidoc(1)的DocBook輸出，又或者使用AsciiDoc裡面a2x(1)這個程式來產生PDF、
EPUB、DVI、LaTeX、PostScript、man page、HTML…等格式。
AsciiDoc格式本身就是一個非常有用的一種表示格式：
因為AsciiDoc的標記很簡單也很直覺，這樣一來就可以很容易的閱讀、查驗、與編
輯。
AsciiDoc程式也很輕巧：程式主要由一支Python script及一些組態設定檔所組成。
要把AsciiDoc格式的檔案轉成DocBook或HTML格式，除了asciidoc(1)命令和
python直譯器之外就不需要其他程式了。請看下文的<<X11, AsciiDoc文件範例>>。
文件中文字標記的慣例純屬個人愛好：
如果預設的語法不合你的意的話你也可以定義你自己專用語法。這可以透過編輯
asciidoc(1)組態檔(這些組態檔都是普通的文字檔而已)來完成。
你也可以建立你專屬的組態檔，來轉譯AsciiDoc文件到任何以SGML/XML標記的後
端格式。
asciidoc(1)伴隨了一群的組態檔用來把不同的AsciiDoc文件類型(專題文章(article)、
書籍(book)、man page)轉譯成HTML或DocBook的後端格式。
.我對AsciiDoc的期盼
**********************************************************************
DocBook幾乎已成為現今Open Source的文件的標準了。但是，DocBook實在是一
個複雜的語言，它的標記很難讀，也很難直接寫 -- 我發現我過去花了許多時間
在打字，打這些標記，也花了許多時間在查參考文件跟修改文法上的錯誤，花在
上面這些事的時間，甚至比我真正在寫文章的時間還多。
**********************************************************************
[[X6]]
== 讓我們開始吧！ ==
=== 安裝AsciiDoc ===
在 `README` 和 `INSTALL` 這兩個檔案裡有關於安裝前需知和安裝程序。套件製作者
請看一下 <<X38,套件製作者注意事項>>。
[[X11]]
=== AsciiDoc文件範例 ===
最好也最快了解AsciiDoc的方式就是去AsciiDoc網站看上面所發佈出來的範例：
- 在AsciiDoc的首頁 http://www.methods.co.nz/asciidoc/ 上，有連結連到
相關的範例。而在畫面左邊的側邊欄中你可以點一下 'Page Source' 就可以
看到該範例的源碼。
- 另外，在所釋出版裡面的 `./doc` 目錄下，你可以看一看裡面的 `.txt` 源
碼並相對應該源碼所產生出來的HTML檔跟DocBook的XML檔。
== AsciiDoc文件類型 ==
AsciiDoc的文件類型有三類：專題文章(article)、書籍(book)和manpage。這三類的文
件都使用相同的的AsciiDoc格式，但彼此間還是略有不同。若你對DocBook很熟的話，你
大概已經注意到AsciiDoc文件類型對應到相同名字的DocBook文件類型)。
使用asciidoc(1)命令時，用 `-d` (`--doctype`)選項來指定AsciiDoc的文件
類型，預設的文件類型為 '專題文章(article)' 。
習慣上，我們使用 `.txt` 這個副檔名作為AsciiDoc文件的副檔名。
=== 專題文章(article) ===
主要是短文，主題性專文，或一般性的文章。你可以在AsciiDoc釋出版裡面
`.doc/article.txt` 找到一些範例。
AsciiDoc定義了標準DocBook文件用的前頁(frontmatter)及後頁(backmatter)
<<X93,區段標記模版>> 如：附錄(appendix)，摘要(abstract)，參考書目(bibliography)
，詞彙表(glossary), 索引(index))。
=== 書籍(book) ===
書籍跟專題文章所使用的格式一樣，但不同的地方如下：
- 在分部藉籍中部標題是<<X17,最上層標題>> (與書籍標題同階層)。
- 有些區段(section)是book才有的例如：前言(preface)及版權頁(colophon)。
通常書籍文件會用來產生DocBook的輸出因為DocBook處理器會自動產生註腳，目錄，表格目錄，
圖示目錄，範例目錄及索引。
AsciiDoc定義了標準DocBook文件用的前頁(frontmatter)及後頁(backmatter)
<<X93,區段標記模版>> 如：附錄(appendix)，致謝(dedication)，前言(preface)，
摘要(abstract)，參考書目(bibliography)，詞彙表(glossary), 索引(index)，
版權頁(colophon))。
.書籍文件範例
書籍(Book)::
請參考AsciiDoc釋出版中的 `./doc/book.txt` 文件。
分部書籍(Multi-part book)::
請參考AsciiDoc釋出版中的 `./doc/book-multi.txt` 文件。
=== manpage ===
此類型文件是用來產生roff格式的UNIX man page。AsciiDoc的manpage
文件會找尋特殊的標題，並用一些傳統分段的命名慣例來命名 -- 詳細內容請
參考<<X1,Manpage Documents>>。
[[X33]]
=== xhtml11 ===
asciidoc(1)預設的後端為 `xhtml11` ，它是XHTML 1.1的標記並使用CSS2為其
樣式。預設的輸出檔的副檔名為 `.html` 。'xhtml11' 的文件的產生將受下列
選項的影響而不同(在產生XHTML時，預設的行為是不產生分段編號(section numbers)，
也不產生內嵌的CSS而且也沒有警告圖示的連結):
[[X35]]
==== Stylesheets ====
AsciiDoc的XHTML輸出將使用CSS2樣式表。這個樣式表可以在釋出版中的
`./stylesheets/` 目錄中找到。
[IMPORTANT]
=====================================================================
所有的瀏覽器都有一些CSS怪癖(CSS quirks)，但是Microsoft's IE6實在有太
多疏漏跟錯誤了，所以我們在作XHTML後端處理時用 `xhtml11-quirks.css`
這個樣式表跟 `xhtml11-quirks.conf` 這個組態檔來實作一些為著IE6的權宜
之計。不過，如果你不使用IE6的話，可以在命令列下 `--attribute quirks!`
來忽略這個樣式表跟組態檔。
=====================================================================
預設的 'xhtml11' 樣示表：
`./stylesheets/xhtml11.css`::
主要的樣式表。
`./stylesheets/xhtml11-manpage.css`::
此樣式表用來產生manpage的文件類型。
`./stylesheets/xhtml11-quirks.css`::
此樣式表含了許多為了與IE6相容的修正。
你可以使用 'theme' 屬性來選用其他的樣式表。舉列來說，如果你在命令列下
`-a theme=foo` 則會使用 `foo.css` 、 `foo-manpage.css` (和 `foo-quirks.css`
，如果有啟用quirk mode的話) 這些樣式表，來取代原本預設的樣式表。
你也可以使用 'stylesheet' 屬性來引入附加的樣式表在XHTML文件中。舉例來
說，在命令列使用 `-a stylesheet=newsletter.css` 會使用 `newsletter.css`
這個樣式表。
=== html4 ===
使用此後端將產生不帶樣式的HTML 4.01 Transitional標記。
== 文件結構 ==
一份AsciiDoc文件由一連串的<<X8,塊狀單元>>所組成，由一個文件標頭(可有可無)開始
、緊接著是前言(可有可無)，前言之後就是零個或多個文件分段。
幾乎零個以上的元素的任意組合都可以構成一份有效的AsciiDoc文件：一份文件可
以是一句話也可以是一本分成好幾部的書。
=== 塊狀單元 ===
塊狀單元由一行或多行的文字所組成，而一個塊狀單元也可以包含許多其他塊
狀單元。
AsciiDoc的塊狀結構大略的歸納起來，如下所示
footnote:[這只是一個大概的概覽，並不是一個嚴謹的語法定義]：
中文版
文件 ::= (標頭?,前言?,分段*)
標頭 ::= (標題,(作者列,修訂版列?)?)
作者列 ::= (作者名,(作者中間的名字?,作者姓氏)?,電子郵件地址?)
修訂版列 ::= (修訂版號?,日期)
前言 ::= (分段本體)
分段 ::= (標題,分段本體?,(分段)*)
分段本體 ::= ((區塊標題?,區塊)|區塊巨集)+
區塊 ::= (文章分段,分隔區塊|條列|表格)
列表 ::= (彈型列表|編號型列表|標籤型列表|Callout列表)
彈型列表 ::= (列表項)+
編號型列表 ::= (列表項)+
Callout列表 ::= (列表項)+
標籤型列表 ::= (列表條)+
列表條 ::= (列表標籤,列表項)
列表項 ::= (列表項文字,(列表|列表段|列表延續))
英文版
Document ::= (Header?,Preamble?,Section*)
Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
Preamble ::= (SectionBody)
Section ::= (Title,SectionBody?,(Section)*)
SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
Block ::= (Paragraph|DelimitedBlock|List|Table)
List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList ::= (ListItem)+
NumberedList ::= (ListItem)+
CalloutList ::= (ListItem)+
LabeledList ::= (ListEntry)+
ListEntry ::= (ListLabel,ListItem)
ListLabel ::= (ListTerm+)
ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
其中：
- '?' 表示出現零次或一次， '+' 表示出現一次或多次， '*' 表示出現零次
或多次。
- All block elements are separated by line boundaries.
- `BlockId`, `AttributeEntry` 及 `AttributeList` 這些塊狀單元(文件中看
不到)幾乎可以在任何地方出現。
- There are a number of document type and backend specific
restrictions imposed on the block syntax.
- 以下所列元素將不允許含有空白列：標頭(Header)、標題(Title)、文章分段
(Paragraph)、列表項文字(ItemText)。
- A ListParagraph is a Paragraph with its 'listelement' option set.
- A ListContinuation is a <<X15,list continuation element>>.
[[X95]]
=== 標頭(Header) ===
標頭必含了一份文件的標題還有(可有可無)作者及文件版本號的資訊：
- 標頭是可有可無的，但是一旦有的話一定在一個文件的最開頭<<X17,標題>>.
- 註解跟<<X18,屬性項目(attribute entries)>>可以放在標頭之前。
- 作者資訊跟版本號資訊(這兩者都可有可無)必需緊跟在標頭標題之後。
- 標頭可包含一些屬性項目。
- 標頭必需跟在它之後的內容用一個以上的空白行隔開。
這邊我們用一個例子來看一下AsciiDoc文件的標頭：
Writing Documentation using AsciiDoc
====================================
Joe Bloggs <[email protected]>
v2.0, February 2003:
Rewritten for version 2 release.
作者資訊列包含作者姓名後面跟著作者的電郵信箱(沒有也沒關系)。正式的格式如下：
firstname[ [middlename ]lastname][ <email>]]
舉例來說，擺放的順序是這樣，名字的後面接著是中間名(可有可無)在來是姓在來是電郵位址。
若是名字、中間名、姓由多個字組成，可用底線字元把字與字之間隔開。電郵位址放在最後面
必須以方框號<>隔開。
下面有一些作者資訊列的範例：
Joe Bloggs <[email protected]>
Joe Bloggs
Vincent Willem van_Gogh
若是作者資訊列的格式並不符合上述格式則整列都會視為作者的名字
文件版本號列(可有可無)跟在作者資訊列之後，可以是下列兩種格式之一：
. 一個文件版本號，後面跟著一個修訂日期，然後是修訂備註(這三個資訊都可有可無)：
* 文件版本號之後必需跟著一個逗號。
* 文件版本號內必需至少包含一個數字字元。
* 在第一個數字字元之前的非數字字元將被捨棄。
* 修訂備註之前必需有一個冒號。
修訂備註的內容是從冒號之後算起到下一個空白列(或下一個屬性項目)為止。內容本身
可進行一般的文字替換。
* 若是文件版本號或是修訂備註有設置，而修訂日期並沒有設則會根據 'docdate' 屬性的
值來設定修訂日期的值。
. 一個 RCS/CVS/SVN $Id$ 標記 (假設有使用 $Id$ 修訂標記則標頭的作者資訊列可省略)。
下面列出一些標頭的文件版本號列：
v2.0, February 2003
February 2003
v2.0,
v2.0, February 2003: Rewritten for version 2 release.
February 2003: Rewritten for version 2 release.
v2.0,: Rewritten for version 2 release.
:Rewritten for version 2 release.
你可以在下Asciidoc(1)命令時使用 `-a` (`--attribute`)這個命令列選項，在此選項之後帶入
'revnumber','revremark', 'revdate', 'email', 'author', 'authorinitials','firstname'
及 'lastname' 這些屬性，可以覆寫掉原本的設定值。舉例來說：
$ asciidoc -a revdate=2004/07/27 article.txt
'revnumber' 屬性可以是一個RCS/CVS/SVN的$Id$標記。
Attributes can also be added to the header for substitution in the
header template with <<X18,屬性項目>> elements.
[[X87]]
==== 其他的文件標頭資訊 ====
可以使用 'docinfo' 檔來引入額外的meta-data資訊在輸出檔的標頭中。
- docinfo檔的命名如同AsciiDoc源碼檔一個但是多了一個 `-docinfo` 的字尾。例如，若源碼檔叫
`mydoc.txt` 則其docinfo檔應命名成 `mydoc-docinfo.xml` (給DocBook輸出用)或是
叫 `mydoc-docinfo.html` (給HTML輸出用)。
- 你需要使用AsciiDoc的 'docinfo' 屬性來含入docinfo檔。下面的範例中第一個例子中會把
`mydoc-docinfo.xml` 這個docinfo檔包在DocBook的 'articleinfo' 元素中；第二個例子會
含入 `mydoc-docinfo.html` 這個docinfo檔在HTML的 'header' 元素中：
$ asciidoc -a docinfo -b docbook mydoc.txt
$ asciidoc -a docinfo -b html4 mydoc.txt
docinfo檔的內容取決於輸出的形式：
HTML::
Valid 'head' child elements. Typically 'style' and 'script' elements
for CSS and JavaScript inclusion.
DocBook::
Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines
numerous elements for document meta-data, for example: copyrights,
document history and authorship information. See the DocBook
`./doc/article-docinfo.xml` example that comes with the AsciiDoc
distribution. The rendering of meta-data elements (or not) is
DocBook processor dependent.
[[X86]]
=== 前言、序文(Preamble) ===
前文(或序文)是一個不需要標題的段落，位於文件標頭跟第一個分段的標題之間。
前文(或序文)可有可無，沒有也沒關系。
=== 區段(Sections) ===
除了文件標題(level 0)之外，AsciiDoc支援了四層的區段階層：1(top)到4(bottom)。
區段階層以區段<<X17,標題>>為界。各個區段會使用組態檔中的<<X93,區段標記模版(
section markup templates)>>來轉譯。AsciiDoc會產生下列<<X60,內在屬性>>，這些
屬性會在區段標記模版中被用到：
level::
`level` 屬性為區段階層數，一般來說，就是指<<X17,標題>> 階層數(1..4)。
不過，若是 `leveloffset` 屬性有定義的話它的值會被加進 `level` 屬性裡。
`leveloffset` 屬性在作<<X90,文件合併>>很有用。
sectnum::
命令列選項 `-n` (`--section-numbers`) 將產生 `sectnum` (區段編號,section number)屬性。
`sectnum` 屬性會在HTML輸出中作區段編號(DocBook的區段編號將由DocBook toolchain命令自動處理)。
[[X93]]
==== 區段標記模版(Section markup templates) ====
區段標記模版在AsciiDoc組態檔中定義。它定義了在輸出檔中的標記為何。區段標記
模版的名稱有下列衍伸(in order of precedence)：
1. 從標題的第一個(在位置上第一個)屬性而得或從 'template' 屬性而得。舉例來說，
下列三個區段標題在功能上是一樣的：
+
.....................................................................
[[terms]]
[glossary]
List of Terms
-------------
["glossary",id="terms"]
List of Terms
-------------
[template="glossary",id="terms"]
List of Terms
-------------
.....................................................................
2. 當標題文字與組態檔中的<<X16,`[specialsections]`>>項目相符合時。
3. 若都不符合上面二者則使用 `sect<level>` 模版作為預設模版。
(`<level>` 為一個數字範圍從1到4)。
除了一般的區段模版名稱('sect1', 'sect2','sect3', 'sect4')之外，AsciiDoc還有下列給前頁
(frontmatter)，後頁(backmatter)及其他區段的特殊模版： 'abstract', 'preface', 'colophon',
'dedication', 'glossary', 'bibliography','synopsis', 'appendix', 'index' 。
這些特殊區段模版會產生出相對應的Docbook元素出來；若是對HTML輸出則會預設為 'sect1' 區段
模版。
==== 區段ID(Section IDs) ====
若沒有明確設置區段的區段ID則它的ID將由區段標題合成而來。這個設計主要的用意是在
確保目錄連結(permalinks)的一致性：persistence 遺失的區段ID在該頁 *載入後* 將由
JavaScript TOC generator動態產生。If you link to a dynamically generated TOC
address the page will load but the browser will ignore the (as yet
ungenerated) section ID.
ID的產生將使用下述演算法：
- 把標題中非數字的字元都用底線取代。
- 去掉頭、尾的底線字元。
- 轉成小寫字元。
- 在最開頭置入 `idprefix` 屬性的值(此時的這個名稱應該沒有任何的可能跟其他
名稱撞名)。若 `idprefix` 屬性並未定義，則在前面加一個底線。
- 如果有一個名稱跟自動產生出來的區段ID一樣，則在後面加一個數字作後綴
(`_2`, `_3` ...)。
舉例來說， 'Jim's House' 這個標題將產生 `_jim_s_house` 這個ID。
區段ID的合成可以用解除 `sectids` 屬性來關閉。
[[X16]]
==== 特殊區段標題 ====
AsciiDoc有一個機制可以將一些事先定義好的區段標題很神奇的對應到特定的區段
標記模版。比如說下面這個標題 'Appendix A: Code Reference' 就會自動使用
'appendix' 這個<<X93,區段標記模版>>。關於標題跟模版名稱怎麼定義都定義在
AsciiDoc的語言組態檔(`lang-*.conf`)中的 `[specialsections]` 段裡。
區段的內容格式長的大概像是這樣：
<title>=<template>
`<title>` 是一個Python的正規表示式而 `<template>` 則是組態檔中標記模版中的
一個名稱。If the `<title>` matches an AsciiDoc document section title then the backend output is
marked up using the `<template>` markup template (instead of the
default `sect<level>` section template). The `{title}` attribute value
is set to the value of the matched regular expression group named
'title', if there is no 'title' group `{title}` defaults to the whole
of the AsciiDoc section title. If `<template>` is blank then any
existing entry with the same `<title>` will be deleted.
.特殊區段標題 vs. explicit template names
*********************************************************************
AsciiDoc有兩種機制來標示非預設的區段標記模版：你可以使用 'template' 屬性
，明確的標出模版名稱，或是使用 'special section titles' 間接標出來。
不過還是比較建議使用<<X93,區段模版(section template)>>屬性來標示。
使用 'special section titles' 有下列幾點壞處：
- They are non-obvious, you have to know the exact matching
title for each special section on a language by language basis.
- Section titles are predefined and can only be customised with a
configuration change.
- The implementation is complicated by multiple languages: every
special section title has to be defined for each language (in each
of the `lang-*.conf` files).
Specifying special section template names explicitly does add more
noise to the source document (the 'template' attribute declaration),
but the intention is obvious and the syntax is consistent with other
AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
Special section titles have been deprecated but are retained for
backward compatibility.
*********************************************************************
=== 列內單元(Inline Elements) ===
<<X34,列內文件元素>>被用來標記文字格式及各樣的文字替換。列內元素及其語法定義
在asciidoc(1)的組態檔中。
下面我們列出AsciiDoc中，列內單元預設將以下列順序被處理：
特殊字元(Special characters)::
這些字元在後端標記要跳脫特殊字元的使用(典型的特殊字元有 `<`, `>`, 及 `&` )。
請參考組態檔中的 `[specialcharacters]` 分段。
引號(Quotes)::
這些字元被用來標記單字跟片語，通常是用在字元的格式化上面。請參考組態檔
中的 `[quotes]` 段。
特殊字(Special Words)::
挑出單字或片語來標記而不需要額外標註。請參考組態檔中的 `[specialwords]` 分段。
替換文字(Replacements)::
每一個替換文字都定義了一個字或一個片語AsciiDoc會找尋相對應的替換文字來替換。
請參考組態檔中的 `[replacements]` 分段。
屬性參照(Attribute references)::
文件的屬性名稱由方括號所框住(表示參考到一個屬性)，它會替換成
相對應的屬性值。
列內巨集(Inline Macros)::
列內巨集會根據組據檔中參數化的內容來替換。
== 文件處理 ==
AsciiDoc源碼文件如何被讀入及處理，將有下列步驟：
1. 首先解析文件的 '標頭(Header)' ， 標頭內的參數值會把組態檔中 `[header]` 範本中
的值給取代掉，因為這些值才是之後真正在輸出檔中的值。
2. 接著每一個文件的 '分段(Section)' 都會被處理，把其構成要素轉譯到輸出檔中。
3. 最後，組態檔中 `[footer]` 範本段會被取代掉然後寫入輸出檔中。
當asciidoc(1)遇到一個塊狀單元時會用下列順序來確定其形態：(區段)標題、
塊狀巨集、列表、分界區塊、表格、屬性項目、屬性列表、區塊標題、文章分段。
預設的文章段落定義 `[paradef-default]` 是最後一個核對的項目。
了解文件解析的順序會幫助你設計出正確(不會模擬兩可)的巨集、列表跟區塊的語法
規則。
在塊狀元素裡面進行每一列的替換，會用下列預設的順序來替換：
1. 特殊字元(Special characters)
2. 引言(Quotes)
3. 特殊字(Special words)
4. 替換文字(Replacements)
5. 屬性(Attributes)
6. 列內巨集(Inline Macros)
7. 替換文字2(Replacements2)
上述所提到的替換，可能在標題(Title)、文章分段(Paragraph)、分隔區塊(DelimitedBlock)中進行，
至於替換的順序及怎麼替換則由組態檔中的參數來決定。
#Unquoted text#::
把\#井字號放在文字的兩端#將不會有任何效果，
Placing \#hashes around text# does nothing, it is a mechanism
to allow inline attributes to be applied to otherwise
unformatted text.
New quote types can be defined by editing asciidoc(1) configuration
files. See the <<X7,Configuration Files>> section for details.
.引用文字之行為(Quoted text behavior)
- 引用行為無法交錯。Quoting cannot be overlapped.
- 不同的引用形式可以可以巢狀內嵌。Different quoting types can be nested.
- To suppress quoted text formatting place a backslash character
immediately in front of the leading quote character(s). In the case
of ambiguity between escaped and non-escaped text you will need to
escape both leading and trailing quotes, in the case of
multi-character quotes you may even need to escape individual
characters.
[[X96]]
==== 引用文字之屬性Quoted text attributes
Quoted text can be prefixed with an <<X21,attribute list>>. The first
positional attribute is translated by AsciiDoc to an HTML 'span'
element 'class' attribute or a DocBook 'phrase' element 'role'
attribute.
DocBook XSL Stylesheets translate DocBook 'phrase' elements with
'role' attributes to corresponding HTML 'span' elements with the same
'class' attributes; CSS can then be used
http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
generated HTML].
Thus CSS styling can be applied to both DocBook and AsciiDoc generated
HTML outputs from the same AsciiDoc source. You can also specify
multiple class names separated by spaces. Examples:
[red]#obvious#
[big red yellowback]*very obvious*
The following CSS rules for 'big', 'red' and 'yellowback' class names
could be used to style HTML outputs generated from the previous
examples:
span.big { font-size: 2em; }
span.red { color: #e3372e; }
span.yellowback { background: #faf519; }
[[X52]]
==== 限制型引號形式(Constrained)與非限式型引號形式(Unconstrained Quotes)
實際上只有兩種引號型式：
===== 限制型引號形式(Constrained quotes) =====
被引號框住的文字必需以空白字元作邊界區隔，例如一個單字或一個片語。這也
是我們之前所討論比較常見的引號型式。
===== 非限式型引號形式(Unconstrained quotes) =====
非限制型引號形式並沒有邊界條件的限制，也就是說兩邊不一定要有空白字元為界
，可以放在一列文字的任何地方。為了一致性的考量，也為了方便使用，非限制型
所使用的引號為**兩個**限制型引號所使用的符號( `_` ， `*` ， `+` `#` )，如下例：
__unconstrained emphasized text__
**unconstrained strong text**
++unconstrained monospaced text++
##unconstrained unquoted text##
下面這個範例中強調了字母F：
**F**ile Open...
=== 上標(Superscripts)與下標(Subscripts) ===
將 \^脫字符號(carets)放在兩端^ 會則此段文字作上標，而將\~波浪符號(tilde)放在兩端~
則會將此段文字作下標。舉例來說，下面這一列：
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~
輸出後看起來是這樣：
e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~
上標與下標的實作是透過<<X52,非限制型引號形式>>來達成的。也可以在在最前面
用backslash來跳脫。而且前面也可以放一個屬性列表。
=== 斷行(Line Breaks) ===
在一列的最後(該列要有內容，不是空列)若放一個加號，並且加號之前有至少一個空白字元
將產生一個斷行。對於HTML輸出它會產生一個(`br`) tag，而對於DocBook輸出它會產生一個
客製化的XML `asciidoc-br` 處理指令。這個 `asciidoc-br` 處理指令會由<<X43,a2x(1)>>
來進行。
=== 分頁(Page Breaks) ===
若有一列有超過三個\<字元組成(`<<<`)會在DocBook的輸出及列印出來的HTML輸出中
硬產生一個分頁。對於HTML輸出它會使用CSS `page-break-after` property達成，而
對於DocBook輸出會使用客製的XML `asciidoc-pagebreak` 處理指令來達成。這個
`asciidoc-pagebreak` 處理指令會由<<X43,a2x(1)>>來進行。
硬作分頁的作法有時很方便，不過一般的通則還是建議讓你的頁面處理器來幫你產生分頁。
=== 尺規(Rulers) ===
一個由三個以上撇號字元(也有人翻成省略符號，apostrophe)以上所組成的列將產生
一個尺規列。若是輸出成HTML則一個尺規列將產生(`hr`) tag。輸出成DocBook的話會用
一個客製化的XML `asciidoc-hr` 處理指令來處理。 `asciidoc-hr`
處理指令將由<<X43,a2x(1)>>執行。
=== 跳格(Tabs) ===
在預設的情況下，跳格字元會被轉譯成8個空白字元。你可以在組態檔的
`[miscellaneous]` 段中設定 'tabsize' 這個項目，來決定跳格字元擴展的大小。
不過這個值可以在使用 `include` 巨集的屬性列表有 'tabsize' 屬性時被覆寫。
舉例如下：
include::addendum.txt[tabsize=2]
跳格字元要表示幾個空白的大小也可以使用命令列選項來指定，例如
`--attribute tabsize=4` 。
=== 替換文字(Replacements) ===
下列的替換文字已經定義在AsciiDoc預設的組態中：
(C) 版權所有， (TM) 商標， (R) 註冊商標， -- 強調用的破折號，
... 省略符號， -> 右箭頭， <- 左箭頭， => 雙槓右箭頭， <= 雙槓右箭頭。
輸出後看起來是這樣：
(C) 版權所有， (TM) 商標， (R) 註冊商標， -- 強調用的破折號，
... 省略符號， -> 右箭頭， <- 左箭頭， => 雙槓右箭頭， <= 雙槓左箭頭。
你也可以在AsciiDoc源碼文件中含入任何的屬性參考項目。例如：
➊ ¶
會輸出成：
➊ ¶
如果要讓這個替換文字照著字面輸出，請在前面加上back-slash來跳脫。
在<<X7,組態檔>>這裡會說明如何設定你自己的替換文字。
=== 特殊字(Special Words) ===
在組態檔中的 `[specialwords]` 段定義了一些特別的字，這些字會自動被標記，而不用
特別作記號。
在<<X7,組態檔>>中會說明如何增加或換掉特殊字。
[[X17]]
== 標題 ==
文件標題(Document title)及區段標題(Section title)可以是下列兩種格式之一：
=== 雙列式標題 ===
一個雙列式標題由一個標題列和一個底線列所組成(從一列的最左邊開始)。底
線列由一連串連續字元所組成其長度與其上的標題列等長(或更長)，不過至少
都要2 個字元。
預設的底線列所對應的文件階層如下：
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
舉例如下：
Level One Section Title
-----------------------
Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~
[[X46]]
=== 單列式標題 ===
單列式標題也就是由一列標題所組成。不過在標題的兩端有相同長度(
不同的長度反應出文件的不同階層)的等號字元(稱之為分隔符號)，下面有
一些例子：
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
[NOTE]
=====================================================================
- 標題本身和分隔符號之間至少要有一個空格。
- 最右邊的分隔符號可有可無。
- 單列式標題的語法可以透過組態檔進行變更。(編輯組態檔中
`[titles]` 段的 `sect0`...`sect4` 項目)
=====================================================================
=== 浮動式標題 ===
若設定標題的第一個屬性(在位置上第一個)或是設定 'style' 屬性為 'float'
則會產生一個浮動式標題。浮動式標題最後看起來的樣子就像一般的區段標題一
樣不同的地方在浮動式標題並不需要跟一個文字塊有關系，並且浮動式標題也不
屬於一般的區段階層之中。浮動式標題也可用在一些“有區塊標題是不對的“的狀
況，像是：示範用途的邊欄區塊或是警示區塊。例如：
[float]
The second day
~~~~~~~~~~~~~~
浮動式標題並不會出現在文件目錄中。
[[X42]]
== 區塊標題 ==
一個 '區塊標題(BlockId)' 是由一個句號開頭的標題文字。通常會用在文章的
一段之後，或是分隔區塊(DelimitedBlock)、列表(List)、表格(Table)、區塊
巨集(BlockMacro)之後。下面這個例子：
........................
.注意事項
- 注意事項1。
- 注意事項2。
.Notes
- Note 1.
- Note 2.
........................
會顯示成這個樣子：
.注意事項
- 注意事項1。
- 注意事項2。
.Notes
- Note 1.
- Note 2.
[[X41]]
== BlockId元素 ==
一個 'BlockId' 是一個單列元素，其內容就是兩個方框號包著一個獨一的識別字
所構成。通常用它來指派一個特殊的識別記號給其後接著的塊狀元素。例如：
[[chapter-titles]]
Chapter titles can be ...
上面這個例子給這個文字段落一個識別記號叫作 'chapter-titles' ，這樣一來，
我們就可以在別的地方用下列這個方式來參照到這個段落，例如：
`<<chapter-titles,chapter titles>>`.
'BlockId' 元素可以使用在標題、文章段落、列表、分隔區塊，表格及BlockMacro elements中。
BlockId元素設置了 `{id}` 屬性，這可用在後面的區塊的標記模版中作替換之用。
如果有給第2個參數的話，其值會設給 `{reftext}` 屬性作為其值，這個值會成為
DocBook的 `xreflabel` 屬性的值。
'BlockId' 元素與<<X30,anchor inline macro>>具有相同的語法及功用。
[[X79]]
== 屬性列表元素(AttributeList Element) ==
一個 '屬性列表' 區塊元素就是自成一列的<<X21,屬性列表 list>>：
- '屬性列表' 屬性只會作用在其後緊跟著的塊狀元素 -- the attributes are made available to the
block's markup template.
- 多個連續的 '屬性列表' 元素會照其出現的順序累加的併在一起。
- 順序上通常第一個列表上的屬性會用來指定後面接著的元素的<<X23,style>>。
=== 屬性值的替換 ===
By default, only substitutions that take place inside attribute list
values are attribute references, this is because not all attributes
are destined to be marked up and rendered as text (for example the
table 'cols' attribute). To perform normal inline text substitutions
(special characters, quotes, macros, replacements) on an attribute
value you need to enclose it in single quotes. In the following quote
block the second attribute value in the AttributeList is quoted to
ensure the 'http' macro is expanded to a hyperlink.
---------------------------------------------------------------------
[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
_____________________________________________________________________
Sir, a woman's preaching is like a dog's walking on his hind legs. It
is not done well; but you are surprised to find it done at all.
_____________________________________________________________________
---------------------------------------------------------------------
=== 一般屬性(Common attributes) ===
大部分的塊狀單元都支援下列屬性：
[cols="1e,1,5a",frame="topbot",options="header"]
|====================================================================
|名稱 |後端 |描述
|id |html4, xhtml11, docbook |
Unique identifier typically serve as link targets.
Can also be set by the 'BlockId' element.
|role |xhtml11, docbook |
Role contains a string used to classify or subclassify an element and
can be applied to AsciiDoc block elements. The AsciiDoc 'role'
attribute is translated to the 'role' attribute in DocBook outputs and
to the 'class' attribute in HTML outputs.
DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML
'class' attributes; CSS can then be used
http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
generated HTML].
|reftext |docbook |
'reftext' is used to set the DocBook 'xreflabel' attribute.
The 'reftext' attribute can an also be set by the 'BlockId' element.
|====================================================================
== 文章段落(Paragraphs) ===
所謂的文章段落是指一段文字之後，最後為一列空白列或是檔案結尾(end of
file)或者是一個個分界區塊的開頭。文章段落的標記定義在組態檔的
`[paradef-*]` 段中。
一般的文章段落由一列或多列非空白列的內文所組成。首列會由最左邊開始(沒有空白
字元)。The default processing expectation is that of a normal
paragraph of text. 'literal' and 'verse' paragraph styles are
available (in addition to the 'default' paragraph style).
[[X85]]
=== 字面文字段落形式(literal paragraph style) ===
字面文字段落會顯示出來的效果會是逐字地使用等寬字體印出，字體後面不會有
背景或粗體的效果。預設的狀況下不會有文字的格式設定或文字替換在字面文字
段落發生，除非是特殊字元跟Callouts。
'字面(literal)' 風格會作用在有縮排的文章段落，例如一段的第一列有縮排一個
、多個空白或tab字元。例如：
---------------------------------------------------------------------
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
會輸出成
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
NOTE: Because <<X64,lists>> can be indented it's possible for your
indented paragraph to be misinterpreted as a list -- in situations
like this apply the 'literal' style to a normal paragraph.
除了你自己縮排一個文章段落之外，你也可以直接使用 'literal' 來達成同樣的
效果，例如：
---------------------------------------------------------------------
[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
輸出成：
[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
[[X94]]
=== 詩式文件段落形式(verse paragraph style) ===
'詩(verse)式' 文件段落 <<X23,形式>>保留了列的邊界，很適合用在歌詞及詩上。
例如：
---------------------------------------------------------------------
[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
---------------------------------------------------------------------
輸出成：
[verse]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
[[X28]]
=== 警示段落(Admonition Paragraphs) ===
若個文章段落的第一個字是以 `NOTE:`, `TIP:`, `IMPORTANT:`, `WARNING:`
或 `CAUTION:` 為其開頭，則會產生下列的警示段落 'TIP', 'NOTE',
'IMPORTANT', 'WARNING' 及 'CAUTION' 。舉例如下：
NOTE: This is an example note.
還有另外一種方式，你可以使用<<X79,屬性列表元素>>來指定這一段所使用警
示段落的形式，例如：
[NOTE]
This is an example note.
輸出成：
NOTE: This is an example note.
TIP: 如果你警示的內容不只一段，那你可以使用<<X22,警示區塊>>來代替。
[[X47]]
==== 警示圖示及說明文字(Admonition Icons and Captions) ====
NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and
`caption` attributes does not apply when generating DocBook output. If
you are going the DocBook route then the <<X43,a2x(1)>> `--no-icons`
and `--icons-dir` options can be used to set the appropriate XSL
Stylesheets parameters.
By default the asciidoc(1) `xhtml11` and `html4` backends generate
text captions instead of admonition icon image links. To generate
links to icon images define the <<X45,`icons`>> attribute, for example
using the `-a icons` command-line option.
The <<X44,`iconsdir`>> attribute sets the location of linked icon
images.
You can override the default icon image using the `icon` attribute to
specify the path of the linked image. For example:
[icon="./images/icons/wink.png"]
NOTE: What lovely war.
Use the `caption` attribute to customize the admonition captions (not
applicable to `docbook` backend). The following example suppresses the
icon image and customizes the caption of a 'NOTE' admonition
(undefining the `icons` attribute with `icons=None` is only necessary
if <<X45,admonition icons>> have been enabled):
[icons=None, caption="My Special Note"]
NOTE: This is my special note.
This subsection also applies to <<X22,Admonition Blocks>>.
== 分界區塊(Delimited Blocks) ==
分界區塊是由兩個分界列夾起來的內容而成的區塊(分界列通常是一連串四個或
四個以上相同字元而成的一列)分界區塊的行為定義在組態檔中的
`[blockdef-*]` 段。
=== 預設的分界區塊(Predefined Delimited Blocks) ===
AsciiDoc已經定義了好幾種分界區塊(參考asciidoc(1)目錄下的的組態檔
`asciidoc.conf`)：
預設的分界區塊如下：
註解區塊(CommentBlock): //////////////////////////
依照原樣區塊(PassthroughBlock): ++++++++++++++++++++++++++
列表區塊(ListingBlock): --------------------------
字面區塊(LiteralBlock): ..........................
邊欄區塊(SidebarBlock): **************************
引用區塊(QuoteBlock): __________________________
範例區塊(ExampleBlock): ==========================
開放式區塊(OpenBlock): --
The <<X56,code>>, <<X57,source>> and <<X58,music>> filter blocks are
detailed in the <<X59,Filters>> section.
.預設的分界區塊的替換行為(Default DelimitedBlock substitutions)
[cols="2e,7*^",frame="topbot",options="header,autowidth"]
|=====================================================
| |Attributes |Callouts |Macros | Quotes |Replacements|Special chars
|Special words
|依照原樣區塊(PassthroughBlock) |Yes |No |Yes |No |No |No |No
|列表區塊(ListingBlock) |No |Yes |No |No |No |Yes |No
|字面區塊(LiteralBlock) |No |Yes |No |No |No |Yes |No
|邊欄區塊(SidebarBlock) |Yes |No |Yes |Yes |Yes |Yes |Yes
|引用區塊(QuoteBlock) |Yes |No |Yes |Yes |Yes |Yes |Yes
|範例區塊(ExampleBlock) |Yes |No |Yes |Yes |Yes |Yes |Yes
|開放式區塊(OpenBlock) |Yes |No |Yes |Yes |Yes |Yes |Yes
|=====================================================
=== 列表區塊(Listing Blocks) ===
'ListingBlocks' are rendered verbatim in a monospaced font, they
retain line and whitespace formatting and are often distinguished by a
background or border. There is no text formatting or substitutions
within Listing blocks apart from Special Characters and Callouts.
Listing blocks are often used for computer output and file listings.
我們來看一個例子：
[listing]
......................................
--------------------------------------
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
--------------------------------------
......................................
輸出後：
--------------------------------------
#include <stdio.h>
int main() {
printf("Hello World!\n");
exit(0);
}
--------------------------------------