| Author: | Engelbert Gruber |
|---|---|
| Contact: | grubert@users.sourceforge.net |
| Revision: | 1.32 |
| Date: | 2004-05-09 |
| Copyright: | This document has been placed in the public domain. |
Producing LaTeX code from reST input could be done in at least two ways:
The former might be preferable, but limits to LaTeXs capabilities, so in reality it is a mix. The reality is that LaTeX has a titlepage with title, author and date, by default only title is used. Author and date are shown in the docutils docinfo table and set to blank for LaTeX. To get author and date set by LaTeX specify option "use-LaTeX-docinfo".
Configuration can be done in two ways (again):
The generated LaTeX documents should be kept processable by a standard LaTeX installation (if such a thing exists), therefore the document contains default settings. To allow overwriting defaults the stylesheet is included at last.
Run rst2latex.py --help to see the command-line options, or have look in config documentytion.
| Setting/Config Entry | Description |
|---|---|
| papersize | Default: a4paper. Paper geometry can be changed using \geometry{xxx} entries. Some possibilities:
and a ton of other option setting margins. An example:
\geometry{a5paper,landscape}
|
| paragraph indent | By default LaTeX indents the forst line in a paragraph. The following lines set indentation to zero but add a vertical space between paragraphs.:
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
|
| admonitionwidth | The width for admonitions. Default: 0.9*textwidth, this can be changed e.g.:
\setlength{\admonitionwidth}{0.7\textwidth}
|
| docinfowidth | The width for the docinfo table. Default: 0.9*textwidth, changed to e.g.:
\setlength{\docinfowidth}{0.7\textwidth}
|
| rubric style | The header contains the definition of a new LaTeX command rubric. Inserting:
\renewcommand{\rubric}[1]{\subsection*{
~\hfill {\color{red} #1} \hfill ~}}
sets rubric to subsection style in red. Default: subsection style italic. |
| font selection | see below |
When generating pdf-files from LaTeX, use the pdflatex command, the files are a lot smaller if postscript fonts are used. To do so put \usepackage{times} into the stylesheet.
It is said that the typewriter font in computer modern font, the default LaTeX font package, is too heavy compared to the others. There is a package or some commands too fix this, which i currently cannot find.
Some people diagnose a similar unbalance for the postscript fonts, the package to fix this is \usepackage{pslatex}. pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
A table of figures can be generated by a command directly to LaTeX:
.. raw:: LaTeX \listoffigures
LaTeX also has a command \listoftables.
If section numbering and LaTeX table of contents is used LaTeX and docutils will number sections. To switch off displaying of LaTeX's numbers one has to add following lines to the stylesheet
% no section number display
\makeatletter
\def\@seccntformat#1{}
\makeatother
% no numbers in toc
\renewcommand{\numberline}[1]{}
By means of the reST-raw directive one can give commands directly to LaTeX, e.g. forcing a page break:
.. raw:: LaTeX \newpage
Or setting formulas in LaTeX:
.. raw:: LaTeX $$x^3 + 3x^2a + 3xa^2 + a^3,$$
Or making a colorbox: If someone wants to get a red background for a textblock, she/he can put definecolor{bg}{rgb}{.9,0,0} into style.tex and in reStructuredText do something like this:
|begincolorbox|
Nobody expects the spanish inquisition.
|endcolorbox|
.. |begincolorbox| raw:: LaTeX
\\begin{center}
\\colorbox{bg}{
\\parbox{0.985\\linewidth}{
.. |endcolorbox| raw:: LaTeX
}}
\\end{center}
Currently maketitle only shows the title and subtitle, date and author are shown in the docinfo table.
To change the titlepage layout, e.g. see fancyhdr, one must redefine the maketitle command in the stylesheet:
\renewcommand{\maketitle}{
\begin{titlepage}
\begin{center}
\textsf{TITLE \@title} \\
Date: \today
\end{center}
\end{titlepage}
}
\@title contains the title.
Open to be fixed or open to discussion.
Does not work, or only in verbatim or verb.
| Tablewidth: | reST-documents line length is assumed to be 80 characters. The tablewidth is set relative to this value. If someone produces documents with line length of 132 this will fail. Table width is tried to fit in page even if it is wider than the assumed linewidth, still assumed linewidth is a hook. |
|---|
In tools.txt the option tables right column, there should be some more spacing between the description and the next paragraph "Default:".
Paragraph separation in tables is hairy. see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
Should there be two hlines after table head and on table end ?
Table: multicol cells are always {l}.
Table heads and footer for longtable (firstpage lastpage ..).
Longtable does not work with multirow
Tabularx says "do not use any multicolmn which spans any X column. maybe use ltxtable instead of tabularx (Longtable combined with tabularx). but ltxtable disables longtable's multicolumn.
Table cells with multirow and multicolumn
The underscore _ does not work in literal-blocks, has different width. I tried
recongize LaTeX and replace by \LaTeX.
Support embed-stylesheet.
the ^-sign is problematic: using mathmode wedge is usually the wrong font.
Sidebar handling.
Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
center subsection{Abstract} gives a LaTeX error here. ! LaTeX Error: Something's wrong--perhaps a missing \item. Committed a HACK: centering by hfill.
Document errors are also too silent.
Use optionlist for docinfo, the table does only work for single page.
Consider peter funk's hooks for TeXpert:
Hyphens: co-developers should be co--developers ?
The indentional problematic error in test.txt is not referring anywhere.
Footnotes are not all on the same page (as in tools/test.txt) and do not link back and forth.
No link to system errors.
Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt 2.14 directives directives
Meta keywords into pdf ?
Pagestyle headings does not work, when sections are starred.
For additional docinfo items: the field_body is inserted as text, i.e. no markup is done.
Multiple author entries in docinfo (same thing as in html).
pslatex has not textbackslash ind bold ?
make use (but test against pslatex)
\textbackslash \backslash \ \textbar \mid | \textless < < \textgreater > > \textasciicircum \hat ^ \textasciitilde \tilde ~ \textbullet \bullet gefüllter Kreis auf halber Höhe \textperiodcentered \cdot · \textvisiblespace (n.v.) sichtbares Leerzeichen