New ``latex_preamble`` setting, PDF standard fonts as default.

Use Times/Helvetica/Courier (the PDF standard fonts) as default fonts.

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

11 files changed, 67 insertions, 25 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 530be1491..596eba314 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -35,6 +35,8 @@ Changes Since 0.6
   - Preserve runs of spaces in `inline literals`__.
   - Deprecate ``figure_footnotes`` setting.
   - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
+  - New ``latex_preamble`` setting.
+  - PDF standard fonts (Times/Helvetica/Courier) as default.
 
 __ docs/ref/restructuredtext.html#inline-literals
 __ docs/user/config.html#docutils-footnotes
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 34c56d0d3..0e84b7729 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -30,6 +30,8 @@ Components:
   - Preserve runs of spaces in 'inline literals'.
   - Deprecate ``figure_footnotes`` setting.
   - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
+  - New ``latex_preamble`` setting.
+  - PDF standard fonts (Times/Helvetica/Courier) as default.
 
 __ docs/user/config.html#docutils-footnotes
 
diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt
index 60f322927..54e6e4b6c 100644
--- a/docutils/docs/api/publisher.txt
+++ b/docutils/docs/api/publisher.txt
@@ -312,12 +312,6 @@ docinfo
 
     'dedication' and 'abstract' are always moved to separate parts.
 
-.. footer
-    ``parts['footer']`` contains the document footer content, meant to
-    appear at the bottom of every printed page.
-    It is not used in the standard template but can be in a custom template
-    to define running heads/foots.
-
 fallbacks
     ``parts['fallbacks']`` contains fallback definitions for
     Docutils-specific commands and environments.
@@ -326,6 +320,10 @@ head_prefix
     ``parts['head_prefix']`` contains the declaration of
     documentclass and document options.
 
+latex_preamble
+    ``parts['latex_preamble']`` contains the argument of the
+    ``--latex-preamble`` option.
+
 pdfsetup
      ``parts['pdfsetup']`` contains the PDF properties
      ("hyperref" package setup).
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 6728ba1b7..1383a5ba0 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -2103,20 +2103,6 @@ Which packages do we want to use?
 Default layout
 --------------
 
-* Which `default font`__ should we use for the output?
-
-  Proposal: Use one of the Postscript default fonts supported by standard
-  LaTeX (pages 10 and 11 of the `PSNFSS documentation`_), e.g. Times or
-  Palatino.
-
-  In PDF 1.3 there are 14 standard fonts:
-
-    Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Helvetica,
-    Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Courier,
-    Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats
-
-  The rest you need to embed.
-
 * Use italic instead of slanted for titlereference?
 
 * Start a new paragraph after lists (as currently)
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 9b0eb20b6..49d06cae8 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -951,8 +951,10 @@ _`font_encoding`
 
 embed_stylesheet
     Embed the stylesheet(s) in the header of the output file.  The
-    stylesheets must be accessible during processing. Also defined for
-    the `HTML Writer`__ (with default *on*).
+    stylesheets must be accessible during processing.  Currently, this
+    fails if the file is not available via the given path (i.e. the
+    file is *not* searched in the `TeX input path`_).
+    Also defined for the `HTML Writer`__ (with default *on*).
 
     Default: off.  Options: ``--embed-stylesheet, --link-stylesheet``.
 
@@ -970,12 +972,16 @@ stylesheet
     referenced with ``\usepackage`` (extension ``.sty`` or no extension) or
     ``\input`` (any other extension).
 
-    Default: no stylesheet ("").  Option: ``--stylesheet``.
+    LaTeX will search the specified files in the `TeX input path`_.
 
+    Default: no stylesheet ("").  Option: ``--stylesheet``.
 
     __ `stylesheet_path [latex2e writer]`_
     __ `embed_stylesheet [latex2e writer]`_
     __ `stylesheet [html4css1 writer]`_
+    .. _TeX input path:
+       http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
+
 
 .. _stylesheet_path [latex2e writer]:
 
@@ -996,6 +1002,22 @@ stylesheet_path
     __
     __ `stylesheet [latex2e writer]`_
 
+
+_`latex_preamble`
+    LaTeX code that will be inserted in the document preamble.
+    Can be used to load packages with options or (re-) define LaTeX
+    macros without writing a custom style file (new in Docutils 0.7).
+
+    Default: Load the "PDF standard fonts" (Times, Helvetica,
+    Courier)::
+
+      \usepackage{mathptmx} % Times
+      \usepackage[scaled=.90]{helvet}
+      \usepackage{courier}
+
+    Option: ``--latex-preamble``
+
+
 .. _template [latex2e writer]:
 
 template
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index fcd3e9233..462304569 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -33,6 +33,10 @@ class Writer(writers.Writer):
     default_template = 'default.tex'
     default_template_path = os.path.dirname(__file__)
 
