← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/documenting/fromlatex.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/documenting/fromlatex.rst
 
1
.. highlightlang:: rest
 
2
 
 
3
Differences to the LaTeX markup
 
4
===============================
 
5
 
 
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.
 
9
 
 
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.
 
14
 
 
15
Inline markup
 
16
-------------
 
17
 
 
18
These changes have been made to inline markup:
 
19
 
 
20
* **Cross-reference roles**
 
21
 
 
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):
 
25
 
 
26
  | *mod* (previously *refmodule* or *module*)
 
27
  | *func* (previously *function*)
 
28
  | *data* (new)
 
29
  | *const*
 
30
  | *class*
 
31
  | *meth* (previously *method*)
 
32
  | *attr* (previously *member*)
 
33
  | *exc* (previously *exception*)
 
34
  | *cdata*
 
35
  | *cfunc* (previously *cfunction*)
 
36
  | *cmacro* (previously *csimplemacro*)
 
37
  | *ctype*
 
38
 
 
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!
 
44
 
 
45
* **Inline commands implemented as directives**
 
46
 
 
47
  These were inline commands in LaTeX, but are now directives in reST:
 
48
 
 
49
  | *deprecated*
 
50
  | *versionadded*
 
51
  | *versionchanged*
 
52
 
 
53
  These are used like so::
 
54
 
 
55
     .. deprecated:: 2.5
 
56
        Reason of deprecation.
 
57
 
 
58
  Also, no period is appended to the text for *versionadded* and
 
59
  *versionchanged*.
 
60
 
 
61
  | *note*
 
62
  | *warning*
 
63
 
 
64
  These are used like so::
 
65
 
 
66
     .. note::
 
67
 
 
68
        Content of note.
 
69
 
 
70
* **Otherwise changed commands**
 
71
 
 
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
 
74
  *file* does:
 
75
 
 
76
     ``:samp:`open({filename}, {mode})``` results in :samp:`open({filename}, {mode})`
 
77
 
 
78
* **Dropped commands**
 
79
 
 
80
  These were commands in LaTeX, but are not available as roles:
 
81
 
 
82
  | *bfcode*
 
83
  | *character* (use :samp:`\`\`'c'\`\``)
 
84
  | *citetitle* (use ```Title <URL>`_``)
 
85
  | *code* (use ````code````)
 
86
  | *email* (just write the address in body text)
 
87
  | *filenq*
 
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)
 
96
 
 
97
* **Backslash escaping**
 
98
 
 
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")````.
 
102
 
 
103
 
 
104
Information units
 
105
-----------------
 
106
 
 
107
Information units (*...desc* environments) have been made reST directives.
 
108
These changes to information units should be noted:
 
109
 
 
110
* **New names**
 
111
 
 
112
  "desc" has been removed from every name.  Additionally, these directives have
 
113
  new names:
 
114
 
 
115
  | *cfunction* (previously *cfuncdesc*)
 
116
  | *cmacro* (previously *csimplemacrodesc*)
 
117
  | *exception* (previously *excdesc*)
 
118
  | *function* (previously *funcdesc*)
 
119
  | *attribute* (previously *memberdesc*)
 
120
 
 
121
  The *classdesc\** and *excclassdesc* environments have been dropped, the
 
122
  *class* and *exception* directives support classes documented with and without
 
123
  constructor arguments.
 
124
 
 
125
* **Multiple objects**
 
126
 
 
127
  The equivalent of the *...line* commands is::
 
128
 
 
129
     .. function:: do_foo(bar)
 
130
                   do_bar(baz)
 
131
 
 
132
        Description of the functions.
 
133
 
 
134
  IOW, just give one signatures per line, at the same indentation level.
 
135
 
 
136
* **Arguments**
 
137
 
 
138
  There is no *optional* command.  Just give function signatures like they
 
139
  should appear in the output::
 
140
 
 
141
     .. function:: open(filename[, mode[, buffering]])
 
142
 
 
143
        Description.
 
144
 
 
145
  Note: markup in the signature is not supported.
 
146
 
 
147
* **Indexing**
 
148
 
 
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::
 
151
 
 
152
     .. function:: foo_*
 
153
        :noindex:
 
154
 
 
155
        Description.
 
156
 
 
157
* **New information units**
 
158
 
 
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::
 
161
 
 
162
     .. describe:: a == b
 
163
 
 
164
        The equals operator.
 
165
 
 
166
  The others are::
 
167
 
 
168
     .. cmdoption:: -O
 
169
 
 
170
        Describes a command-line option.
 
171
 
 
172
     .. envvar:: PYTHONINSPECT
 
173
 
 
174
        Describes an environment variable.
 
175
 
 
176
 
 
177
Structure
 
178
---------
 
179
 
 
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`.
 
186
 
 
187
However, most of the old directory structure has been kept, with the
 
188
directories renamed as follows:
 
189
 
 
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
 
200
 
 
201
 
 
202
.. XXX more (index-generating, production lists, ...)