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 新增)constclassmeth (previously method 先前是 method )attr (previously member 先前是 member )exc (previously exception 先前是 exception )cdatacfunc (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:
deprecatedversionaddedversionchanged它们像这样使用:
.. deprecated:: 2.5 Reason of deprecation.
同样, 对于 versionadded 和 versionchanged 没有句号增加到文本中.
notewarning这些用起来像这样:
.. note:: Content of note.
Otherwise changed commands
samp 命令以前用于格式化代码, 并在其周围增加引号. 但现在的 samp , 其特点是一个新的高亮系统, 就像 file 那样:
:samp:`open({filename}, {mode})`
results inopen(filename, mode)
Dropped commands
这些是 LaTeX 中的命令, 但不是 role :
bfcodecharacter (use``'c'``
)citetitle (use`Title <URL>`_
)code (use``code``
)email (just write the address in body text)filenqfilevar (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 updoc
->documenting
ext
->extending
inst
->installing
lib
->library
mac
-> merged intolibrary
, withmac/using.tex
moved tousing/mac.rst
ref
->reference
tut
->tutorial
, with the single TeX file split up