sandbox/latex-variants/README.txt

   1 ..                            -*- rst-mode -*-
   2
   3 =====================
   4 Latex Writer Variants
   5 =====================
   6
   7 :Author: Günter Milde <milde@users.berlios.de>
   8 :Date: $Date$
   9
  10 This sandbox project is a place to try out and discuss
  11 `latex2e writer extensions`_ and `alternative latex writers`_
  12 for special needs.
  13
  14 .. contents::
  15
  16 ``latex2e`` writer extensions
  17 *****************************
  18
  19 .. Steps for uploading Changes:
  20
  21   * pepare patch to ../../docutils/docutils/writers/latex2e/__init__.py
  22
  23   * (add and) run functional and unit- tests::
  24
  25        ../../docutils/test/test_functional.py
  26        ../../docutils/test/test_writers/test_latex2e.py
  27
  28     or all at once::
  29
  30        cd ../../docutils/test/
  31        ./alltests.py
  32
  33     + if output changed: test-compile and approve new output in
  34       ../../docutils/test/functional/output/
  35
  36     More (informal) tests are in::
  37
  38       ../../docutils/test/functional/input/data/latex.txt
  39       ../grubert/test
  40       ~/Texte/Test/Docutils
  41
  42   * Documentation
  43
  44     * remove from TODO list in ../../docutils/docs/dev/todo.txt
  45       or the BUGS in ../../docutils/BUGS.txt
  46
  47     * describe new end-user features in ../../docutils/docs/user/latex.txt
  48     * describe new settings in ../../docutils/docs/user/config.txt
  49
  50     * add backwards-incompatible changes to ../../docutils/RELEASE-NOTES.txt
  51     * add summary of changes to ../../docutils/HISTORY.txt
  52     * describe change in ../../docutils/docs/user/docutils-05-compat.sty.txt
  53       (convert to style sheet and test with
  54       ../../docutils/docutils/writers/latex2e/05-compatibility-test.txt
  55
  56   * Commit and announce.
  57
  58 Questionnaire
  59 =============
  60
  61 #. Which `default font`_ do you prefer for the output?
  62
  63 #. Did you have problems with Find or Export of words with
  64    non-ASCII chars (e.g. Umlauts) in the PDF reader (Acrobat, xpdf, ...)
  65
  66    Which font encoding do you prefer for the output?
  67
  68 #. Does the latex2e writer need a `--stylesheet-path option`_?
  69
  70 #. Feature wishes or ideas of improvement for the `latex2e` writer.
  71
  72
  73 Users of ``rst2latex2.py`` are encouraged to respond by mail to the
  74 docutils-users list.
  75
  76 Proposed Changes
  77 ================
  78
  79 See also the notes in
  80 http://docutils.sourceforge.net/docs/user/latex.html#problems
  81 and the TODO list in
  82 http://docutils.sourceforge.net/docs/dev/todo.html#latex-writer
  83
  84
  85 Default font
  86 ------------
  87
  88 Which default font do you prefer for the output?
  89
  90 Answers:
  91   By default, PDFLaTeX uses embedded computer modern family, which look good
  92   on paper but poor on LCDs (even if outlined, due to suboptimal hinting),
  93   and result in large PDFs.  rst2pdf uses the "standard" PDF fonts by
  94   default (Times, Helvetica, Courier) which IMO look reasonable both on
  95   screen and on paper.  Because they aren't embedded, it also results in a
  96   smaller file size.
  97
  98 Using different fonts (e.g. standard postscript fonts) can be achieved
  99 easily by selecting a font package with the ``--stylesheet`` command line
 100 option or in a custom style-sheet.
 101
 102 Font embedding must be configured in the LaTeX installation.
 103
 104 Proposal
 105 ~~~~~~~~
 106
 107 Use one of the Postscript default fonts supported by standard LaTeX (pages
 108 10 and 11 of the `PSNFSS documentation`_)
 109
 110 Bookman
 111   | -2  very very wide
 112 Charter
 113   | +0  nonspectacular
 114   | -1  no "Base35" font
 115 New Century Schoolbook
 116   | -1  very wide
 117 Palatino
 118   | +1  recommended by font experts
 119   | +1  good LaTeX support including matching math fonts, small caps,
 120         old-style figures
 121   | -1  bad rendering in xpdf viewer (auto-hinting leads to different
 122         x-hight for different characters at some magnifications)
 123 Times
 124   | +1  'de facto standard'
 125   | -1  overused
 126   | -1  narrow (devised for multi-column layouts)
 127 Utopia
 128   | +1  recommended by font experts
 129   | -1  no `Base35` font, no required part of LaTeX any more.
 130
 131 Implement as default stylesheet option, so it can be easily overridden.
 132
 133    My vote is for Palatino.
 134    --Matthew Leingang
 135
 136
 137 --stylesheet-path option
 138 ------------------------
 139
 140 There are 2 use cases:
 141
 142 1. files in the TEXINPUTS path ("installed", site-wide style files (standard
 143    or local))
 144
 145    * specify only the filename
 146    * include literally
 147
 148 2. files outside the TEXINPUTS path (not installed, local style files)
 149
 150    * a relative path should be rewritten if the output document is in a
 151      different dir than the pwd
 152
 153 Currently, 1) is done with --stylesheet and 2) with --stylesheet-path.
 154
 155 But:
 156
 157 -1 having both ``--stylesheet`` and ``stylesheet-path`` makes things
 158    complicated:
 159
 160   Explaining the two options and their interaction to the user is
 161   not straightforward.
 162
 163   This holds even more if you take into account the third related
 164   option, ``--embed-stylesheet``.
 165
 166 -1  it is impossible to have some paths rewritten and some not, as in e.g. ::
 167
 168       --stylesheet=mathpazo -stylesheet-path=mystyle.tex
 169
 170     "mystyle.tex" would overwrite "mathpazo".
 171
 172 Proposal
 173 ~~~~~~~~
 174
 175 Instead of two options, do "the right thing" based on simple rules, e.g:
 176
 177 a) Use the "package" vs. "custom style sheet" distinction:
 178
 179    Rewrite, if there is an filename extension and it is not ``.sty`` ::
 180
 181      --stylesheet='mathpazo,mystyle.tex'
 182
 183    will use 'mathpazo' verbatim and rewrite 'mystyle.tex'.
 184
 185    -1  will not work for latex packages in the pwd or outside the TEXINPUTS
 186        path.
 187
 188 b) rewrite paths that have a directory part::
 189
 190      --stylesheet='mathpazo,./mystyle.sty'
 191
 192    will use 'mathpazo' verbatim and rewrite './mystyle.sty'.
 193
 194    +1  explicite and flexible
 195
 196    +1  the common case (files in the TEXINPUTS path) is the most simple
 197
 198    -1  need to document/learn special syntax
 199
 200 c) rewrite path if this prevents errors:
 201
 202    * Check for a given file (or relative path) relative to pwd and output dir.
 203    * If it is available relative to pwd but not relative to the output dir,
 204      rewrite the path.
 205
 206    +1  no need to explain any additional syntax
 207
 208    +1  does "the right thing" in most usual cases
 209
 210    -1  hidden automatism might lead to problems in corner cases
 211
 212    -1  mechanism depends on the availability of files at the time of the run,
 213        which is harder to explain and less predictable than b)
 214
 215 .. Use case:
 216
 217   A project with rst documents sorted into a hierarchy of sub-directories
 218   and a common style file in the base dir or a sub dir::
 219
 220    .
 221    |_ base.txt
 222    |_ mystyle.sty
 223    |_ docutils.conf
 224    |_ A/
 225    |  |_ a.txt
 226    |  | ...
 227    |_ B/
 228       |_ b.txt
 229
 230
 231   With the line ::
 232
 233    stylesheet-path: mystyle.sty
 234
 235   in docutils.conf, all documents will get a valid link to the style file,
 236   if the conversion is started from the base dir.
 237
 238
 239 Require only standard packages
 240 ------------------------------
 241
 242 Provide fallback solutions for the use of "exotic" packages in case they do
 243 not exist on the target system.
 244
 245 .. \@ifpackageloaded{} \IfPackageExists{}
 246
 247
 248
 249 Bibliography directive
 250 ----------------------
 251
 252 Alan suggested a bibliography directive so that BibTex references are not
 253 automatically placed at the end (and bibtex for html via ... can be supported)
 254
 255 This would imply supression of the "Bibliography" or "References" header
 256 added by LaTeX which is possible with:
 257
 258   From: Martin Scharrer <martin@scharrer-online.de>
 259   Subject: Re: Literaturverzeichnis ?berschrift entfernen
 260   Date: Sun, 22 Mar 2009 06:30:33 -0700 (PDT)
 261
 262   On Mar 21, 11:10?pm, Elfish26111...@gmail.com wrote:
 263   > Hallo,
 264   >
 265   > ich benutze Bibtex und w?rde gerne die komplette ?berschrift, also
 266   > auch die daf?r reservierte Box entfernen.
 267   > Hat jemand eine Idee wie ich das machen kann?
 268   >
 269   > \renewcommand{\bibname}{}
 270   >
 271   > habe ich bereits versucht. Aber wie gesagt den reservierten Platz in
 272   > der Überschrift behält er immernoch.
 273
 274   Die Ueberschrift ist denk ich mal ein '\chapter*{\bibname}' was du
 275   dann zu einem '\chapter*{}' machst.
 276   Die Loesung ist einfach das \chapter macro umzudefinieren:
 277
 278   \begingroup
 279   \renewcommand{\chapter}[2]{}
 280   % Literaturverzeichnis einbinden: ueber BibTeX oder manuell ...
 281   \endgroup
 282
 283   Wobei der '*' hier einfach als ein zusaetzliches Argument genommen
 284   wird.
 285   Dann braucht \bibname gar nicht mehr geaendert werden.
 286
 287   Gruesse,
 288   Martin
 289
 290
 291
 292 Implemented Changes
 293 ===================
 294
 295 Changes to the latex2e writer in the SVN version since docutils version 0.5
 296 are documented in the compatibility style sheet latex2e-compat_.
 297
 298 Also see the `Docutils Release Notes`_, the `Docutils History`_.
 299
 300
 301 Alternative latex writers
 302 *************************
 303
 304 Browse the `SVN repository at berlios.de`__
 305
 306 __ http://svn.berlios.de/viewvc/docutils/trunk/sandbox/latex-variants/
 307
 308 * The `docs` dir contains generic documentation and discussion.
 309
 310   Writer specific documentation is placed in the respective "literate"
 311   source.
 312
 313 other latex writers
 314 ===================
 315
 316 Currently none.
 317
 318 Tests
 319 *****
 320
 321 Test documents and unit tests highlighting problems with the LaTeX
 322 export and testing alternatives.
 323
 324
 325 See `<tests>`_
 326
 327 Related sandbox projects
 328 ************************
 329
 330 * `<../dkuhlman/Docs>`__,
 331 * `<../docpy-writer>`__,
 332 * `<../jensj/latex_math>`__,
 333 * `<../latex_directive>`__, and
 334 * `<../verse-writer>`__.
 335
 336 .. References
 337    ==========
 338
 339 .. _latex.html: ../../docutils/docs/user/latex.html
 340 .. _latex2e-compat:
 341    ../../docutils/docs/user/docutils-05-compat.sty.html
 342
 343 .. _font encoding: ../../docutils/docs/user/latex.html#
 344
 345
 346 .. _PSNFSS documentation:
 347    http://dante.ctan.org/CTAN/macros/latex/required/psnfss/psnfss2e.pdf
 348 .. _Docutils Release Notes:
 349    http://docutils.sourceforge.net/RELEASE-NOTES.html
 350 .. _Docutils History:
 351    http://docutils.sourceforge.net/HISTORY.html