/
restructuredtext.txt
2338 lines (1500 loc) · 88.4 KB
/
restructuredtext.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
.. -*- coding: utf-8 -*-
.. _rst:
=======================================
reStructuredText标记规范
=======================================
:Author: eonwen
:Contact: eonwen@hotmail.com
.. Note::
本文档为技术规范细节，而非教程或入门。如果你第一次接触 reStructuredText，请先阅读 `ReStructuredText介绍 <../../user/rst/quickstart.html>`_ 和 `ReStructuredText快速开始 <../../user/rst/quickref.html>`_ 用户手册。
reStructuredText_ 是使用简单直观结构来展示文档结构的纯文本。这些结构无论是原生状态还是处理后的形式都相当易于阅读。这篇文档本身就是一个reStructuredText的例子(原生的，如果你阅读的是文本文件；或处理后的，如果你阅读的是一个HTML文档)。reStructuredText解析器是 Docutils_ 的一个组件。
简单的隐式标记用于展示特殊的结果，如段落标题、无序列表和强调。使用的标记尽可能小且不显眼。reStructuredText基本语法中不常用的结构和扩展可能会更显眼或使用显式标记。
reStructuredText适用于任何长度的文档，从非常小的(如行内程序文档片段 -- Python文档字符串)到非常大的(本文档)。
第一节通过例子展示了reStructuredText标记的语法快速概览。完整的规范可以在 `语法细节`_ 章节看到。
`文本块`_ (其中的标记不被处理)用于展示本文档的示例，其以纯文本的形式来说明标记。
.. contents::
.. section-numbering::
.. _rst-quick-syntax-overview:
-----------------------
语法快速概述
-----------------------
reStructuredText文档由正文或块级元素组成，可以使用章节的方式来组织。 章节_ 表现为标题风格（下划线和可选的上划线）。章节包含正文元素及/或子标题。某些正文元素包含其他元素，如列表包含列表项，列表项包含段落及其他正文元素。其他的，如段落包含文本和 行内标记_ 元素。
这是 正文元素_ 的例子：
- 段落_ (和 行内标记_ )::
段落包含文本，还可能包含行内标记: *强调* 、 **特别强调** 、 `解释文本` 、 ``行内文本`` 、 独立超链接(http://www.python.org)、扩展超链接(Python_)、内部交叉引用(example_)、脚注引用([1]_)、引文引用([CIT2002]_)、替代引用(|example|)和 _`行内内部目标`.
段落使用空行分隔，左对齐。
- 五种类型的列表:
1. 无序列表_::
- 这是无序列表
- 序号可以是"* + -"
2. 有序列表_::
1. 这是一个有序列表
2. 序号可以是任何数字、字母或罗马数字
3. 定义列表_::
是什么
定义列表关联一个术语到一个定义
如何
术语是一个一行句子，定义是一个或多个段落或正文元素，使用缩进联系到术语
4. 字段列表_::
:是什么: 字段列表映射字段名到字段体，如数据库记录。它们通常是扩展语法的一部分
:怎么样: 字段标记是一个冒号，字段名，另一个冒号
5. 选项列表_ ，用于列出命令行选项::
-a 命令行选项"a"
-b file 选项可以有参数和描述
--long 选项也可以长
--input=file 长选项也可以有参数
/v DOS/VMS风格的选项也行
选项与描述之间需要至少两个空格
- 文本块_::
文本块可以是缩进或段落最后的行前缀块（表现为两个冒号"::"）::
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
- 引用块_::
引用快包括缩进的正文元素：
Tis theory, that is mine, is mine.
-- Anne Elk (Miss)
- 测试文档块_::
>>> print 'Python专用用例；以">>>"'
Python专用用例；以">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
- 表格_ 有两种语法:
1. 网格表格_ ：完整的，但复杂、冗长::
+------------------------+------------+----------+
| Header row, column 1 | Header 2 | Header 3 |
+========================+============+==========+
| body row 1, column 1 | column 2 | column 3 |
+------------------------+------------+----------+
| body row 2 | Cells may span |
+------------------------+-----------------------+
2. 简单表格_ ：简单且紧凑，但有限制::
==================== ========== ==========
Header row, column 1 Header 2 Header 3
==================== ========== ==========
body row 1, column 1 column 2 column 3
body row 2 Cells may span columns
==================== ======================
- 显式标记块_ 都是以一个显式块标记，两个点和一个空格:
- 脚注_::
.. [1] 个脚注包含正文元素、最少3个空格的一致缩进
- 引文_::
.. [CIT2002] 似脚注，除了标签是文本
- 超链接目标_::
.. _Python: http://www.python.org
.. _example:
上面的"_example"指向这一段
- 指令_::
.. image:: mylogo.png
- 替代定义_::
.. |symbol here| image:: symbol.png
- 注释_::
.. 注释以两个点和一个空格开始。可以接除了脚注/引文、超谅解、指令或替代定义之外的任何东西。
.. _rst-syntax-details:
----------------
语法细节
----------------
下面的描述列出了"文档树元素"(文档树元素名称、XML DTD通用标识符)所对应的语法结构。想查看元素层次结构的细节，请阅读 `Docutils文档树 <The
Docutils Document Tree_>`_ 和 `Docutils通用DTD <Docutils Generic DTD_>`_ XML文档类型定义。
.. _rst-whitespace:
空格
==========
议使用空格进行 缩进_ ，但tab也可以使用。tab会转换为空格。tab会停在每个第八列。
其他空白字符（form feeds [chr(12)] and vertical tabs [chr(11)]）会在处理前转为单个空格。
.. _rst-blank-lines:
空行
-----------
空行用于分隔段落和其他元素。除了在文本块（所有的空格被保留）中之外，多个连续的空行相当于一个空行。当标记使元素分离不明确时，空行会被忽略。文档的第一行会被当做其之前有一个空行，文档的最后一行会被当做其之后有一个空行。
.. _indentation:
缩进
-----------
缩进是用来表示引用块、定义（在定义列表项中）和本地嵌套内容的唯一重要标示:
- 列表项内容（列表项多行内容和一个列表项中多个正文元素包括嵌套列表）
- 文本块的内容
- 显式标记块的内容
任何文本的缩进少于当前级别，会结束当前级别的缩进
因为所有的缩进都是重要的标志，因此缩进的级别应当一致。例如，缩进是引用块的唯一标记：
这是一个顶级段落。
该段落属于一级引用块。
一级引用块的第二段。
一个引用块内的多级缩进会导致复杂的结构：
这是一个顶级段落。
该段落属于一级引用块。
该段落属于二级引用块
另一个顶级段落
这一段属于二级引用块。
这一段属于一级引用块。上面的二级引用块在这个一级引用块里面。
当一个段落或其他结构有不止一行文本，行应该左对齐::
这是一个段落。段落各行
左对齐。
这个段落有问题。行
没有左对齐。除了潜在的误解，还会
由解析器生成警告和/或错误信息。
几种结构以同一个标记开始，结构体必须以缩进与标记联系。对于使用简单标记的结构(无序列表_ 、有序列表_ 、脚注_ 、引文_ 、超链接目标_ 、指令_ 和 注释_ )，正文的缩进级别由文本第一行的位置决定，与标记在同一位置。举例，无序列表体必须必子弹字符缩进至少2列::
- 这是无序列表项目的段落的第一行。
所有行必须与这一行对齐。 [1]_
这个缩进段落解释为一个引用块
因为其没有充分缩进，
这个段落不属于列表项。
.. [1] 这里是脚注。第二行与
注标签对齐。".."标记
用于决定缩进。
对于使用复杂标记( 字段列表_ 、 选项列表_ )的结构，标记可能包含任意文本，标记后的第一行的缩进决定了正文的左边。举例，字段列表可能有非常长的标记（包含字段名）::
:Hello: 这个字段有一个很短的名字，因此
对齐到第一行就行了。
:Number-of-African-swallows-required-to-carry-a-coconut: 这个
很难将字段体对齐到第一行左边。甚至可能与标记不在同一行开
始字段体。
.. _rst-escaping-mechanism:
转义机制
==================
7位ASCII普遍适用，是有限的。不管用什么字符作标记，它们都会在文本中具有多重意义。因此，标记字符在文本中有时会出现，而不被认为是标记。任何严谨的标记系统都需要一个转义机制来重写标记字符的默认含义。我们使用与其他常用领域相同的转义字符，反斜杠。
反斜杠可以将任何非空白字符转义为字符。转义的字符表示字符本身，并阻止其在标记中扮演任何角色。反斜杠会在输出时去除。反斜杠文本用两个反斜杠表示(第一个反斜杠转义第二个，阻止其变被解释为转义角色)。
反斜杠转义空白字符会被从本文档中删除。在字符级 行内标记_ 中是允许的。
在两种上下文中反斜杠没有特殊含义：文本块和行内文本。在这些上下文中，单个的反斜杠表示反斜杠文本，无须重复。
注意：reSturcturedText规范和解析器不处理文本输入的表示或提取的问题（文本以如何和以何种形式到达解析器）。反斜杠与其他字符可能在特定的上下文中作为转义字符，其必须被合适的处理。例如，Python在字符串中使用反斜杠来转义特定字符，而不是其他的。在Python文档字符串中出现反斜杠最简单的处理方法就是使用原生文档字符串::
r"""This is a raw docstring. Backslashes (\) are not touched."""
.. _rst-reference-names:
引用名称
===============
简单引用名称是由字母和内部连字符、下划线、点、冒号和加号组成的单个单词，不能有空白或其他字符。脚注标签（脚注_ 和 脚注引用_ ）、引文标签（引文_ 和 引文引用_ ）、解释文本_ 角色以及某些 超链接引用_ 使用简单引用名称语法。
引用名称使用标点符号或短语（2个或更多空格分隔的单词），被称为“短语引用”。短语引用由在反引号封闭的短语表示，并将反引号文本作为引用名称::
想要学习 `我最喜欢的编程语言`_ ?
.. _我最喜欢的编程语言: http://www.python.org
简单引用名称也可以可选的使用反引号。
引用名称是空白中立的且不区分大小写。在内部解析引用名称时：
- 空白会被归一(一个或多个空格、横向或纵向的tabs、新行、换行会被解释为一个空格)
- 大小写会被归一（所有字母被转为小写）
举例，如下 超链接引用_ 是等价的::
- `A HYPERLINK`_
- `a hyperlink`_
- `A
Hyperlink`_
`超链接 <超链接目标_>`_ 、脚注_ 和 引文_ 对于引用名称共享相同的命名空间。引文的标签（简单引用名称）和手动编号脚注（数字）会进入相同的数据库作为其他超链接名称。这意味着一个可以被脚注引用(``[1]_``)指向的脚注（定义为".. [1]"）也可以被纯超链接引用 (1_)指向。当然，每个类型的引用（超链接、脚注、引文）可能会以不同的方式处理和渲染。应该注意避免引用名称混淆。
.. _rst-document-structure:
文档结构
==================
.. _rst-document:
文档
--------
文档树元素：文档
解析过的reStructuredText文档的顶级元素是"文档"元素。在初始化解析之后，文档元素是一个文档片段的简单容器，包含 正文元素_ 、 过渡_ 和 章节_ ，但不包括文档标题或其他目录元素。调用解析器的代码可以选择运行一个或多个可选的post-parse transforms_ ，将文档片段重新组织为一个带有标题和其他可能的元数据的完整文档（作者、日期等等。详见 目录字段_ ）。
具体来说，没有办法在reStructuredText中显式的表示文档的标题和子标题。作为替代，一个长的顶级章节标题(见下面的 章节_ )可以作为文档标题。类似的，紧跟在"文档标题"之后的长的二级章节标题，可以作为文档的子标题。其他所有章节会提升一到两级。详见：`文档标题转换 <DocTitle transform_>`_ 。
.. _rst-sections:
章节
--------
文档树元素：章节、标题
章节通过其标题识别，在标题文本下使用下划线进行标记或下划线和匹配的上划线。下划线/上划线是单个重复的标点字符，从左边第一列开始最少到与文档标题右边对齐。具体来说，一个下划线/上划线字符可以是任何非字母打印7位ASCII字符 [#]_ 。当使用上划线时，上划线的长度与使用的字符必须与下划线相同。可以有任意数字级别的章节标题，但某些输出格式可能有限制（HTML只有6级标题）。
.. [#] 下面是有效的章节标题装饰字符::
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
有一些字符比其他字符更适用，建议使用它们::
= - ` : . ' " ~ ^ _ * + #
相比强加一个固定数字和顺序的章节标题装饰风格，其执行的顺序是碰到每个标题的先后顺序。碰到的第一种类型是最外层标题（如HTML H1），第二种类型则成为子标题，第三种将成为子子标题，以此类推。
下面是章节标题样式的例子::
========
章节标题
========
--------
章节标题
--------
章节标题
========
章节标题
--------
章节标题
````````
章节标题
''''''''
章节标题
........
章节标题
~~~~~~~~
章节标题
********
章节标题
++++++++
章节标题
^^^^^^^^
当一个标题同时有上下划线，标题文本可以插入，类似上述前两个例子。这只是为了美观而非必要的。只有下划线的标题文本 *不* 可以插入。
标题后的空行是可选的。到下一个标题的所有文本块或更高级别会包含在章节中（或子章节，等等）。
所有章节标题样式不需要使用，也不需要使用任何特定的段落标题样式。然而，一个文档使用的章节标题必须是一致的：一旦建立了标题样式的层次结构，章节必须使用该层次结构。
每个章节标题会自动生成指向章节的超链接。超链接的文本（即引用名称）与章节标题一致。详见 隐式超链接目标_ 。
章节可以包含 正文元素_ 、 过渡_ 和嵌套的章节。
.. _rst-transitions:
过渡
-----------
文档元素：过渡
取代小标题，段落之间的额外空间或类型装饰符可用来标记文本分隔或主
题或重点的改变。
(The Chicago Manual of Style, 14th edition, section 1.80)
过渡常见于小说，作为一个跨越一行或多行的间隙，有或没有类似于一行星号的类型装饰符。过渡分隔其他正文元素。过渡不应开始或结束一个章节或文档，两个过渡也不应该直接相邻。
过渡标记的语法是一排至少4个重复的标点符号。该语法与章节标题下划线一样。过渡标记前后需要空行::
段落
----------
段落
不像章节标题下划线，章节标题不需要体系结构。建议使用同一种风格。
处理系统可以以任何其希望的方式在输出中渲染过渡。如，HTML中的<hr>输出是一种明显的选择。
.. _rst-body-elements:
正文元素
=============
.. _rst-paragraphs:
段落
----------
文档树元素：段落
段落包含没有任何标记指向其他正文元素的左对齐文本块。使用空行分隔段落及其他正文元素。段落可以包含 行内标记_ 。
语法图::
+------------------------------+
| 段落 |
| |
+------------------------------+
+------------------------------+
| 段落 |
| |
+------------------------------+
.. _rst-bullet-lists:
无序列表
------------
文档树元素：无序列表、列表项
以一个 "*", "+", "-"开头，后面根一个空格的文本块是一个无序列表项。列表项正文必须与bullet缩进左对齐。文本紧接在bullet分隔符之后。例如::
- 这是第一个无序列表项。上面的空行是必须的。两个列表项
之间的空行（如这一段下面的）是可选的。
- 这是列表第二项的第一个段落
这是列表第二项的第二个段落。
这一段上面的空行是必须的。段落的左边与上一个段落对其
所有的缩进与无序符号对齐。
- 这是一个子列表。无序符号与上一行的左边对其。
子列表是一个新的列表，因此要求上下都有空行。
- 这是主列表的第三项
这个段落不是列表的一部分。
下面是一些 **错误** 的无序列表格式的例子::
- 第一行没问题
列表项与段落之间需要空行(警告)
- 下面一行看似一个新的子列表，但实际上不是:
- 这是一个连续的段落而非子列表（因为没有空行）
这一行缩进也不对。
- 可能会生成警告。
语法图::
+------+-----------------------+
| "- " | list item |
+------| (body elements)+ |
+-----------------------+
.. _rst-enumerated-lists:
有序列表
----------------
文档树元素：有序列表、列表项
有序列表与无序列表类似，但是用序号而非圆点。序号包含有序成员和格式，之后跟着空格。以下有序序列可以识别:
- 任意数字：1 2 3 ... (无上限)
- 大写字母：A B C ... Z
- 小写字母：a b c ... z
- 大写罗马数字：I II III IV ... MMMMCMXCIX(4999)
- 小写罗马数字：i ii iii iv ... mmmmcmxcix(4999)
另外，自动编号符"#"可以用于自动编号列表。自动编号列表可以以显示的编号开始设置序列。完整的自动有序列表使用以1开始的任意数字(自动有序列表为
Docutils 0.3.8新增)
以下格式可以识别：
- 以点为后缀："1." "A." "a." "I." "i."
- 以括号包围："(1)" "(A)" "(a)" "(I)" "(i)"
- 以右括号为后缀："1)" "A)" "a)" "I)" "i)"
解析一个有序列表时碰到下列情况，会开始一个新列表：
- 碰到与当前列表序号的类型和格式不一致的序号（如，"1."和"a."分属两个列表）
- 序号不在序列内有序（如，"1"、"3"产生连个独立的列表）
建议使用1 ("1", "A", "a", "I", or "i")作为第一个列表项的序号。当然以其他的数字开始也会被识别，但输出格式可能不支持。任何不以传统的1开始的列表都会生成一个一级[info]系统信息。
使用罗马数字的列表必须以"I/i"或一个多字符值如"II"或"XV"开始。任何其他单字符罗马数字（"V", "X", "L", "C", "D", "M"）会被解释为一个字母而非罗马数字。
同样，使用字母开始的列表不能使用"I/i"，因为其会被识别为罗马数字1。
有序列表项的第二行会被验证。这会阻止原始段落被解释为列表项。例如，下面的文本会被解释为原始的段落::
A. Einstein was a really
smart dude.
但段落仅包含一行必然含糊不清。这段文本被解析为一个有序列表::
A. Einstein was a really smart dude.
如果一个单行段落以序号("A.", "1.", "(b)", "I)", 等等)开始，第一个字符需要转义，以便其被解析为一个段落::
\A. Einstein was a really smart dude.
嵌套的有序列表的例子::
1. Item 1 initial text.
a) Item 1a.
b) Item 1b.
2. a) Item 2a.
b) Item 2b.
语法图::
+-------+----------------------+
| "1. " | list item |
+-------| (body elements)+ |
+----------------------+
.. _rst-definition-lists:
定义列表
----------------
文档树元素：定义列表、定义列表项、术语、分类器、定义
每个定义列表项包含一个术语、可选的分类器和一个定义i。术语是一个简单的一行单词或句子。可选的分类器与术语在同一行，跟在它后面。每个分类器跟在一个行内":"(空格冒号空格)之后。定义是一个块通，过缩进与术语联系，可以包含多个段落和其他正文元素。术语与定义块之间不允许有空格（这区分了定义列表与 引用块_ ）。定义列表第一行之前和最后一行之后需要空行，中间的列表项是否空行是可选的。例如::
术语 1
定义 1.
术语 2
定义 2, 段落 1.
定义 2, 段落 2.
术语 3 : 分类器
定义 3.
术语 4 : 分类器 1 : 分类器 2
定义 4.
行内标记在术语行被解析，在分类器分隔符(":")被识别之前。分隔符仅在出现在任何行内标记之外时被识别。
定义列表可用于多种用途，包括:
- 作为一个字典或术语表。术语是单词本身，分类细可用于根据用途分类术语（动词、名词等等），定义跟在后面。
- 用于描述程序变量。术语是变量名，分类器用于区分变量类型（字符串、整形等等），定义描述变量在程序中的用法。定义列表的该用途支持分类器语法 Grouch ，一种描述和执行Python对象约束的系统。
语法图::
+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
| definition |
| (body elements)+ |
+----------------------------+
.. _rst-field-lists:
字段列表
-----------
文档树元素: 字段列表、字段、字段名、字段正文
字段列表作为扩展语法的一部分被使用，如 指令_ 的选项或等待进一步处理的类数据库记录。它们也被用于两列类列表结构类似于数据库记录（标签和数据对）。reStructuredText应用可以在特定上下文中识别字段名和变形字段或字段正文。例如，阅读下面的 `目录字段`_ 或 指令_ 中的 "`图片 <image_>`_"和"`元 <meta>`_" 指令 .
字段列表会映射字段名到字段正文，仿照 RFC822_ 头。一个字段名可以包含任何字符，但字段名中的冒号(":")必须使用反斜杠转义。行内标记被解析为字段名。在进一步处理或传输时，字段名大小写敏感。字段名. 字段名与一个单独的冒号前后缀一起构成字段标记。字段表及之后跟空格和字段正文。字段正文可以包含多个正文元素，缩进到字段标记处。字段名标记之后的第一行决定字段正文的缩进。如::
:Date: 2001-08-16
:Version: 1
:Authors: - Me
- Myself
- I
:Indentation: 因为字段标记可能很长，字段正文的第二行
及随后的行不必与第一行对齐，但必须缩进到字段名标记
处，且它们应当互相对齐。
:Parameter i: integer
一个多单词字段名中的单个词的解释是应用程序。该应用程序可以为该字段名指定一个语法。例如，第二个单词及其后面的单词可以被视为“参数”，引用短语可以被视为一个单一的参数，并可能会增加直接支持“键=值”的语法。
除了潜在的可能导致误解的标准 RFC822_ 标题不能用于这种构造是因为它们模糊不清。以一个单词后面跟一个冒号开始一行是一种通用的书写文本。然而，在定义良好的上下文如当一个字段列表总是在文档的开头（PEPS和电子邮件）时，标准RFC822头可以使用。
语法图(简化)::
+--------------------+----------------------+
| ":" field name ":" | field body |
+-------+------------+ |
| (body elements)+ |
+-----------------------------------+
.. _rst-bibliographic-fields:
目录字段
````````````````````
文档树元素: 文档信息、作者、多个作者、组织、 联系方式、版本、状态、日期、版权、字段、主题
当一个字段列表是文档的第一个非注释元素时(只在文档标题之后，如果有)，它可以从字段转换为文档目录数据。这个目录数据对应一本书的封面，如标题页和版权页。
特定的注册过的字段名(见下表)会被识别并转换为对应的文档树元素，大部分会变为"docinfo"元素的子元素。对于这些字段，没有顺序要求，但它们会被重新组织以适应文档的结构。 除非另有说明，每一个目录元素的字段正文只能包含一个段落。字段正文会被 RCS关键字_ 检查和清理。任何不能识别的字段会被作为通用字段保留在docinfo元素中。
注册过的目录字段名和它们对应的文档树元素如下:
- 字段名 "Author": 作者元素
- "Authors": 作者.
- "Organization": 组织.
- "Contact": 联系方式.
- "Address": 地址.
- "Version": 版本.
- "Status": 状态.
- "Date": 日期.
- "Copyright": 版权.
- "Dedication": 主题.
- "Abstract": 主题.
"Authors"字段可以包含: 一个包含作者列表（冒号或逗号分隔）的段落；或一个无序列表，其每个元素包含一个单独的段落每作者。首先检查";"，因此"Doe, Jane; Doe, John"是可以的。如果单个饼子包含逗号，使用分号结束它: ":Authors: Doe, Jane;"。
"Address"字段用于多行邮件地址。新行和空格会被保留。
"Dedication"和"Abstract"字段可以包含任意正文元素。每种一个。它们会称为紧跟在docinfo元素之后的使用"Dedication"或"Abstract"标题（或语言相等）的主题元素。
这个字段名到元素的映射可以替换为其他语言。详见 `文档信息转换 <DocInfo transform_>`_ 实现文档。
未注册/通用字段可以包含一个或多个段落或任意正文元素。
.. _rst-rcs-keywords:
RCS关键字
````````````
被解析器识别的 目录字段_ 通常会检查并清理 RCS [#]_ 关键字 [#]_ 。RCS关键字会作为"$keyword$"进入源文件，一旦存储为 RCS 或
CVS [#]_ ，它们会扩展为"$keyword: expansion text $"。例如，一个"Status"字段会被转换为一个"status"元素::
:Status: $keyword: expansion text $
.. [#] 修订控制系统（Revision Control System）。
.. [#] RCS关键字处理可以关闭（未实现）。
.. [#] 并发版本系统（Concurrent Versions System）。CVS使用与RCS相同的关键字。
处理后，"status"元素的文本会变为简单的"扩展文本"。美元分隔符和开头的RCS关键字名会被去除。
RCS关键字仅处理目录上下文（文档标题，如果有，之后的文档中第一个非注释结构）中的字段列表。
.. _rst-option-lists:
选项列表
------------
文档树元素: 选项列表、选项列表项、选项组、选项、选项字符串、选项参数、描述
选项列表是一个包含命令行参数和描述的两列列表，用于记录程序的选项。例如::
-a 输出全部
-b 都输出(该描述有点
长)
-c arg 只输出参数
--long 整天输出
-p 这个选项的描述有两段
这是第一段
这是第二段。选项间的空行可能被
忽略（像上面一样）或左对齐（像这里一样）
--very-long-option 一个VMS风格的选项。注意调整
必须的两个空格
--an-even-longer-option
表述也可以从另一行开始
-2, --two 这个选项有两个变量
-f FILE, --file=FILE 这两个选项是同义词；
都有参数。
/V 一个VMS/DOS风格的选项
reStructuredText能够识别几种类型的选项:
- POSIX短选项，由连字符和选项字符组成
- POSIX长选项，由两个连字符和一个选项单词组成；某些系统
使用一个连字符。
- 老式GNU风格"plus"选项，由一个plus和选项字符组成("plus"
选项已经被废弃了，不鼓励使用它们)。
- DOS/VMS选项，由一个斜杠和一个选项字符或单词组成。
请注意：DOS或Windows软件可能使用POSIX风格和DOS/VMS风格的选项。
这些和其他变体有时可能会混合使用。选择上面的名字只是为了方便。
POSIX长/短选项的语法基于Python的 getopt.py_ 模块所提供的语法，
其实现一个类似于 `GNU libc getopt_long()`_ 函数但有某些约束的
选项解析器。有许多不同的选项系统，reStructuredText并非全部都
支持。
尽管POSIX长选项和DOS/VMS选项单词可能允许在使用命令行时被操作
系统或应用程序截取，但reStructuredText并不展示或支持这种方式。
应提供完整的选项单词。
选项可以跟在一个参数占位符之后，其角色和语法应该被解释为描述
文本。使用空格或等号作为选项与选项参数占位符之间的分隔符；短
选项(只有"-"或"+"前缀)可能会省略分隔符。选项参数有两种形式:
- 字母(``[a-zA-Z]``)开头，其后紧跟字母、数字、下划线和连字符
(``[a-zA-Z0-9_-]``)。
- 以尖括号(``<``)开始，以反尖括号(``>``)结束；中间可以是除此
之外的任何字符。
多选项"同义词"可以列出并共享同一个描述。以逗号空格分隔。
选项和描述之间至少需要两个空格描述可以包含多个正文元素。选项
标记分隔符后的第一行缩进为描述。与其他类型的列表类似，第一个
列表项之后和最后一个列表项之后需要一个空行，中间的空行可选。
语法图(简化)::
+----------------------------+-------------+
| option [" " argument] " " | description |
+-------+--------------------+ |
| (body elements)+ |
+----------------------------------+
.. _rst-literal-blocks:
文本块
--------------
文档树元素: 文本块
一个包含两个冒号("::")的段落表示接下来的文本由文本块组成。文本块
必须缩进或引用（看下面）。文本块内的任何标记都不会被处理。它会被
留下，通常适用等快字体渲染::
这是一个典型的段落，后面跟着一个缩进的文本块。
::
for a in [5,4,3,2,1]: # this is program code, shown as-is
print a
print "it's..."
# a literal block continues until the indentation ends
这段文本恢复了缩进，其在文本块之外，因此会被当做普通的段落。
只包含"::"的段落会在输出时完全移除；不会保留空段落。
为了方便，段落结尾处的"::"可以被识别。
如果后面紧跟空格，输出时两个冒号都会被移除。当文本之后紧跟"::"，
其中 *一个* 冒号违背保留(如，"::"会变为":")。
换句话说，这些全部是等价的(请注意段落之后的冒号):
1. 扩展形式::
段落:
::
文本块
2. 部分最小化形式::
段落: ::
文本块
3. 完全最小化形式::
段落::
文本块
所有的空白(包括折行，但不包括对于缩进文本块最低限度的缩进)会被保留。
前后各需要一个空行，但这些空行不被认为是文本块的一部分。
.. _rst-indented-literal-blocks:
缩进文本块
``````````
缩进文本块通过缩进关联到包围的文本(每行以空白开头)。缩进文本块的每
一行的最低限度的缩进会被移除。该文本块不需要是连续的，缩进文本的章
节之间允许空行。该文本块以缩进的结束而结束。
语法图::
+------------------------------+
| paragraph |
| (ends with "::") |
+------------------------------+
+---------------------------+
| indented literal block |
+---------------------------+
.. _rst-quoted-literal-blocks:
引用文本块
`````````````````````
引用文本块是非缩进的连续文本块，其每一行以相同的非字母可打印7位ASCII
字符 [#]_ 开始。引用文本快由空行结束。引用文本快会在处理过的文档中保
存。
.. [#] 以下是所有有效缩进字符::
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
注意：这与有效的 章节_ 标题装饰相同。
语法图::
+------------------------------+
| paragraph |
| (ends with "::") |
+------------------------------+
+------------------------------+
| ">" per-line-quoted |
| ">" contiguous literal block |
+------------------------------+
.. _rst-line-blocks:
行块
-----------
文档树元素: 行块、行(Docutils 0.3.5新增)
行块对于地址块很有用。诗(诗歌、歌词)和无装饰列表等行结构有重要
意义。行块是一组由竖线("|")前缀开头的行。每个竖线前缀表示一个新
行，因此折行会被保留。初始缩进对于嵌套结构也很重要。支持行内标
记。连续行辈包装为一个长的行，他们以一个空格代替竖线开始，左边
必须对其，但不需要与上面的文字的左边对其。行块以空行结束。
这个例子展示了连续行::
| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
as soon as it comes.
| Love, Ewan.
这个例子展示了嵌套的行块，通过初始缩进表示新行::
Take it away, Eric the Orchestra Leader!
| A one, two, a one two three four
|
| Half a bee, philosophically,
| must, *ipso facto*, half not be.
| But half the bee has got to be,
| *vis a vis* its entity. D'you see?
|
| But can a bee be said to be
| or not to be an entire bee,
| when half the bee is not a bee,
| due to some ancient injury?
|
| Singing...
语法图::
+------+-----------------------+
| "| " | line |
+------| continuation line |
+-----------------------+
.. _rst-block-quotes:
引用块
------------
文档树元素: 引用块、属性
一个以缩进与前面的文本关联的文本块，前面没有标记表示其为文被快或其他内容的，是引用块。里面的所有标记会被连续处理（对于正文元素和行内标记)::
这是一个原始段落，介绍引用快。
"It is my business to know things. That is my trade."
-- Sherlock Holmes
引用块可能以一个属性结束: 以"--"或"---"开始的文本块。如果属性包含多行，第二行及随后的行必须对其。
如果以属性结束，可能连续出现多个引用快。
非缩进段落
引用块 1.
-- 属性 1
引用块 2.
`空注释`_ 用于显式的结束前面可能会被当做一个引用块的结构::
* 列表项
..
引用块 3.
空注释也可以用来分隔引用快::
引用块 4.
..
引用块 5.
前后均需要空行，但空行不是引用块的一部分。
语法图::
+------------------------------+
| (current level of |
| indentation) |
+------------------------------+
+---------------------------+
| block quote |
| (body elements)+ |
| |
| -- attribution text |
| (optional) |
+---------------------------+
.. _rst-doctest-blocks:
测试文档块
--------------
文档树元素: 测试文档块
测试文档块是交互式Python会话剪切粘贴到文档字符串。它们是通过例子来做
使用说明，并通过Python标准库中的 `测试文档模块 <doctest module_>`_ 一个优雅且强大的测试环境。
测试文档块是以Python交互式解释器的主要提示符 ``">>> "`` 开头的文本块，
并以空行结束。测试为本快会被当做文本块的特殊例子，不需要使用文本块
语法。如果都提供了，文本块语法优先于测试文本块语法::
这是一个原始段落。
>>> print '这是一个测试文本块'
这是一个测试文本块
以下是一个文本块::
>>> 这里不会被识别为测试文本块。但它仍 *会* 被测试文档模块
识别。
测试文档块不需要缩进。
.. _rst-tables:
表格
------
文档树元素: 表格、表格组、行、表头、表正文、行、入口
ReStructuredText提供两种语法来处理表格单元: 网格表格_ 和 简单表格_ 。
类似于其他正文元素，表格前后都需要空行。表格应当与前面的文本块左对齐。
如果缩进，表格会被当做引用块的一部分。
一旦隔离，每个表格单元会被当做一个小型文档；顶部和底部的单元格分界线
作为分隔空行。每个单元格包含0个或多个正文元素。单元格的内容可以包含左
和/或右边距，其会在处理时删除。
.. _rst-grid-tables:
网格表格
```````````
网格表格通过类网格"ASCII art"提供一个完整的表格表示。网格表格允许任意
单元格内容（正文元素），及跨行和列。但网格表格难以生成，特别是对于简单
数据集合来说。 `Emacs表格模式 <Emacs table mode_>`_ 是一个Emacs中允许简单编辑网格表格的
工具。查看 简单表格_ 以获取一个简单（但有限制）的表示。
网格表格通过字符"-"、"="、"|"和"+"被描述为一个视觉网格。连字符("-")被
用于行行(行分隔符)。等号("=")可以用作分隔可选的标题行与表格正文(不被 `Emacs表格模式 <Emacs table mode_>`_ 支持)。竖线 ("|")用于竖行(列分隔符)。加号用于横行与竖行的交叉。例如
::