2007-08-15 14:28:22 +00:00
|
|
|
.. highlightlang:: rest
|
|
|
|
|
|
|
|
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*.
|
|
|
|
|
|
|
|
| *note*
|
|
|
|
| *warning*
|
|
|
|
|
|
|
|
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 :samp:`open({filename}, {mode})`
|
|
|
|
|
|
|
|
* **Dropped commands**
|
|
|
|
|
|
|
|
These were commands in LaTeX, but are not available as roles:
|
|
|
|
|
|
|
|
| *bfcode*
|
|
|
|
| *character* (use :samp:`\`\`'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")````.
|
|
|
|
|
|
|
|
|
|
|
|
Information units
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
Information units (*...desc* environments) have been made reST directives.
|
|
|
|
These changes to information units should be noted:
|
|
|
|
|
|
|
|
* **New names**
|
|
|
|
|
|
|
|
"desc" has been removed from every name. Additionally, these directives have
|
|
|
|
new names:
|
|
|
|
|
|
|
|
| *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**
|
|
|
|
|
|
|
|
The equivalent of the *...line* commands is::
|
|
|
|
|
|
|
|
.. function:: do_foo(bar)
|
|
|
|
do_bar(baz)
|
|
|
|
|
|
|
|
Description of the functions.
|
|
|
|
|
|
|
|
IOW, just give one signatures per line, at the same indentation level.
|
|
|
|
|
|
|
|
* **Arguments**
|
|
|
|
|
|
|
|
There is no *optional* command. Just give function signatures like they
|
|
|
|
should appear in the output::
|
|
|
|
|
|
|
|
.. function:: open(filename[, mode[, buffering]])
|
|
|
|
|
|
|
|
Description.
|
|
|
|
|
|
|
|
Note: markup in the signature is not supported.
|
|
|
|
|
|
|
|
* **Indexing**
|
|
|
|
|
|
|
|
The *...descni* environments have been dropped. To mark an information unit
|
|
|
|
as unsuitable for index entry generation, use the *noindex* option like so::
|
|
|
|
|
|
|
|
.. function:: foo_*
|
|
|
|
:noindex:
|
|
|
|
|
|
|
|
Description.
|
|
|
|
|
|
|
|
* **New information unit**
|
|
|
|
|
|
|
|
There is a new generic information unit called "describe" which can be used
|
|
|
|
to document things that are not covered by the other units::
|
|
|
|
|
|
|
|
.. describe:: a == b
|
|
|
|
|
|
|
|
The equals operator.
|
|
|
|
|
|
|
|
|
|
|
|
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. 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
|
|
|
|
:file:`contents.rst`.
|
|
|
|
|
|
|
|
However, most of the old directory structure has been kept, with the
|
|
|
|
directories renamed as follows:
|
|
|
|
|
|
|
|
* :file:`api` -> :file:`c-api`
|
|
|
|
* :file:`dist` -> :file:`distutils`, with the single TeX file split up
|
|
|
|
* :file:`doc` -> :file:`documenting`
|
|
|
|
* :file:`ext` -> :file:`extending`
|
|
|
|
* :file:`inst` -> :file:`installing`
|
|
|
|
* :file:`lib` -> :file:`library`
|
Merged revisions 59333-59370 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59343 | georg.brandl | 2007-12-05 08:02:47 +0100 (Wed, 05 Dec 2007) | 2 lines
Fix typo.
........
r59347 | christian.heimes | 2007-12-05 13:31:44 +0100 (Wed, 05 Dec 2007) | 1 line
Fixed quoting and paths in the sqlite project file
........
r59348 | christian.heimes | 2007-12-05 13:45:11 +0100 (Wed, 05 Dec 2007) | 1 line
Fixed error in regrtest. I must have missed the spot.
........
r59350 | christian.heimes | 2007-12-05 13:49:14 +0100 (Wed, 05 Dec 2007) | 1 line
merge -r59315:59316 from py3k: Fix issue #1553: An errornous __length_hint__ can make list() raise a SystemError
........
r59352 | christian.heimes | 2007-12-05 13:52:34 +0100 (Wed, 05 Dec 2007) | 1 line
Added msg to Misc/NEWS
........
r59354 | andrew.kuchling | 2007-12-05 14:27:20 +0100 (Wed, 05 Dec 2007) | 1 line
Spelling fix
........
r59356 | georg.brandl | 2007-12-05 18:56:50 +0100 (Wed, 05 Dec 2007) | 3 lines
Add examples to csv, pprint and traceback docs.
Written by Ross for GHOP.
........
r59358 | raymond.hettinger | 2007-12-05 19:11:08 +0100 (Wed, 05 Dec 2007) | 1 line
Error checking was too aggressive (reported by Chris Tismer)
........
r59359 | georg.brandl | 2007-12-05 19:30:48 +0100 (Wed, 05 Dec 2007) | 2 lines
Add examples to re docs. Written for GHOP by Dan Finnie.
........
r59366 | georg.brandl | 2007-12-05 20:49:21 +0100 (Wed, 05 Dec 2007) | 2 lines
Fix markup.
........
r59367 | christian.heimes | 2007-12-05 20:57:54 +0100 (Wed, 05 Dec 2007) | 1 line
Updated documentation and build_tkinter.py script
........
r59368 | georg.brandl | 2007-12-05 21:03:57 +0100 (Wed, 05 Dec 2007) | 2 lines
Another markup fix.
........
r59369 | ronald.oussoren | 2007-12-05 21:07:36 +0100 (Wed, 05 Dec 2007) | 7 lines
This "fixes" compilation issues for the Carbon._OSA module on OSX Leopard
by purging bindings to OSA's debug API's. Those APIs we're completely
unsupported on OSX 10.4 and are no longer available on OSX 10.5.
Note that this patches a generated file. This is somewhat acceptable because
regenerating the file is non-trivial and wouldn't use system headers anyway.
........
r59370 | christian.heimes | 2007-12-05 21:10:38 +0100 (Wed, 05 Dec 2007) | 1 line
Fixed bug #1557 by using popen.communicate() before popen.wait()
........
2007-12-05 20:18:38 +00:00
|
|
|
* :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`
|
|
|
|
moved to :file:`howto/pythonmac.rst`
|
2007-08-15 14:28:22 +00:00
|
|
|
* :file:`ref` -> :file:`reference`
|
|
|
|
* :file:`tut` -> :file:`tutorial`, with the single TeX file split up
|
|
|
|
|
|
|
|
|
|
|
|
.. XXX more (index-generating, production lists, ...)
|