re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.3.9@3815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 388 insertions, 0 deletions

diff --git a/docs/user/latex.txt b/docs/user/latex.txt
new file mode 100644
index 000000000..d66586bc7
--- /dev/null
+++ b/docs/user/latex.txt
@@ -0,0 +1,388 @@
+================================
+ Generating LaTeX with Docutils
+================================
+
+:Author: Engelbert Gruber
+:Contact: grubert@users.sourceforge.net
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+Introduction
+============
+
+Producing LaTeX code from reST input could be done in at least two ways:
+
+a. Transform the internal markup into corresponding LaTeX markup e.g.
+   a section title would be written as ```\section{this section ...}``.
+b. Using LaTeX as a typesetting system to produce desired paperwork
+   without caring about loosing document structure information.
+
+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".
+
+Options
+=======
+
+Configuration can be done in two ways (again):
+
+1. Options to the docutils tool: e.g. language selection.
+2. Options to LaTeX via the stylesheet file.
+
+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.
+
+
+=====================  ================================================
+Configuration Issue    Description
+=====================  ================================================
+papersize              Default: a4paper. Paper geometry can be changed  
+                       using ``\geometry{xxx}`` entries.
+
+                       Some possibilities:
+
+                       * a4paper, b3paper, letterpaper, executivepaper,
+                         legalpaper
+                       * landscape, portrait, twoside.
+
+                       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.
+---------------------  ------------------------------------------------
+line spacing           Is done with package *setspace*, which gives
+                       singlespace, onehalfspace and doublespace 
+                       commands. To get documentwide double spacing, 
+                       add this to your stylesheet ::
+
+                         \usepackage{setspace} 
+                         \doublespacing
+
+                       Another way ::
+
+                         \linespread{1.55}
+
+                       And yet another, add ``doublesp`` to the
+                       documentoptions and e.g. ::
+
+                         \setstretch{1.7}
+
+                       for bigger linespacing.
+---------------------  ------------------------------------------------
+font selection         see below
+=====================  ================================================
+
+
+Font selection
+--------------
+
+When generating pdf-files from LaTeX, use the pdflatex command, the files
+are a lot smaller if postscript fonts are used. This *was* fixed by putting 
+``\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.
+
+As ``times`` does not use the appropriate mathematical fonts and ``pslatex``
+does not work with T1 encodings one should use::
+
+  \usepackage{mathptmx}
+  \usepackage[scaled=.90]{helvet}
+  \usepackage{courier}
+
+*font encoding* can be selected with option "font-encoding". Default
+uses package "ae" for old style font encoding use "OT1". 
+
+Hyphenation
+-----------
+
+The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to 
+10000 almost prevents hyphenation. As this produces lines with more spcea 
+between words one should increase LaTeX's ``\tolerance`` for this.
+
+E.g. try ::
+
+  \hyphenpenalty=5000
+  \tolerance=1000
+
+Unicode
+-------
+
+The generated LaTeX documents are in latin1 encoding per default, if unicode
+characters are required one must set ``--output-encoding=utf-8`` install
+`LaTeX unicode`_ support and add::
+
+    \usepackage{ucs}
+    \usepackage[utf8]{inputenc}
+
+to the stylesheet. If LaTeX issues a Warning about unloaded/known characters
+adding ::
+
+    \PreloadUnicodePage{n}
+
+where *n* is the unicode pagenumber, might help.
+
+.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
+
+Table of figures
+----------------
+
+A table of figures can be generated by a command directly to LaTeX::
+
+  .. raw:: LaTeX
+
+     \listoffigures
+
+LaTeX also has a command ``\listoftables``.
+
+Section numbering
+-----------------
+
+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]{}
+
+
+Number pages by chapter
+-----------------------
+
+This can be accomplished with ::
+
+  \usepackage{chappg}
+
+From the documentation 
+
+  Basic operation of the package is to redefine ``\thepage`` to be
+  ``\thechapter-\arabic{page}``, and to cause the page number to be reset
+  (to 1) at the start of each chapter.  So the pages of chapter 3 will
+  be numbered 3-1, 3-2, ..., and the pages of appendix B will be
+  numbered B-1, B-2, ...
+
+See documentation for details and other possibilities.
+
+Images
+------
+
+Images are included in LaTeX by the graphicx package. The supported
+image formats depend on the used driver (dvi, dvips, pdftex, ...).
+
+pdf-image inclusion in pdf files fails, specify ``--graphicx-option=pdftex``
+or ``--graphicx-option=auto``.
+
+
+Commands directly to LaTeX
+==========================
+
+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}
+
+
+Custom title page
+-----------------
+
+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.
+
+Problems
+========
+
+Open to be fixed or open to discussion.
+
+footnotes and citations
+-----------------------
+
+Initially both were implemented using figures, because hyperlinking back
+and forth seemed to be impossible. Later images were put into figures.
+
+This results in footnotes images and figures possibly being mixed at page 
+foot.
+
+* Use LaTeX footnotes and citations for printing or more complex layout.
+* Footnotes and citations done with figures might excell in hyperlink
+  support.
+
+If ``use-latex-citations`` is used a bibliography is inserted right at
+the end of the document. *This should be customizable*.
+
+Tables
+------
+
+: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
+
+  - The strut solution did not work.
+  - setting extrarowheight added ad top of row not between paragraphs in
+    a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
+  - baselineskip/stretch does not help.
+* Should there be two hlines after table head and on table end ?
+* Table: multicol cells are always {l}.
+* The contents of a rowspan cell do not influence table height.
+  (Maybe if we put a tabular inside ?)
+* Table heads and footer for longtable (firstpage lastpage ..).
+* Table cells with multirow and multicolumn
+* literal-blocks in table cells: 
+
+  - If verbatim or flushleft is used one gets vertical space above and below.
+  - This is bad for the topmost paragraph in a cell, therefore the writer
+    uses raggedright. 
+  - Ragged right fails on followup paragraphs as the vertical space would be
+    missing.
+
+Notes
+~~~~~
+
+* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
+
+Miscellaneous
+-------------
+
+* Selection of LaTeX fontsize configurable.
+* Assumed reST linelength for table width setting configurable.
+* literal-block indentation configurable.
+* recongize LaTeX and replace by ``\LaTeX``.
+* Support embed-stylesheet.
+* Sidebar handling.
+* Maybe add end of line after term in definition list. see
+    http://roundup.sf.net/doc-0.5/features.pdf
+* 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:
+  
+  * Define his own document preamble (including the choice to
+    choose his own documentclass.  That would make the ``--documentclass``
+    option superfluous).  I suggest to call this option ``--preamble``
+  * Use two additional hooks to put additional stuff just behind the 
+    ``\begin{document}`` and just before the ``\end{document}`` macros.
+    Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
+    ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such 
+    for larger documents.
+
+* The indentional problematic error in docs/user/rst/demo.txt is not
+  referring anywhere.
+* Footnotes are not all on the same page (as in
+  docs/user/rst/demo.txt) and do not link back and forth.
+* No link to system errors.
+* Hyperlinks are not hyphenated; this leads to bad spacing. See
+  docs/user/rst/demo.txt 2.14 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).
+* keep literal-blocks together on a page, avoid pagebreaks.
+
+  failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
+  the block.
+