Release 0.4: tagging released revisiondocutils-0.4

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

1 files changed, 0 insertions, 388 deletions

diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
deleted file mode 100644
index ce8447692..000000000
--- a/docutils/docs/user/latex.txt
+++ /dev/null
@@ -1,388 +0,0 @@
-================================
- 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, ...).
-
-If 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.
-