1
.. highlightlang:: rest
3
Differences to the LaTeX markup
4
===============================
6
Though the markup language is different, most of the concepts and markup types
7
of the old LaTeX docs have been kept -- environments as reST directives, inline
8
commands as reST roles and so forth.
10
However, there are some differences in the way these work, partly due to the
11
differences in the markup languages, partly due to improvements in Sphinx. This
12
section lists these differences, in order to give those familiar with the old
13
format a quick overview of what they might run into.
18
These changes have been made to inline markup:
20
* **Cross-reference roles**
22
Most of the following semantic roles existed previously as inline commands,
23
but didn't do anything except formatting the content as code. Now, they
24
cross-reference to known targets (some names have also been shortened):
26
| *mod* (previously *refmodule* or *module*)
27
| *func* (previously *function*)
31
| *meth* (previously *method*)
32
| *attr* (previously *member*)
33
| *exc* (previously *exception*)
35
| *cfunc* (previously *cfunction*)
36
| *cmacro* (previously *csimplemacro*)
39
Also different is the handling of *func* and *meth*: while previously
40
parentheses were added to the callable name (like ``\func{str()}``), they are
41
now appended by the build system -- appending them in the source will result
42
in double parentheses. This also means that ``:func:`str(object)``` will not
43
work as expected -- use ````str(object)```` instead!
45
* **Inline commands implemented as directives**
47
These were inline commands in LaTeX, but are now directives in reST:
53
These are used like so::
56
Reason of deprecation.
58
Also, no period is appended to the text for *versionadded* and
64
These are used like so::
70
* **Otherwise changed commands**
72
The *samp* command previously formatted code and added quotation marks around
73
it. The *samp* role, however, features a new highlighting system just like
76
``:samp:`open({filename}, {mode})``` results in :samp:`open({filename}, {mode})`
78
* **Dropped commands**
80
These were commands in LaTeX, but are not available as roles:
83
| *character* (use :samp:`\`\`'c'\`\``)
84
| *citetitle* (use ```Title <URL>`_``)
85
| *code* (use ````code````)
86
| *email* (just write the address in body text)
88
| *filevar* (use the ``{...}`` highlighting feature of *file*)
89
| *programopt*, *longprogramopt* (use *option*)
90
| *ulink* (use ```Title <URL>`_``)
91
| *url* (just write the URL in body text)
92
| *var* (use ``*var*``)
93
| *infinity*, *plusminus* (use the Unicode character)
94
| *shortversion*, *version* (use the ``|version|`` and ``|release|`` substitutions)
95
| *emph*, *strong* (use the reST markup)
97
* **Backslash escaping**
99
In reST, a backslash must be escaped in normal text, and in the content of
100
roles. However, in code literals and literal blocks, it must not be escaped.
101
Example: ``:file:`C:\\Temp\\my.tmp``` vs. ````open("C:\Temp\my.tmp")````.
107
Information units (*...desc* environments) have been made reST directives.
108
These changes to information units should be noted:
112
"desc" has been removed from every name. Additionally, these directives have
115
| *cfunction* (previously *cfuncdesc*)
116
| *cmacro* (previously *csimplemacrodesc*)
117
| *exception* (previously *excdesc*)
118
| *function* (previously *funcdesc*)
119
| *attribute* (previously *memberdesc*)
121
The *classdesc\** and *excclassdesc* environments have been dropped, the
122
*class* and *exception* directives support classes documented with and without
123
constructor arguments.
125
* **Multiple objects**
127
The equivalent of the *...line* commands is::
129
.. function:: do_foo(bar)
132
Description of the functions.
134
IOW, just give one signatures per line, at the same indentation level.
138
There is no *optional* command. Just give function signatures like they
139
should appear in the output::
141
.. function:: open(filename[, mode[, buffering]])
145
Note: markup in the signature is not supported.
149
The *...descni* environments have been dropped. To mark an information unit
150
as unsuitable for index entry generation, use the *noindex* option like so::
157
* **New information units**
159
There are new generic information units: One is called "describe" and can be
160
used to document things that are not covered by the other units::
170
Describes a command-line option.
172
.. envvar:: PYTHONINSPECT
174
Describes an environment variable.
180
The LaTeX docs were split in several toplevel manuals. Now, all files are part
181
of the same documentation tree, as indicated by the *toctree* directives in the
182
sources (though individual output formats may choose to split them up into parts
183
again). Every *toctree* directive embeds other files as subdocuments of the
184
current file (this structure is not necessarily mirrored in the filesystem
185
layout). The toplevel file is :file:`contents.rst`.
187
However, most of the old directory structure has been kept, with the
188
directories renamed as follows:
190
* :file:`api` -> :file:`c-api`
191
* :file:`dist` -> :file:`distutils`, with the single TeX file split up
192
* :file:`doc` -> :file:`documenting`
193
* :file:`ext` -> :file:`extending`
194
* :file:`inst` -> :file:`installing`
195
* :file:`lib` -> :file:`library`
196
* :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`
197
moved to :file:`using/mac.rst`
198
* :file:`ref` -> :file:`reference`
199
* :file:`tut` -> :file:`tutorial`, with the single TeX file split up
202
.. XXX more (index-generating, production lists, ...)
added
removed
Doc/documenting/fromlatex.rst
