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     if output changed: test-compile and approve new output in
  29       ../../docutils/test/functional/output/
  30
  31     More (informal) tests are in::
  32
  33       tests/
  34       ../../docutils/test/functional/input/data/latex.txt
  35       ../grubert/test
  36
  37
  38   * Documentation
  39
  40     * remove from TODO list in ../../docutils/docs/dev/todo.txt
  41       or the BUGS in ../../docutils/BUGS.txt
  42
  43     * describe new end-user features in ../../docutils/docs/user/latex.txt
  44     * describe new settings in ../../docutils/docs/user/config.txt
  45
  46     * add backwards-incompatible changes to ../../docutils/RELEASE-NOTES.txt
  47     * add summary of changes to ../../docutils/HISTORY.txt
  48
  49   * Commit and announce.
  50
  51
  52 Proposed Changes
  53 ================
  54
  55 See also the notes in
  56 http://docutils.sourceforge.net/docs/user/latex.html#problems
  57 and the TODO list in
  58 http://docutils.sourceforge.net/docs/dev/todo.html#latex-writer
  59
  60
  61 --stylesheet-path option
  62 ------------------------
  63
  64 There are 2 use cases:
  65
  66 1. files in the TEXINPUTS path ("installed", site-wide style files (standard
  67    or local))
  68
  69    * specify only the filename
  70    * include literally
  71
  72 2. files outside the TEXINPUTS path (not installed, local style files)
  73
  74    * a relative path should be rewritten if the output document is in a
  75      different dir than the pwd
  76
  77 Currently, 1) is done with --stylesheet and 2) with --stylesheet-path.
  78
  79 But:
  80
  81 -1 having both ``--stylesheet`` and ``stylesheet-path`` makes things
  82    complicated:
  83
  84   Explaining the two options and their interaction to the user is
  85   not straightforward.
  86
  87   This holds even more if you take into account the third related
  88   option, ``--embed-stylesheet``.
  89
  90 -1  it is impossible to have some paths rewritten and some not, as in e.g. ::
  91
  92       --stylesheet=mathpazo -stylesheet-path=mystyle.tex
  93
  94     "mystyle.tex" would overwrite "mathpazo".
  95
  96 Proposal
  97 ~~~~~~~~
  98
  99 Instead of two options, do "the right thing" based on simple rules, e.g:
 100
 101 a) Use the "package" vs. "custom style sheet" distinction:
 102
 103    Rewrite, if there is an filename extension and it is not ``.sty`` ::
 104
 105      --stylesheet='mathpazo,mystyle.tex'
 106
 107    will use 'mathpazo' verbatim and rewrite 'mystyle.tex'.
 108
 109    -1  will not work for latex packages in the pwd or outside the TEXINPUTS
 110        path.
 111
 112 b) rewrite paths that have a directory part::
 113
 114      --stylesheet='mathpazo,./mystyle.sty'
 115
 116    will use 'mathpazo' verbatim and rewrite './mystyle.sty'.
 117
 118    +1  explicite and flexible
 119
 120    +1  the common case (files in the TEXINPUTS path) is the most simple
 121
 122    -1  need to document/learn special syntax
 123
 124 c) rewrite path if this prevents errors:
 125
 126    * Check for a given file (or relative path) relative to pwd and output dir.
 127    * If it is available relative to pwd but not relative to the output dir,
 128      rewrite the path.
 129
 130    +1  no need to explain any additional syntax
 131
 132    +1  does "the right thing" in most usual cases
 133
 134    -1  hidden automatism might lead to problems in corner cases
 135
 136    -1  mechanism depends on the availability of files at the time of the run,
 137        which is harder to explain and less predictable than b)
 138
 139 .. Use case:
 140
 141   A project with rst documents sorted into a hierarchy of sub-directories
 142   and a common style file in the base dir or a sub dir::
 143
 144    .
 145    |_ base.txt
 146    |_ mystyle.sty
 147    |_ docutils.conf
 148    |_ A/
 149    |  |_ a.txt
 150    |  | ...
 151    |_ B/
 152       |_ b.txt
 153
 154
 155   With the line ::
 156
 157    stylesheet-path: mystyle.sty
 158
 159   in docutils.conf, all documents will get a valid link to the style file,
 160   if the conversion is started from the base dir.
 161
 162
 163 Require only standard packages
 164 ------------------------------
 165
 166 Provide fallback solutions for the use of "exotic" packages in case they do
 167 not exist on the target system.
 168
 169 .. \@ifpackageloaded{} \IfPackageExists{}
 170
 171
 172
 173 Bibliography directive
 174 ----------------------
 175
 176 Alan suggested a bibliography directive so that BibTex references are not
 177 automatically placed at the end (and bibtex for HTML via ... can be supported)
 178
 179 This would imply supression of the "Bibliography" or "References" header
 180 added by LaTeX which is possible with:
 181
 182   From: Martin Scharrer <martin@scharrer-online.de>
 183   Subject: Re: Literaturverzeichnis ?berschrift entfernen
 184   Date: Sun, 22 Mar 2009 06:30:33 -0700 (PDT)
 185
 186   On Mar 21, 11:10?pm, Elfish26111...@gmail.com wrote:
 187   > Hallo,
 188   >
 189   > ich benutze Bibtex und w?rde gerne die komplette ?berschrift, also
 190   > auch die daf?r reservierte Box entfernen.
 191   > Hat jemand eine Idee wie ich das machen kann?
 192   >
 193   > \renewcommand{\bibname}{}
 194   >
 195   > habe ich bereits versucht. Aber wie gesagt den reservierten Platz in
 196   > der Überschrift behält er immernoch.
 197
 198   Die Ueberschrift ist denk ich mal ein '\chapter*{\bibname}' was du
 199   dann zu einem '\chapter*{}' machst.
 200   Die Loesung ist einfach das \chapter macro umzudefinieren:
 201
 202   \begingroup
 203   \renewcommand{\chapter}[2]{}
 204   % Literaturverzeichnis einbinden: ueber BibTeX oder manuell ...
 205   \endgroup
 206
 207   Wobei der '*' hier einfach als ein zusaetzliches Argument genommen
 208   wird.
 209   Dann braucht \bibname gar nicht mehr geaendert werden.
 210
 211   Gruesse,
 212   Martin
 213
 214
 215 Tests
 216 *****
 217
 218 Test documents and unit tests highlighting problems with the LaTeX
 219 export and testing alternatives.
 220
 221
 222 See `<tests>`_
 223
 224 Related sandbox projects
 225 ************************
 226
 227 * `<../dkuhlman/Docs>`__,
 228 * `<../docpy-writer>`__,
 229 * `<../jensj/latex_math>`__,
 230 * `<../latex_directive>`__, and
 231 * `<../verse-writer>`__.
 232
 233 .. References
 234    ==========
 235
 236 .. _latex.html: ../../docutils/docs/user/latex.html
 237 .. _latex2e-compat:
 238    ../../docutils/docs/user/docutils-05-compat.sty.html
 239
 240 .. _font encoding: ../../docutils/docs/user/latex.html#
 241
 242
 243 .. _PSNFSS documentation:
 244    http://dante.ctan.org/CTAN/macros/latex/required/psnfss/psnfss2e.pdf
 245 .. _Docutils Release Notes:
 246    http://docutils.sourceforge.net/RELEASE-NOTES.html
 247 .. _Docutils History:
 248    http://docutils.sourceforge.net/HISTORY.html