faq/tex_latex.rst

   1 =============
   2 TeX and LaTeX
   3 =============
   4
   5 General aspects
   6 ===============
   7
   8 .. _what_is_tex:
   9
  10 What is TeX/LaTeX and why do I need it?
  11 ---------------------------------------
  12
  13 TeX is a high quality typesetting system developed by Donald E. Knuth which is
  14 available for a wide variety of operating systems. LaTeX is a macro package
  15 originally developed by Leslie Lamport which makes life with TeX easier, in
  16 particular for complex typesetting tasks. The current version of LaTeX is
  17 referred to as LaTeX2e and offers e.g. improved font selection as compared to
  18 the long outdated LaTeX 2.09 which should no longer be used.
  19
  20 All typesetting tasks in PyX are ultimately handed over to TeX (which is the
  21 default) or LaTeX, so that PyX cannot do without it. On the other hand, the
  22 capabilities of TeX and LaTeX can be used for complex tasks where both graphics
  23 and typesetting are needed.
  24
  25 .. _intro_tex_latex:
  26
  27 I don't know anything about TeX and LaTeX. Where can I read something about it?
  28 --------------------------------------------------------------------------------
  29
  30 Take a look at CTAN (cf. :ref:`ctan`) where in `CTAN:info
  31 <http://www.ctan.org/tex-archive/info/>`_ you may be able to find some useful
  32 information. There exists for example “A Gentle Introduction to TeX” by M. Doob
  33 (`CTAN:gentle/gentle.pdf <http://www.ctan.org/tex-archive/gentle/gentle.pdf>`_)
  34 and “The Not So Short Introduction to LaTeX2e”
  35 (`CTAN:info/lshort/english/lshort.pdf
  36 <http:www.ctan.org/tex-archive/info/lshort/english/lshort.pdf>`_) by T. Oetiker
  37 et al. The latter has been translated into a variety of languages among them
  38 korean (which you will not be able to read unless you have appropriate fonts
  39 installed) and mongolian.
  40
  41 Of course, it is likely that these documents will go way beyond what you will
  42 need for generating graphics with PyX so you don't have to read all of it
  43 (unless you want to use TeX or LaTeX for typesetting which can be highly
  44 recommended).
  45
  46 There exists also a number of FAQs on TeX at `CTAN:help <http://www.ctan.org/tex-archive/help>`_.
  47
  48 .. _ctan:
  49
  50 What is CTAN?
  51 -------------
  52
  53 CTAN is the *Comprehensive TeX Archive Network* where you will find almost
  54 everything related to TeX and friends. The main CTAN server is `www.ctan.org
  55 <http://www.ctan.org>`_ but there exists a large number of mirrors around the
  56 world. You can help to reduce the load on the main server by using
  57 `mirror.ctan.org <http://mirror.ctan.org>`_ which will redirect you to a mirror
  58 nearby. A list of known mirrors is available at
  59 `http://mirror.ctan.org/README.mirrors
  60 <http://mirror.ctan.org/README.mirrors>`_.
  61
  62 In this FAQ, ``CTAN:`` refers to the root of the CTAN tree, e.g.
  63 `http://www.ctan.org/tex-archive/ <http://www.ctan.org/tex-archive/>`_.  The
  64 links to CTAN in this document point to the main server but you might consider
  65 using a server closer to you in order to reduce traffic load.
  66
  67 Is there support for ConTeXt?
  68 -----------------------------
  69
  70 No, and as far as I know there no plans to provide it in the near future.
  71 Given the close ties between ConTeXt and MetaPost, ConTeXt users probably
  72 prefer to stick with the latter anyway.
  73
  74 TeX and LaTeX commands useful for PyX
  75 =====================================
  76
  77 How do I get a specific symbol with TeX or LaTeX?
  78 -------------------------------------------------
  79
  80 A list of mathematical symbols together with the appropriate command name can
  81 be found at `CTAN:info/symbols/math/symbols.pdf
  82 <http://www.ctan.org/tex-archive/info/symbols/math/symbols.pdf>`_. A
  83 comprehensive list containing almost 6000 symbols for use with LaTeX can be
  84 obtained from `CTAN:info/symbols/comprehensive/symbols-a4.pdf
  85 <http://www.ctan.org/tex-archive/info/symbols/comprehensive/symbols-a4.pdf>`_.
  86 In some cases it might be necessary to install fonts or packages available from
  87 CTAN (cf. :ref:`ctan`).
  88
  89 TeX and LaTeX errors
  90 ====================
  91
  92 .. _undefined_usepackage:
  93
  94 Undefined control sequence ``\usepackage``
  95 ------------------------------------------
  96
  97 The command ``\usepackage`` is specific to LaTeX. Since by default PyX
  98 uses TeX, you have to specify the correct mode::
  99
 100    text.set(mode="latex")
 101
 102 Undefined control sequence ``\frac``
 103
 104 The command ``\frac`` is only available in LaTeX. The equivalent to
 105 ``\frac{a}{b}`` in TeX is ``{a \over b}``.  As an alternative you may ask for
 106 the LaTeX mode as explained in :ref:`undefined_usepackage`.
 107
 108 Missing ``$`` inserted
 109 ----------------------
 110
 111 You have specified TeX- or LaTeX-code which is only valid in math mode.
 112 Typical examples are greek symbols, sub- and superscripts or fractions.
 113
 114 On the PyX level, you can specify math mode for the whole string by using
 115 ``text.mathmode`` as in ::
 116
 117    c.text(0, 0, r"{\alpha}", text.mathmode)
 118
 119 Keep also in mind that the standard Python interpretation of the backslash as
 120 introducing escape sequences needs to be prevented
 121 :ref:`raw_string`.
 122
 123 On the TeX/LaTeX level you should enclose the commands requiring math mode in
 124 ``$``'s. As an example, ``$\alpha_i^j$`` will produce a greek letter alpha with
 125 a subscript i and a superscript j.  The dollar sign thus allows you to specify
 126 math mode also for substrings. There exist other ways to specify math mode in
 127 TeX and LaTeX which are particularly useful for more complex typesetting tasks.
 128 To learn more about it, you should consult the documentation
 129 :ref:`intro_tex_latex`.
 130
 131 Why do environments like ``itemize`` or ``eqnarray`` seem not to work?
 132 ----------------------------------------------------------------------
 133
 134 An itemize environment might result in a LaTeX error complaining about a
 135 ``missing \item`` or an eqnarray might lead to a LaTeX message ``missing
 136 \endgroup inserted`` even though the syntax appears to be correct. The TeXnical
 137 reason is that in PyX text is typeset in left-right mode (LR mode) which does
 138 not allow linebreaks to occur. There are two ways out.
 139
 140 If the text material should go in a box of given width, a parbox can be used
 141 like in the following example::
 142
 143    text.set(mode="latex")
 144    c = canvas.canvas()
 145    w = 2
 146    c.text(0, 0, r"\begin{itemize}\item a\item b\end{itemize}", [text.parbox(w)])
 147
 148 Occasionally, one would like to have the box in which the text appears to be as
 149 small as possible. Then the ``fancybox`` package developed by Timothy Van Zandt
 150 is useful which provides several environments like ``Bitemize`` and
 151 ``Beqnarray`` which can be processed in LR mode. The relevant part of the code
 152 could look like::
 153
 154    text.set(mode="latex")
 155    text.preamble(r"\usepackage{fancybox}")
 156    c = canvas.canvas()
 157    c.text(0, 0, r"\begin{Bitemize}\item a\item b\end{Bitemize}")
 158
 159 Other environments provided by the ``fancybox`` package include ``Bcenter``,
 160 ``Bflushleft``, ``Bflushright``, ``Benumerate``, and ``Bdescription``. For more
 161 details, the documentation of the package should be consulted.
 162
 163 .. _fontshape_undefined:
 164
 165 Font shape ``OT1/xyz/m/n`` undefined
 166 ------------------------------------
 167
 168 You have asked to use font ``xyz`` which is not available. Make sure that you
 169 have this font available in Type1 format, i.e. there should be a file
 170 ``xyz.pfb`` somewhere. If your TeX system is TDS compliant (TDS=TeX directory
 171 structure, cf. `CTAN:tds/draft-standard/tds/tds.pdf
 172 <http://www.ctan.org/tex-archive/tds/draft-standard/tds/tds.pdf>`_) you should
 173 take a look at the subdirectories of ``$TEXMF/fonts/type1``.
 174
 175 File ``…`` is not available or not readable
 176 -------------------------------------------
 177
 178 Such an error message might already occur when running the example file
 179 ``hello.py`` included in the PyX distribution. Usually, the error occurs due to
 180 an overly restrictive umask setting applied when unpacking the ``tar.gz``
 181 sources. This may render the file mentioned in the error message unreadable
 182 because the python distutil installation package doesn't change the file
 183 permissions back to readable for everyone.
 184
 185 If the file exists, the problem can be solved by changing the permissions to
 186 allow read access.
 187
 188 No information for font ``cmr10`` found in font mapping file
 189 ------------------------------------------------------------
 190
 191 Such an error message can already be encountered by simply running the example
 192 file ``hello.py`` included in the PyX distribution. The likely reason is that
 193 the TeX system does not find the cmr fonts in Type1 format.  PyX depends on
 194 these fonts as it does not work with the traditional pk fonts which are stored
 195 as bitmaps.
 196
 197 Therefore, the first thing to make sure is that the cmr Type1 fonts are
 198 installed. In some TeX installations, the command ``kpsewhich cmr10.pfb`` will
 199 return the appropriate path if the cmr fonts exist in the binary Type1 format
 200 (extension ``pfb``) required by PyX. If the command does not work but the TeX
 201 system is TDS compliant (:ref:`fontshape_undefined`), a look should be taken at
 202 ``$TEXMF/fonts/type1/bluesky/cm`` where ``$TEXMF`` is the root of the ``texmf``
 203 tree.
 204
 205 If the Type1 fonts do not exist on the system, they may be obtained from the
 206 CTAN (cf. :ref:`ctan`) at `CTAN:fonts/cm/ps-type1/bluesky
 207 <http://www.ctan.org/tex-archive/fonts/cm/ps-type1/bluesky>`_). See the
 208 ``README`` for information about who produced these fonts and why they are
 209 freely available.
 210
 211 If the Type1 fonts exist, the next step is to take a look at ``psfonts.map``.
 212 There may be several files with this name on the system, so it is important to
 213 find out which one TeX is actually using.  ``kpsewhich psfonts.map`` might give
 214 this information.
 215
 216 The most likely problem is that this file does not contain a line telling TeX
 217 what to do if it encounters a request for font ``cmr10``, i.e. the following
 218 line may be missing ::
 219
 220    cmr10           CMR10           <cmr10.pfb
 221
 222 It is probable that the required lines (in practice, you do not just need
 223 ``cmr10``) are found in a file named ``psfonts.cmz`` which resides in
 224 ``$TEXMF/dvips/bluesky``.
 225
 226 One solution is to instruct PyX to read additional map files like
 227 ``psfonts.cmz`` or ``psfonts.amz``. This can be achieved by modifying the
 228 appropriate ``pyxrc`` file which is either the systemwide ``/etc/pyxrc`` or
 229 ``.pyxrc`` in the user's home directory. Here, the names of the map files to be
 230 read by PyX should be appended separated by whitespaces like in the following
 231 example::
 232
 233    [text]
 234    fontmaps = psfonts.map psfonts.cmz psfonts.amz
 235
 236 The same effect can be achieved by inserting the following line into the
 237 PyX code::
 238
 239    text.set(fontmaps="psfonts.map psfonts.cmz psfonts.amz")
 240
 241 Note that the default map (``psfonts.map``) has to be specified explicitly.
 242
 243 An alternative approach consists in modifying the TeX installation by inserting
 244 the contents of the desired map files like ``psfonts.cmz`` into
 245 ``psfonts.map``. Probably, ``psfonts.map`` recommends not to do this by hand.
 246 In this case the instructions given in the file should be followed.  Otherwise,
 247 ``psfonts.cmz`` should be copied into ``psfonts.map`` while keeping a backup of
 248 the old ``psfonts.map`` just in case. After these changes, PyX most likely will
 249 be happy. When inserting ``psfonts.cmz`` into ``psfonts.map`` it may be a good
 250 idea to include ``psfonts.amz`` as well. ``psfonts.amz`` contains information
 251 about some more fonts which might be needed at some point. Making these changes
 252 to ``psfonts.map`` will imply that the TeX system will use the cmr fonts in
 253 Type1 format instead of pk format which is actually not a bad thing, in
 254 particular if ``latex / dvips / ps2pdf`` is used to generate PDF output. With
 255 fonts in pk format this will look ugly and using Type1 fonts solves this
 256 problem as well. When ``pdflatex`` is used to create PDF files, Type1 fonts
 257 will be used anyway.
 258
 259 Fonts
 260 =====
 261
 262 I have Type1 fonts in ``pfa`` format. How do I obtain the corresponding ``pfb`` files needed by PyX?
 263 ----------------------------------------------------------------------------------------------------
 264
 265 .. todo:
 266
 267    still needs to be answered
 268
 269 .. _other_font:
 270
 271 I want to use a font other than computer modern roman
 272 -----------------------------------------------------
 273
 274 As long as you have a font in Type1 format available, this should be no
 275 problem (even though it may cost you some time to set up things properly).
 276
 277 In the simplest case, your LaTeX system contains everything needed.
 278 Including the following line into your code will probably work ::
 279
 280 text.set(mode="latex")
 281 text.preamble(r"\usepackage{mathptmx}")
 282
 283 and give you Times as roman font.
 284
 285 If you own one of the more common commercial fonts, take a look at `CTAN:fonts
 286 <http://www.ctan.org/tex-archive/fonts/>`_ and its subdirectories as well as at
 287 the web page `http://home.vr-web.de/was/fonts.html
 288 <http://home.vr-web.de/was/fonts.html>`_ of Walter Schmidt. It is not unlikely
 289 that somebody has already done most of the work for you and created the files
 290 needed for the font to work properly with LaTeX. But remember: we are talking
 291 about commercial fonts here, so do not expect to find the fonts themselves for
 292 free.
 293
 294 If none of these cases applies, you should spend some time reading manuals
 295 about font installation, e.g. `CTAN:macros/latex/doc/fntguide.pdf
 296 <http://www.ctan.org/tex-archive/macros/latex/doc/fntguide.pdf>`_ (of course, I
 297 do not expect font wizards to read the last few lines).
 298
 299 Can I use a TrueType font with PyX?
 300 -----------------------------------
 301
 302 Not directly as PyX only knows how to handle Type1 fonts (although it is
 303 possible to get LaTeX to work with TrueType fonts). However, you may use
 304 ``ttf2pt1`` (from `ttf2pt1.sourceforge.net <http://ttf2pt1.sourceforge.net>`_)
 305 to convert a TrueType font into a Type1 font which you then install in your TeX
 306 system (cf. :ref:`other_font`). You will loose hinting information in the
 307 conversion process but this should not really matter on output devices with not
 308 too low resolution.