Differences to the LaTeX markup
Though the markup language is different, most of the concepts and markup types
of the old LaTeX docs have been kept – environments as reST directives, inline
commands as reST roles and so forth.
However, there are some differences in the way these work, partly due to the
differences in the markup languages, partly due to improvements in Sphinx. This
section lists these differences, in order to give those familiar with the old
format a quick overview of what they might run into.
Inline markup
These changes have been made to inline markup:
Cross-reference roles
Most of the following semantic roles existed previously as inline commands,
but didn’t do anything except formatting the content as code. Now, they
cross-reference to known targets (some names have also been shortened):
mod (previously refmodule or module)
func (previously function)
data (new)
const
class
meth (previously method)
attr (previously member)
exc (previously exception)
cdata
cfunc (previously cfunction)
cmacro (previously csimplemacro)
ctype
Also different is the handling of func and meth: while previously
parentheses were added to the callable name (like \func{str()}), they are
now appended by the build system – appending them in the source will result
in double parentheses. This also means that :func:`str(object)` will not
work as expected – use ``str(object)`` instead!
Inline commands implemented as directives
These were inline commands in LaTeX, but are now directives in reST:
deprecated
versionadded
versionchanged
These are used like so:
.. deprecated:: 2.5
Reason of deprecation.
Also, no period is appended to the text for versionadded and
versionchanged.
These are used like so:
.. note::
Content of note.
Otherwise changed commands
The samp command previously formatted code and added quotation marks around
it. The samp role, however, features a new highlighting system just like
file does:
:samp:`open({filename}, {mode})` results in open(filename, mode)
Dropped commands
These were commands in LaTeX, but are not available as roles:
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
In reST, a backslash must be escaped in normal text, and in the content of
roles. However, in code literals and literal blocks, it must not be escaped.
Example: :file:`C:\\Temp\\my.tmp` vs. ``open("C:\Temp\my.tmp")``.
Structure
The LaTeX docs were split in several toplevel manuals. Now, all files are part
of the same documentation tree, as indicated by the toctree directives in the
sources (though individual output formats may choose to split them up into parts
again). Every toctree directive embeds other files as subdocuments of the
current file (this structure is not necessarily mirrored in the filesystem
layout). The toplevel file is contents.rst.
However, most of the old directory structure has been kept, with the
directories renamed as follows:
- 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
|