+    default_preamble = '\n'.join([r'% PDF Standard Fonts',
+                                  r'\usepackage{mathptmx} % Times',
+                                  r'\usepackage[scaled=.90]{helvet}',
+                                  r'\usepackage{courier}'])
     settings_spec = (
         'LaTeX-Specific Options',
         'The LaTeX "--output-encoding" default is "latin-1:strict".',
@@ -94,6 +98,10 @@ class Writer(writers.Writer):
           ['--embed-stylesheet'],
           {'default': 0, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
+         ('Customization by LaTeX code in the preamble. '
+          'Default: select PDF standard fonts (Times, Helvetica, Courier).',
+          ['--latex-preamble'],
+          {'default': default_preamble}),
          ('Specify the template file. Default: "%s".' % default_template,
           ['--template'],
           {'default': default_template, 'metavar': '<file>'}),
@@ -199,8 +207,8 @@ class Writer(writers.Writer):
     config_section = 'latex2e writer'
     config_section_dependencies = ('writers',)
 
-    head_parts = ('head_prefix', 'requirements', 'stylesheet',
-                  'fallbacks', 'pdfsetup', 'title', 'subtitle')
+    head_parts = ('head_prefix', 'requirements', 'latex_preamble',
+                  'stylesheet', 'fallbacks', 'pdfsetup', 'title', 'subtitle')
     visitor_attributes = head_parts + ('body_pre_docinfo', 'docinfo',
                                        'dedication', 'abstract', 'body')
 
@@ -942,6 +950,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.head_prefix = [r'\documentclass[%s]{%s}' %
                             (self.d_options, self.settings.documentclass)]
         self.requirements = SortableDict() # made a list in depart_document()
+        self.latex_preamble = [settings.latex_preamble]
         self.stylesheet = []
         self.fallbacks = SortableDict() # made a list in depart_document()
         self.pdfsetup = [] # PDF properties (hyperref package)
diff --git a/docutils/docutils/writers/latex2e/default.tex b/docutils/docutils/writers/latex2e/default.tex
index c1857a8b3..c6e8ec3bd 100644
--- a/docutils/docutils/writers/latex2e/default.tex
+++ b/docutils/docutils/writers/latex2e/default.tex
@@ -2,6 +2,8 @@
 $head_prefix\usepackage{fixltx2e} % LaTeX patches, \textsubscript
 \usepackage{cmap} % fix search and cut-and-paste in PDF
 $requirements
+%%% Custom LaTeX preamble
+$latex_preamble
 %%% User specified packages and stylesheets
 $stylesheet
 %%% Fallback definitions for Docutils-specific commands
diff --git a/docutils/docutils/writers/latex2e/titlepage.tex b/docutils/docutils/writers/latex2e/titlepage.tex
index dc798c9ee..f7f35f9be 100644
--- a/docutils/docutils/writers/latex2e/titlepage.tex
+++ b/docutils/docutils/writers/latex2e/titlepage.tex
@@ -1,5 +1,7 @@
 % generated by Docutils <http://docutils.sourceforge.net/>
 $head_prefix$requirements
+%%% Custom LaTeX preamble
+$latex_preamble
 %%% User specified packages and stylesheets
 $stylesheet
 %%% Fallback definitions for Docutils-specific commands
diff --git a/docutils/test/functional/expected/latex_docinfo.tex b/docutils/test/functional/expected/latex_docinfo.tex
index fc6861326..6aca23c5a 100644
--- a/docutils/test/functional/expected/latex_docinfo.tex
+++ b/docutils/test/functional/expected/latex_docinfo.tex
@@ -7,6 +7,12 @@
 \usepackage[latin1]{inputenc}
 \usepackage{ifthen}
 
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
 %%% User specified packages and stylesheets
 
 %%% Fallback definitions for Docutils-specific commands
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index 12ce43877..90cda8c95 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -17,6 +17,12 @@
 \newlength{\DUtablewidth} % internal use in tables
 \usepackage{tabularx}
 
+%%% Custom LaTeX preamble
+% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+
 %%% User specified packages and stylesheets
 
 %%% Fallback definitions for Docutils-specific commands
diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py
index bb3466b50..6e75930f9 100755
--- a/docutils/test/test_writers/test_latex2e.py
+++ b/docutils/test/test_writers/test_latex2e.py
@@ -36,6 +36,8 @@ r"""% generated by Docutils <http://docutils.sourceforge.net/>
 $head_prefix\usepackage{fixltx2e} % LaTeX patches, \textsubscript
 \usepackage{cmap} % fix search and cut-and-paste in PDF
 $requirements
+%%% Custom LaTeX preamble
+$latex_preamble
 %%% User specified packages and stylesheets
 $stylesheet
 %%% Fallback definitions for Docutils-specific commands
@@ -52,6 +54,11 @@ requirements = r"""\usepackage{babel}
 \usepackage[latin1]{inputenc}
 \usepackage{ifthen}
 """,
+latex_preamble = r"""% PDF Standard Fonts
+\usepackage{mathptmx} % Times
+\usepackage[scaled=.90]{helvet}
+\usepackage{courier}
+""",
 stylesheet = '',
 fallbacks =  '',
 pdfsetup = r"""