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, ...)