Commits

ZoomQuiet committed 5a0e522

+0.5H reST 70%

Comments (0)

Files changed (1)

 详细参考 :ref:`定义规则 <Mref-role>`
 
 
-节 Sections
+节 Sections
 ------------------------
 
 Section headers (:duref:`ref <sections>`) are created by underlining (and
 optionally overlining) the section title with a punctuation character, at least
 as long as the text::
-节头(:duref:`文献<sections>`)创建强调(和
-可选overlining)一个标点符号节的标题,至少
-如文本:
 
+章节头部 (:duref:`参考 <sections>`) 
+由下线(也可有上线)和包含标点的标题 组合创建,
+其中下线要至少等于标准文本的长度::
 
-=================
-This is a heading
-=================
+    =================
+    This is a heading
+    =================
+
+
+.. sidebar:: 注意
+    :subtitle: 中文标题的问题
+
+    在多数编辑器中,全角/半角中文/标点和E文字符的长度是完全没谱的,
+    所以,多数情况下,为保持一致性,译者建议统一使用固定长度的上下标线;
+    比如说78.
+
 
 Normally, there are no heading levels assigned to certain characters as the
 structure is determined from the succession of headings.  However, for the
 Python documentation, this convention is used which you may follow:
+通常并没有对标题的层级指定明确的标线字符.
+不过,对于 Pyhton 文档,可以使用如下约定:
 
-* ``#`` with overline, for parts
-* ``*`` with overline, for chapters
-* ``=``, for sections
-* ``-``, for subsections
-* ``^``, for subsubsections
-* ``"``, for paragraphs
+* ``#`` 有上标线, 用以部分
+* ``*`` 有上标线, 用以章节
+* ``=``, 用以小节
+* ``-``, 用以子节
+* ``^``, 用以子节的子节
+* ``"``, 用以段落
 
 Of course, you are free to use your own marker characters (see the reST
 documentation), and use a deeper nesting level, but keep in mind that most
 target formats (HTML, LaTeX) have a limited supported nesting depth.
 
+当然,你可以自由的使用你自定的标识字符(参考 reST 文档),
+并使用更加深的嵌套层次,
+不过,考虑到兼容多种输出格式(HTML, LaTeX) 最好限制嵌套的深度.
 
-Explicit Markup
----------------
+.. sidebar:: 提示
+    :subtitle: 标题层次体验
+
+    从行文来说,结构化文本组织的文章,更加关注局部文本的结构清晰,
+    以整个图书来说,不建议设定太多的标题级别,一般而言**四级**足够了.
+
+
+
+明确标记 Explicit Markup
+------------------------------------------------------------
 
 "Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for
 most constructs that need special handling, such as footnotes,
 specially-highlighted paragraphs, comments, and generic directives.
+"明确标记" (:duref:`参考 <explicit-markup-blocks>`)
+用以 reST 中需要特殊处理的内容,
+如脚注,特殊高亮段落,注释,以及通用指令.
 
 An explicit markup block begins with a line starting with ``..`` followed by
 whitespace and is terminated by the next paragraph at the same level of
 paragraphs.  This may all sound a bit complicated, but it is intuitive enough
 when you write it.)
 
+明确标记块由``..``开始,紧后跟空格以及跟随的同缩进的文本块.
+(和正文间要有空白行来明确的加以区分.
+可能听起来有点复杂,但当你书写时就能直观的体验到)
+
 
 .. _directives:
 
-Directives
-----------
+指令 Directives
+------------------------------------------------------------
 
 A directive (:duref:`ref <directives>`) is a generic block of explicit markup.
+指令(:duref:`ref <directives>`)就是一个标准的明确标记(Explicit Markup)块.
 Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes
 heavy use of it.
+除了规则,它是reST 的又一个扩展机制,
+Sphinx 大量使用了指令.
 
-Docutils supports the following directives:
+Docutils 支持以下:
 
-* Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
+* 警示 Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
   :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
   :dudir:`tip`, :dudir:`warning` and the generic :dudir:`admonition`.
   (Most themes style only "note" and "warning" specially.)
 
-* Images:
+* 图像 Images:
 
   - :dudir:`image` (see also Images_ below)
   - :dudir:`figure` (an image with caption and optional legend)
 
-* Additional body elements:
+* 其它行文元素 Additional body elements:
 
   - :dudir:`contents` (a local, i.e. for the current file only, table of
     contents)
     class attribute)
   - :dudir:`compound` (a compound paragraph)
 
-* Special tables:
+* 特殊表格 Special tables:
 
   - :dudir:`table` (a table with title)
   - :dudir:`csv-table` (a table generated from comma-separated values)
   - :dudir:`list-table` (a table generated from a list of lists)
 
-* Special directives:
+* 特殊指令 Special directives:
 
   - :dudir:`raw` (include raw target-format markup)
   - :dudir:`include` (include reStructuredText from another file)
     it as relative to the source directory
   - :dudir:`class` (assign a class attribute to the next element) [1]_
 
-* HTML specifics:
+* HTML 专用 specifics:
 
   - :dudir:`meta` (generation of HTML ``<meta>`` tags)
   - :dudir:`title` (override document title)
 
-* Influencing markup:
+* 影响标记 Influencing markup:
 
   - :dudir:`default-role` (set a new default role)
   - :dudir:`role` (create a new role)