5. 与 LaTeX 标记的区别

尽管标记语言不一样, 但是大多数旧式的 LaTeX 文档的概念, 及其标记的类型都被保留下来 – environment 类似于 reST 的 directive, inline command 类似于 reST 的 role, 等等.

但是, 在它们工作的方式上是有所不同的, 部分原因是标记语言的不同, 另一部分原因是在 Sphinx 中的升级. 本节列出了这些不同, 为了使那些熟悉旧格式的可以快速地了解.

5.1. 行内标记

在行内标记中有这些改变:

• Cross-reference roles

  下面语义的 role 中大部分在先前都有命令相对应, 但是除了格式化其内容作为代码之外, 就不做任何的事了. 现在, 它们交叉引用到已知的目标上 (有些名字也缩短了):

  mod (previously refmodule or module 先前是 refmodule 或 module )

  func (previously function 先前是 function )

  data (new 新增)

  const

  class

  meth (previously method 先前是 method )

  attr (previously member 先前是 member )

  exc (previously exception 先前是 exception )

  cdata

  cfunc (previously cfunction 先前是 cfunction )

  cmacro (previously csimplemacro 先前是 csimplemacro )

  ctype

  另外的不同是处理 func 和 meth , 前者的括号需要增加至调用的名字上 (像 \func{str()}),它们现在有构建的系统增加 – 在源代码中添加它们会导致出现两个括号. 这意味着 :func:`str(object)` 不会像想象的那样工作 – 使用 ``str(object)`` 替换.

• Inline commands implemented as directives

  下面的在 LaTeX 中是行内命令, 但是在 reST 中则是 directive:

  deprecated

  versionadded

  versionchanged

  它们像这样使用:

  .. deprecated:: 2.5
     Reason of deprecation.
  

  同样, 对于 versionadded 和 versionchanged 没有句号增加到文本中.

  note

  warning

  这些用起来像这样:

  .. note::
  
     Content of note.
  

• Otherwise changed commands

  samp 命令以前用于格式化代码, 并在其周围增加引号. 但现在的 samp , 其特点是一个新的高亮系统, 就像 file 那样:

  :samp:`open({filename}, {mode})` results in open(filename, mode)

• Dropped commands

  这些是 LaTeX 中的命令, 但不是 role :

  bfcode

  character (use ``'c'``)

  citetitle (use `Title <URL>`_)

  code (use ``code``)

  email (just write the address in body text)

  filenq

  filevar (use the {...} highlighting feature of file)

  programopt, longprogramopt (use option)

  ulink (use `Title <URL>`_)

  url (just write the URL in body text)

  var (use *var*)

  infinity, plusminus (use the Unicode character)

  shortversion, version (use the |version| and |release| substitutions)

  emph, strong (use the reST markup)

• Backslash escaping

  在 reST 中, 一个反斜杠在正常的文本中和在 role 的内容中都必须转义, 但是在代码块中, 就不需要转义了. 比如: :file:`C:\\Temp\\my.tmp` vs. ``open("C:\Temp\my.tmp")``.

5.2. Information units 信息单元

信息单元 ( ...desc 环境 ) 做成了 reST 的 directive. 这些改变需要注意:

• New names

  “desc” 已经从每个名字中移除. 另外, 这些指示符有了新的名字:

  cfunction (previously cfuncdesc)

  cmacro (previously csimplemacrodesc)

  exception (previously excdesc)

  function (previously funcdesc)

  attribute (previously memberdesc)

  The classdesc* and excclassdesc environments have been dropped, the class and exception directives support classes documented with and without constructor arguments.

• Multiple objects

  与 ...line 命令等同的是:

  .. function:: do_foo(bar)
                do_bar(baz)
  
     Description of the functions.
  

  换句话说, 仅要每行一个签名, 并在同一缩进级别.

• Arguments

  没有 optional 命令. 只要将它们写出输出的样子就可以了:

  .. function:: open(filename[, mode[, buffering]])
  
     Description.
  

  注意: 在签名中不能使用标记.

• Indexing

  ...descni 环境已经被移除了. 为了使一个信息单元不作为索引项, 使用 noindex 选项, 像这样:

  .. function:: foo_*
     :noindex:
  
     Description.
  

• New information units

  有些新的信息单元: 一个称为 “describe” , 可以用以其他的信息单元:

  .. describe:: a == b
  
     The equals operator.
  

  另外的是:

  .. cmdoption:: -O
  
     Describes a command-line option.
  
  .. envvar:: PYTHONINSPECT
  
     Describes an environment variable.
  

5.3. 结构

LaTeX 文档一般以文档级别进行拆分. 现在, 所有文件都是同一文档树的一部分, 就是在 toctree 中指明的 (尽管可以在输出时又将他们拆分). 每一个 toctree 嵌于其他文件作为当前文件的子文档 (在文件系统的布置上, 这个结构并不是必须要被映出). 最顶层的文件是 contents.rst.

但是, 许多旧式的目录结构被保存下来, 名字像下面一样重命名为:

• api -> c-api
• dist -> distutils, with the single TeX file split up
• doc -> documenting
• ext -> extending
• inst -> installing
• lib -> library
• mac -> merged into library, with mac/using.tex moved to using/mac.rst
• ref -> reference
• tut -> tutorial, with the single TeX file split up