docs/user/latex.txt

   1 =======================
   2  Docutils LaTeX Writer
   3 =======================
   4
   5 :Author: Engelbert Gruber
   6 :Contact: grubert@users.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. contents::
  12
  13
  14 Introduction
  15 ============
  16
  17 Producing LaTeX code from reST input could be done in at least two ways:
  18
  19 a. Transform the internal markup into corresponding LaTeX markup e.g.
  20    a section title would be written as ```\section{this section ...}``.
  21 b. Using LaTeX as a typesetting system to produce desired paperwork
  22    without caring about loosing document structure information.
  23
  24 The former might be preferable, but limits to LaTeXs capabilities, so
  25 in reality it is a mix. The reality is that LaTeX has a titlepage with
  26 title, author and date, by default only title is used. Author and date
  27 are shown in the docutils docinfo table and set to blank for LaTeX.
  28 To get author and date set by LaTeX specify option "use-LaTeX-docinfo".
  29
  30 Options
  31 =======
  32
  33 Configuration can be done in two ways (again):
  34
  35 1. Options to the docutils tool: e.g. language selection.
  36 2. Options to LaTeX via the stylesheet file.
  37
  38 The generated LaTeX documents should be kept processable by a standard
  39 LaTeX installation (if such a thing exists), therefore the document
  40 contains default settings. To allow *overwriting defaults* the stylesheet
  41 is included at last.
  42
  43 Run ``rst2latex.py --help`` to see the command-line options, or have look in
  44 config documentytion.
  45
  46
  47 =====================  ================================================
  48 Setting/Config Entry   Description
  49 =====================  ================================================
  50 papersize              Default: a4paper. Paper geometry can be changed
  51                        using ``\geometry{xxx}`` entries.
  52
  53                        Some possibilities:
  54
  55                        * a4paper, b3paper, letterpaper, executivepaper,
  56                          legalpaper
  57                        * landscape, portrait, twoside.
  58
  59                        and a ton of other option setting margins.
  60
  61                        An example::
  62
  63                          \geometry{a5paper,landscape}
  64 ---------------------  ------------------------------------------------
  65 paragraph indent       By default LaTeX indents the forst line in a
  66                        paragraph. The following lines set indentation
  67                        to zero but add a vertical space between
  68                        paragraphs.::
  69
  70                          \setlength{\parindent}{0pt}
  71                          \setlength{\parskip}{6pt plus 2pt minus 1pt}
  72 ---------------------  ------------------------------------------------
  73 admonitionwidth        The width for admonitions.
  74                        Default: 0.9*textwidth, this can be changed
  75                        e.g.::
  76
  77                          \setlength{\admonitionwidth}{0.7\textwidth}
  78 ---------------------  ------------------------------------------------
  79 docinfowidth           The width for the docinfo table.
  80                        Default: 0.9*textwidth, changed to e.g.::
  81
  82                          \setlength{\docinfowidth}{0.7\textwidth}
  83 ---------------------  ------------------------------------------------
  84 rubric style           The header contains the definition of a new
  85                        LaTeX command rubric. Inserting::
  86
  87                          \renewcommand{\rubric}[1]{\subsection*{
  88                            ~\hfill {\color{red} #1} \hfill ~}}
  89
  90                        sets rubric to subsection style in red.
  91
  92                        Default: subsection style italic.
  93 ---------------------  ------------------------------------------------
  94 font selection         see below
  95 =====================  ================================================
  96
  97 Missing options
  98 ---------------
  99
 100 * Selection of LaTeX fontsize.
 101 * Assumed reST linelength for table width setting.
 102
 103 Font selection
 104 --------------
 105
 106 When generating pdf-files from LaTeX, use the pdflatex command, the files
 107 are a lot smaller if postscript fonts are used. To do so put
 108 ``\usepackage{times}`` into the stylesheet.
 109
 110 It is said that the typewriter font in computer modern font, the default
 111 LaTeX font package, is too heavy compared to the others. There is a package
 112 or some commands too fix this, which i currently cannot find.
 113
 114 Some people diagnose a similar unbalance for the postscript fonts, the
 115 package to fix this is ``\usepackage{pslatex}``.
 116 pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
 117
 118 Table of figures
 119 ----------------
 120
 121 A table of figures can be generated by a command directly to LaTeX::
 122
 123   .. raw:: LaTeX
 124
 125      \listoffigures
 126
 127 LaTeX also has a command ``\listoftables``.
 128
 129 Section numbering
 130 -----------------
 131
 132 If section numbering and LaTeX table of contents is used LaTeX and
 133 docutils will number sections. To switch off displaying of LaTeX's
 134 numbers one has to add following lines to the stylesheet ::
 135
 136   % no section number display
 137   \makeatletter
 138   \def\@seccntformat#1{}
 139   \makeatother
 140   % no numbers in toc
 141   \renewcommand{\numberline}[1]{}
 142
 143
 144 Commands directly to LaTeX
 145 ==========================
 146
 147 By means of the reST-raw directive one can give commands directly to
 148 LaTeX, e.g. forcing a page break::
 149
 150   .. raw:: LaTeX
 151
 152      \newpage
 153
 154
 155 Or setting formulas in LaTeX::
 156
 157   .. raw:: LaTeX
 158
 159      $$x^3 + 3x^2a + 3xa^2 + a^3,$$
 160
 161
 162 Or making a colorbox: If someone wants to get a red background for a textblock,
 163 she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
 164 reStructuredText do something like this::
 165
 166   |begincolorbox|
 167   Nobody expects the spanish inquisition.
 168   |endcolorbox|
 169
 170   .. |begincolorbox| raw:: LaTeX
 171
 172      \\begin{center}
 173      \\colorbox{bg}{
 174      \\parbox{0.985\\linewidth}{
 175
 176   .. |endcolorbox| raw:: LaTeX
 177
 178      }}
 179      \\end{center}
 180
 181
 182 Custom title page
 183 -----------------
 184
 185 Currently maketitle only shows the title and subtitle, date and author are shown
 186 in the docinfo table.
 187
 188 To change the titlepage layout, e.g. see fancyhdr, one must redefine the
 189 maketitle command in the stylesheet::
 190
 191   \renewcommand{\maketitle}{
 192     \begin{titlepage}
 193       \begin{center}
 194       \textsf{TITLE \@title} \\
 195       Date: \today
 196       \end{center}
 197     \end{titlepage}
 198   }
 199
 200 ``\@title`` contains the title.
 201
 202 Problems
 203 ========
 204
 205 Open to be fixed or open to discussion.
 206
 207 Tilde in italian
 208 ----------------
 209
 210 Does not work, or only in verbatim or verb.
 211
 212 Tables
 213 ------
 214
 215 :Tablewidth: reST-documents line length is assumed to be 80 characters. The
 216              tablewidth is set relative to this value. If someone produces
 217              documents with line length of 132 this will fail.
 218
 219              Table width is tried to fit in page even if it is wider than
 220              the assumed linewidth, still assumed linewidth is a hook.
 221
 222 * In tools.txt the option tables right column, there should be some more spacing
 223   between the description and the next paragraph "Default:".
 224
 225   Paragraph separation in tables is hairy.
 226   see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
 227
 228   - The strut solution did not work.
 229   - setting extrarowheight added ad top of row not between paragraphs in
 230     a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
 231   - baselineskip/stretch does not help.
 232 * Should there be two hlines after table head and on table end ?
 233 * Table: multicol cells are always {l}.
 234 * Table heads and footer for longtable (firstpage lastpage ..).
 235 * Longtable does not work with multirow
 236 * Tabularx says "do not use any multicolmn which spans any X column.
 237   maybe use ltxtable instead of tabularx (Longtable combined with tabularx).
 238   but ltxtable disables longtable's multicolumn.
 239 * Table cells with multirow and multicolumn
 240 * table-style booktabs: booktabs.sty 1.00 does not work with longtable.
 241
 242 Miscellaneous
 243 -------------
 244
 245 * The underscore ``_`` does not work in literal-blocks, has different width.
 246   I tried
 247
 248   - Underline a blank ``\underline{ }`` to low, as in windows-xp.
 249     And elsewhere use this.
 250   - Escape it ``{\_}`` to narrow
 251   - Subscript a hyphen ``$_{\tt-}$`` too wide and thin
 252   - ``$_{-}$`` the same.
 253
 254 * recongize LaTeX and replace by ``\LaTeX``.
 255 * Support embed-stylesheet.
 256 * the ^-sign is problematic: using mathmode wedge is usually the wrong font.
 257 * Sidebar handling.
 258 * Maybe add end of line after term in definition list. see
 259     http://roundup.sf.net/doc-0.5/features.pdf
 260 * Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
 261 * center subsection{Abstract} gives a LaTeX error here.
 262   ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
 263   Committed a HACK: centering by hfill.
 264 * Document errors are also too silent.
 265 * Use optionlist for docinfo, the table does only work for single page.
 266 * Consider peter funk's hooks for TeXpert:
 267
 268   * Define his own document preamble (including the choice to
 269     choose his own documentclass.  That would make the ``--documentclass``
 270     option superfluous).  I suggest to call this option ``--preamble``
 271   * Use two additional hooks to put additional stuff just behind the
 272     ``\begin{document}`` and just before the ``\end{document}`` macros.
 273     Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
 274     ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
 275     for larger documents.
 276
 277 * Hyphens: co-developers should be co--developers ?
 278 * The indentional problematic error in test.txt is not referring anywhere.
 279 * Footnotes are not all on the same page (as in tools/test.txt) and do not link back
 280   and forth.
 281 * No link to system errors.
 282 * Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt
 283   2.14 directives directives
 284 * Meta keywords into pdf ?
 285 * Pagestyle headings does not work, when sections are starred.
 286 * For additional docinfo items: the field_body is inserted as text, i.e. no
 287   markup is done.
 288 * Multiple author entries in docinfo (same thing as in html).
 289 * pslatex has not textbackslash in bold ?
 290 * make use (but test against pslatex) ::
 291
 292     \textbackslash      \backslash \
 293     \textbar            \mid       |
 294     \textless           <          <
 295     \textgreater        >          >
 296     \textasciicircum    \hat       ^
 297     \textasciitilde     \tilde     ~
 298     \textbullet         \bullet    gefüllter Kreis auf halber Höhe
 299     \textperiodcentered \cdot      ·
 300     \textvisiblespace   (n.v.)     sichtbares Leerzeichen
 301