attachment:reStructuredText.txt of reST

   1 .. 此处是注释，可以注意到一些注释被解析到，文档的标题，副标等处
   2    This is a comment. Note how any initial comments are moved by
   3    transforms to after the document title, subtitle, and docinfo.
   4 
   5 ================================================================
   6  结构化文本(reStructuredText)测试文档
   7 ================================================================
   8 
   9 .. 在文档标题与副标之间的注释在章节标题后解析
  10     Above is the document title, and below is the subtitle.
  11    They are transformed from section titles after parsing.
  12 
  13 ----------------------------------------------------------------
  14  语法结构示例 Examples of Syntax Constructs
  15 ----------------------------------------------------------------
  16 
  17 .. 文档信息栏 bibliographic fields (which also require a transform):
  18 
  19 :作者: David Goodger
  20 :地址: 123 Example Street
  21           Example, EX  Canada
  22           A1B 2C3
  23 :联系: [email protected]
  24 :译者: Me; 
  25 :组织: infopro.cn
  26 :日期: $Date: 2004/01/04 17:44:46 $
  27 :状态: 完善ing;This is a "work in progress"
  28 :当前版本: $Revision: 1.29 $
  29 :版本: 1
  30 :copyright: 此文档遵从开放原则，你可以自由的复制，修改，发布,发售，购买,
  31             租借，销毁，改进；或是引用，摘录，合并，比较，分类等等
  32             总之你可以自由使用此文档；
  33             This document has been placed in the public domain. You
  34             may do with it as you wish. You may copy, modify,
  35             redistribute, reattribute, sell, buy, rent, lease,
  36             destroy, or improve it, quote it at length, excerpt,
  37             incorporate, collate, fold, staple, or mutilate it, or do
  38             anything else to it that your or anyone else's heart
  39             desires.
  40 :条目名称 field name: 普通文档信息栏 This is a generic bibliographic field.
  41 :条目名称2 field name 2:
  42     普通文档信息栏可以包含其它元素
  43     Generic bibliographic fields may contain multiple 文档元素 Body Elements.
  44     (但是条目名称不能使用中文，否则脚本不能生成正常排版格式)
  45     
  46     比如说 Like this.
  47 
  48 :Dedication:
  49 
  50     罗列捐献和开发者名录;For Docutils users & co-developers.
  51 
  52 :abstract:
  53 
  54     这是一个测试文档，包含了 新结构化文本 的所有元素的例子
  55     This is a test document, containing at least one example of each
  56     reStructuredText construct.
  57 
  58 .. meta::
  59    :keywords: reStructuredText, test, parser
  60    :description lang=zh: 一个测试文档，包含了 新结构化文本 的所有元素的例子 A test document, containing at least one
  61        example of each reStructuredText construct.
  62 
  63 .. contents:: 内容索引 Table of Contents
  64 .. section-numbering::
  65 
  66 
  67 结构元素 Structural Elements
  68 ======================================
  69 
  70 章节层次,是通过使用不同的行装饰字串实现的，实际上你可以使用任何字串，
  71 在章节标题行下，使用 行装饰字串 再另起一行就好（注意，行装饰字串至少要与标题一样长）
  72 
  73 推荐使用如下 行装饰字串::
  74 
  75   第一级
  76   ==============
  77   第二级
  78   --------------
  79   第三级
  80   ``````````````
  81   第四级
  82   ''''''''''''''
  83   第五级
  84   """"""""""""""
  85   
  86 即，按照键盘的左右顺序 选的几个不常用字符，实际上 结构文本支持更深层次的结构，
  87 但是HTML标签只支持到 H6,且，不建议创立过多层次的文档...
  88 
  89 
  90 实际效果--第一级别
  91 ======================================
  92 文章序言
  93 
  94 第二级别
  95 -------------------------------------
  96 章正文
  97 
  98 第三级别
  99 `````````````````````````````
 100 小节正文
 101 
 102 第四级别.1
 103 '''''''''''''''''''''''''''''
 104 分论题正文
 105 
 106 第五级别.a
 107 """"""""""""""""""""""""""""
 108 细论正文
 109 
 110 第五级别.b
 111 """"""""""""""""""""""""""""
 112 细论正文
 113 
 114 第四级别.2
 115 ''''''''''''''''''''''''''''
 116 分论题正文
 117 
 118 章节标题 Section Title
 119 --------------------------
 120 
 121 就是在 行装饰字串 上面一行的文字 That's it, the text just above this line.
 122 
 123 过渡 Transitions
 124 -----------------
 125 
 126 这是个表示过渡的横线 Here's a transition:
 127 
 128 ---------
 129 
 130 用以区分 章节 It divides the section.
 131 
 132 文档元素 Body Elements
 133 ==========================
 134 
 135 段落 Paragraphs
 136 --------------------
 137 
 138 一个自然段 A paragraph.
 139 
 140 行内标记Inline Markup
 141 ````````````````````````````
 142 
 143 段落文字可以包含一些行内标记:
 144 *强调*, **加重强调** , ``斜体``,
 145 
 146 标准超链接(http://www.python.org), 扩展超链接 (Python_),
 147 
 148 内联交叉参考(example_), 扩展超链接内嵌URIs
 149 (`Python网站 <http://www.python.org>`__),
 150 
 151 脚注参考引用
 152 (使用数字 [1]_, 末名自动数字 [#]_, 使用标签 [#label]_, 或是符号 [*]_), 
 153 
 154 参考引用([CIT2002]_), 
 155 
 156 置换引用 (|example|)<-- 图片,
 157 
 158 以及 _`行内超链接标签` (参看后文的 标签Targets_ 部分).
 159 
 160 字符级 行内标记Inline Markup 也支持(即使非常的丑!) 
 161 在 *新*\ ``结构化``\ *文本* 
 162 *re*\ ``Structured``\ *Text* 都是可能的.  
 163 (注意 修饰符前要有空格)
 164 
 165 解析时的问题将使用 |problematic| 指出
 166 (此处故意产生一个错误 generated by processing errors; this one is intentional).
 167 
 168 
 169 默认的解析规则字符是 `标题参考`.
 170 这儿有几种显式的规则字符:
 171 
 172 PEP参考 (:PEP:`287`); 
 173 
 174 RFC参考 (:RFC:`2822`); 
 175 
 176 下标 :sub:`subscript`; 
 177 
 178 上标 :sup:`superscript`;
 179 
 180 以及扩展规则 :emphasis:`标准强调` :strong:`行内加重`
 181 :literal:`标记强调`.
 182 
 183 即通过::
 184 
 185  :特殊规则字符:`正常字串`
 186 
 187 以上形式的 规则字符 前导，改变解析输出！
 188 
 189 .. 以下段落不要重新回行分段！DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
 190 
 191 让我们来进行一次行内空白与包绕试验:(对中文支持应该不严密)
 192 Let's test wrapping and whitespace significance in inline literals:
 193 ``This is an example of --inline-literal --text, --including some--
 194 strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
 195 to see how the text is wrapped.  -- ---- --------  Now note    the
 196 spacing    between the    words of    this sentence    (words
 197 should    be grouped    in pairs).``
 198 
 199 如果 ``--pep-references`` 选项已经支持，则此链接应该已经存在 :PEP:`258` 
 200 
 201 
 202 标点列表 Bullet Lists
 203 ------------------------
 204 
 205 - 标点列表 A bullet list
 206 
 207   + 嵌套标点列表 Nested bullet list.
 208   + 嵌套标点列表项 2 Nested item 2.
 209 
 210 - 列表项 2 Item 2.
 211 
 212   列表项 2 的内容段落 Paragraph 2 of item 2.
 213 
 214   * 嵌套标点列表 Nested bullet list.
 215   * 嵌套标点列表项 2 Nested item 2.
 216 
 217     - 第三级 Third level.
 218     - 列表项 2 Item 2.
 219 
 220   * 嵌套标点列表项 3 Nested item 3.
 221 
 222 列举列表 Enumerated Lists
 223 --------------------------------
 224 
 225 1. 阿拉伯数字式 Arabic numerals.
 226 
 227    a) 小写字母lower alpha)
 228 
 229       (i) (小写罗马lower roman)
 230 
 231           A. 大写字母upper alpha.
 232 
 233              I) 大写罗马upper roman)
 234 
 235 2. 列表不从 1 开始 Lists that don't start at 1:
 236 
 237    3. Three
 238 
 239    4. Four
 240 
 241    C. C
 242 
 243    D. D
 244 
 245    iii. iii
 246 
 247    iv. iv
 248 
 249 定义式列表 Definition Lists
 250 --------------------------------
 251 
 252 Term
 253     Definition
 254 Term : classifier
 255     Definition paragraph 1.
 256 
 257     Definition paragraph 2.
 258 Term
 259     Definition
 260 
 261 字段列表 Field Lists
 262 ----------------------
 263 
 264 :怎样what: 字段列表是一组字段名对应字段体,就象数据库的记录,
 265        常常作为扩展语法的一部分,精确的叙述在: :RFC:`2822`
 266        Field lists map field names to field bodies, like database
 267        records.  They are often part of an extension syntax.  They are
 268        an unambiguous variant of :RFC: 2822 fields.
 269 
 270 :多个参数how arg1 arg2:
 271 
 272     字段标记是 冒号 字段名 冒号
 273     The field marker is a colon, the field name, and a colon.
 274 
 275     字段体可以包含其它文档元素
 276     The field body may contain one or more Body Elements, indented
 277     relative to the field marker.
 278 
 279 选项列表 Option Lists
 280 ------------------------
 281 
 282 用以说明命令行选项 For listing command-line options:
 283 
 284 -a            命令行选项 "a"
 285 -b file       选项可以带参数 
 286               和长的说明
 287 --long        选项也可以完整型
 288 --input=file  完整型选项也可带参数
 289 
 290 --very-long-option
 291               说明也可以另起一行
 292 
 293               说明也可以包含其它文档元素 
 294               不用理会从何处开始
 295               
 296 -x, -y, -z    多个选项成为一 "选项组".
 297 -v, --verbose  比照: 缩简式 & 完整式.
 298 -1 file, --one=file, --two file
 299               多个选项加参数.
 300 /V            DOS/VMS 形式的选项也可以
 301 
 302 在选项与描述中至少有两个空格
 303 
 304 
 305 原文块 Literal Blocks
 306 ----------------------------
 307 
 308 原文块 Literal blocks 由两个冒号指出 ("::") 另一空白行结束.  
 309 原文块一般用以忠实的复述有严格缩进的程序代码::
 310 
 311     if literal_block:
 312         text = 'is left as-is'
 313         spaces_and_linebreaks = 'are preserved'
 314         markup_processing = None
 315 
 316 也可能引用没有缩排的::
 317 
 318 >> Great idea!
 319 >
 320 > Why didn't I think of that?
 321 
 322 引述块 Block Quotes
 323 ------------------------
 324 
 325 由缩进的文档元素组成:
 326 
 327     My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
 328     as follows and begins now.  All brontosauruses are thin at one
 329     end, much much thicker in the middle and then thin again at the
 330     far end.  That is my theory, it is mine, and belongs to me and I
 331     own it, and what it is too.
 332 
 333     -- Anne Elk (Miss)
 334 
 335 测试块 Doctest Blocks
 336 ----------------------------
 337 
 338 >>> print 'Python格式使用实例由 ">>>" 开始'
 339 Python-specific usage examples; begun with ">>>"
 340 >>> print '(cut and pasted from interactive Python sessions)'
 341 (cut and pasted from interactive Python sessions)
 342 
 343 表格 Tables
 344 ------------
 345 
 346 下面是栅格式表格接着是简单式表格:
 347 
 348 +------------------------+------------+----------+----------+
 349 | Header row, column 1   | Header 2   | Header 3 | Header 4 |
 350 | (header rows optional) |            |          |          |
 351 +========================+============+==========+==========+
 352 | body row 1, column 1   | column 2   | column 3 | column 4 |
 353 +------------------------+------------+----------+----------+
 354 | body row 2             | Cells may span columns.          |
 355 +------------------------+------------+---------------------+
 356 | body row 3             | Cells may  | - Table cells       |
 357 +------------------------+ span rows. | - contain           |
 358 | body row 4             |            | - body Elements.    |
 359 +------------------------+------------+----------+----------+
 360 | body row 5             | Cells may also be     |          |
 361 |                        | empty: ``-->``        |          |
 362 +------------------------+-----------------------+----------+
 363 
 364 =====  =====  ======
 365    Inputs     Output
 366 ------------  ------
 367   A      B    A or B
 368 =====  =====  ======
 369 False  False  False
 370 True   False  True
 371 False  True   True
 372 True   True   True
 373 =====  =====  ======
 374 
 375 脚注 Footnotes
 376 ------------------
 377 
 378 .. [1] 每一脚注都可以包含其它文档元素, 不过注意要统一有至少三空格以上的缩进
 379 
 380     此为脚注的第二段 This is the footnote's second paragraph.
 381 
 382 .. [#label] 脚注可能是数字式的, 手工指定(如 [1]_) 或是自动分配
 383     使用标签前加 "#".  
 384     此条脚注有一标签使它可以在其它多处被引用, 以脚注参考的形式 ([#label]_) 
 385     或是超链接引用 (label_).
 386 
 387 .. [#] 此为自动分配数字式引用的脚注，拥有匿名的标签引用标签 仅使用 "#" .
 388 
 389 .. [*] 脚注也可使用符号, 特别的使用 "*" 标签.
 390    引用下一脚注: [*]_.
 391 
 392 .. [*] 这是符号式脚注序列中的另一条目
 393 
 394 .. [4] 这是未引用过的脚注，连同一个不存在的脚注的引用: [4]_.
 395 
 396 引用 Citations
 397 ------------------
 398 
 399 .. [CIT2002] 引用，是文字标签的脚注. 比一般脚注表现的不同.
 400 
 401 就是对上面的引用, [CIT2002]_, 
 402 以及一个 [不存在nonexistent]_ 的引用.(故意引发一个错误报告)
 403 
 404 标签Targets
 405 --------------
 406 
 407 .. _example:
 408 
 409 此段落由显示声明的" `example`_ "标签所指(由注释中的标签声明构成) 
 410 
 411 以下还可以看到
 412 前面的 `行内标记Inline Markup`_ 引用, `行内超链接标签`_ 也支持
 413 
 414 章节的标头是隐含的 标签,由名称来引用，
 415 
 416 比如说: 标签Targets_ , 这是另一节的标题引用 `文档元素 Body Elements`_.
 417 
 418 外部扩展 标签 的插入引用类似以"Python_".
 419 
 420 .. _Python: http://www.python.org/
 421 
 422 标签也可以以匿名或是间接命名方式来引用！
 423 
 424 从而 `随便一个短语`__ 也可以指向本节 标签Targets_ 
 425 
 426 __ 标签Targets_
 427 
 428 这则是 `没有定义标签的超链接 hyperlink reference without a target`_, 
 429 这将引发一个错误
 430 
 431 直接外部链接声明： `《计算机行业 术语对照表(英日中)》`__
 432 
 433 __  http://192.168.2.29:7080/moin/KatakanaTEtab
 434 
 435 :注意: 对于外部链接，可以通过"__ " 前导，直接声明到对应字串上;
 436         但是使用".. _标签:URL"的方式，更加灵活，因为可以通过使用 "标签_" 的形式，在多处进行引用！
 437         (此处的引用因为没有进行过定义，所以会产生报错)
 438 
 439 重复的标签名
 440 ``````````````````````
 441 
 442 在章节标题或是其它隐含标签处的重复名称将生成"有效系统信息"(一级 level-1)
 443 
 444 在扩展标签中的重复名称将生成"警告系统信息"(二级 level-2)
 445 
 446 重复的标签名
 447 `````````````````````` 
 448 
 449 现在有两个  "重复的标签名" 小节, 系统不能通过名称来正确引用他们,
 450 若尝试如此引用:( `重复的标签名`_), 将产生一个报错.
 451 
 452 指引Directives
 453 --------------------
 454 
 455 .. _directives:
 456 
 457 .. contents:: :local:
 458 
 459 一个简单的一些 结构文本 结构指引的例子
 460 
 461 其它的情况请参考 http://docutils.sf.net/spec/rst/directives.html.
 462 
 463 文档部分 Document Parts
 464 ````````````````````````````
 465 
 466 上面为本章节的"内容"指引示例
 467 (一个本地的无标题的内容指引表 Contents_)
 468 
 469 在文档开始(一个全文档范围的 `内容索引 Table of Contents`_).
 470 
 471 图片 Images
 472 ````````````
 473 
 474 以下是图像指引 (可点击，含一超链接引用 -- ):
 475 
 476 .. image:: images/title.png
 477    :target: directives_
 478 
 479 以下是 指向引用:
 480 
 481 .. figure:: images/title.png
 482    :alt: 新结构化文本 reStructuredText, 标记语法
 483 
 484    指向(figure)是可以拥有标题和解说的图片:
 485 
 486    +------------+-----------------------------------------------+
 487    | re         | Revised, revisited, based on 're' module.     |
 488    +------------+-----------------------------------------------+
 489    | Structured | Structure-enhanced text, structuredtext.      |
 490    +------------+-----------------------------------------------+
 491    | Text       | Well it is, isn't it?                         |
 492    +------------+-----------------------------------------------+
 493 
 494    本段落依然属于图片的解说,
 495    This paragraph is also part of the legend.
 496 
 497 警告 Admonitions
 498 ``````````````````````
 499 
 500 .. Attention::  注意！
 501         
 502         Directives at large.(也可以含有其它结构文档元素)        
 503 
 504 .. Caution::    警告！
 505 
 506     Don't take any wooden nickels.
 507 
 508 .. DANGER:: 危险！
 509 
 510     Mad scientist at work!
 511 
 512 .. Error:: 错误……
 513 
 514     Does not compute.
 515 
 516 .. Hint:: 暗示……It's bigger than a bread box.
 517 
 518 .. Important::  重要！
 519    - Wash behind your ears.
 520    - Clean up your room.
 521    - Call your mother.
 522    - Back up your data.
 523 
 524 .. Note:: 解说……
 525     
 526     This is a note.
 527 
 528 .. Tip:: 小贴士……
 529     
 530     15% if the service is good.
 531 
 532 .. WARNING::    警报……
 533     
 534     Strong prose may provoke extreme mental exertion.
 535     Reader discretion is strongly advised.
 536     
 537 
 538 .. admonition::     注意!
 539     
 540     And, by the way...    
 541 
 542     You can make up your own admonition too.
 543 
 544 主题，边注和加红 Topics, Sidebars, and Rubrics
 545 ``````````````````````````````````````````````````````````
 546 
 547 .. sidebar:: 边注标题 Sidebar Title
 548    :subtitle: 副标可选 Optional Subtitle
 549 
 550    这是一个边注，它是活动在主文本之外的一块文本
 551 
 552    .. rubric:: 这是边注里的加红效果
 553 
 554    边注经常使用边线和底色出现在主文档的旁边，用以进行某些专用词的详细描述
 555    
 556 
 557 .. topic:: 主题标题 Topic Title
 558 
 559    这是一个主题 This is a topic.
 560 
 561 .. rubric:: 这是加红效果 This is a rubric
 562 
 563 脚注标签 Target Footnotes
 564 ````````````````````````````````
 565 
 566 .. target-notes::
 567 
 568 使用"target-notes: :" 标签，会自动在脚注位置整理输出所有外部链接信息
 569 
 570 行文本块 Line Blocks
 571 ``````````````````````
 572 
 573 Take it away, Eric the Orchestra Leader!
 574 
 575 .. line-block::
 576 
 577    A one, two, a one two three four
 578 
 579    Half a bee, philosophically,
 580        must, *ipso facto*, half not be.
 581    But half the bee has got to be,
 582        *vis a vis* its entity.  D'you see?
 583 
 584    But can a bee be said to be
 585        or not to be an entire bee,
 586            when half the bee is not a bee,
 587                due to some ancient injury?
 588 
 589    Singing...
 590 
 591 文本置换 Replacement Text
 592 ````````````````````````````````
 593 
 594 我建议你尝试 |Python|_.
 595 
 596 .. |Python| replace:: Python, *最好的* 语言之一
 597 
 598 替换定义 Substitution Definitions
 599 ------------------------------------------------
 600 
 601 行内图片示例  (|example|) :
 602 
 603 .. |EXAMPLE| image:: images/ball1.gif
 604 
 605 (替换定义在HTML原代码中不会有体现.)
 606 
 607 注释 Comments
 608 ----------------
 609 
 610 这有一段例子:
 611 
 612 .. 注释由两个冒号和空格开始 
 613    其它各种 结构化文本语法都支持,除了脚注，超链接，指引，替换定义
 614     Comments begin with two dots and a space. Anything may
 615    follow, except for the syntax of footnotes, hyperlink
 616    标签Targets, directives, or substitution definitions.
 617 
 618    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 619 
 620 (查看HTML原代码来看注释效果 View the HTML source to see the comment.)
 621 
 622 错误处理 Error Handling
 623 ============================
 624 
 625 任何处理时捕获的错误都会生成系统信息.
 626 Any errors caught during processing will generate system messages.
 627 
 628 测试文本将生成5条报错信息，并自动生成
 629 "Docutils System Messages"章节:
 630 
 631 .. section should be added by Docutils automatically