Merge pull request #14 from gertingold/unicode

unicode section of faq reworked

faq/tex_latex.rst

@@ -7,8 +7,8 @@ General aspects
 
 .. _what_is_tex:
 
-What is TeX/LaTeX and why do I need it?
----------------------------------------
+What is TeX/LaTeX?
+------------------
 
 TeX is a high quality typesetting system developed by Donald E. Knuth which is
 available for a wide variety of operating systems. LaTeX is a macro package
@@ -17,10 +17,15 @@ particular for complex typesetting tasks. The current version of LaTeX is
 referred to as LaTeX2e and offers e.g. improved font selection as compared to
 the long outdated LaTeX 2.09 which should no longer be used. 
 
-All typesetting tasks in PyX are ultimately handed over to TeX (which is the
-default) or LaTeX, so that PyX cannot do without it. On the other hand, the
-capabilities of TeX and LaTeX can be used for complex tasks where both graphics
-and typesetting are needed.
+Do I need to use TeX/LaTeX?
+---------------------------
+
+Traditionally, typesetting in PyX is done with TeX or LaTeX. With PyX 0.15, the
+Unicode engine was introduced. This engine can be useful if one does not need
+the elaborate typesetting capabilities of TeX and LaTeX and wants to avoid
+installing the corresponding packages.  A TeX installation may nevertheless be
+useful if one wants to make use of fonts distributed with it. For further
+information see :ref:`text_without_tex`.
 
 .. _intro_tex_latex:
 

faq/unicode_text.rst

@@ -1,3 +1,5 @@
+.. _text_without_tex:
+
 =======================
 Text output without TeX
 =======================
@@ -11,60 +13,80 @@ General aspects
 How can I typeset text in PyX without TeX?
 ------------------------------------------
 
-Originally, TeX (or variants thereof, like LaTeX) were the only way to typeset
-text in PyX. However, as PyX does all the post-typesetting itself based on the
-dvi output of TeX, it has all the font infrastructure in place. Starting with
-PyX 0.15, this functionality is made available for direct use.
-
-The UnicodeEngine allows to typeset text on a canvas ``c`` using the font
-directly::
-
-    engine = text.UnicodeEngine()
-    c.insert(engine.text(0, 0, "Hello, world!"))
-
-The font name and size are parameters to the ``UnicodeEngine`` constructor::
-
-    engine = text.UnicodeEngine(fontname='cmss10', size=20)
-
-A text engine can be made the default typesetting engine by::
+Starting with PyX 0.15, an additional typesetting engine besides the TeX and
+LaTeX engine is available: the Unicode engine. It can be made the default
+typesetting engine by::
 
     text.set(text.UnicodeEngine)
 
-Parameters to the engine are provided as additional parameters to the ``set``
-command::
+The font and its size can be specified through additional parameters like in
+this example::
 
     text.set(text.UnicodeEngine, fontname='cmss10', size=20)
 
 
 .. _font_configuration_for_the_unicode_engine:
 
-But I still need a TeX installation?
-------------------------------------
+Do I still need a TeX installation?
+-----------------------------------
+
+Not necessarily. However, PyX needs to have access to the Type1 fonts it is
+supposed to use in the typesetting. Specifically, it needs the corresponding
+``pfb`` and ``afm`` files. There are different ways to provide them.
+
+The first possibility is indeed a TeX installation. This approach makes
+particularly sense if the fonts to be used are made available by a TeX
+distribution. For example, the Computer Modern fonts used by PyX as default
+fonts are provided by all TeX installations.
 
-In fact, the answer of the previous question will not function out of the box
-if you do not have a TeX installation in place. The reason is, that PyX still
-requires and uses the Computer Modern fonts provided by the TeX installation.
-In fact, PyX uses Type1 fonts, and needs the pfb and afm files of the font. You
-can do so by placing the two files of the Type1 font in the current directory.
-However, fonts can also be loaded from somewhere else in the file system.
+If, on the other hand, a font is to be used for which no TeX support is readily
+available, its ``pfb`` and ``afm`` files can be put in the directory where
+the Python script is placed. The font will then be found by PyX if the parameter
+``fontname`` corresponds to the basename of the ``pfb`` and ``afm`` files.
 
-Suppose you want to use the standard TeX fonts, you can get them in Type1
-format at `https://www.ams.org/publications/authors/tex/amsfonts <https://www.ams.org/publications/authors/tex/amsfonts>`_.
+The latter approach is not optimal if the font is used in different PyX scripts
+scattered over several directories or if a larger number of fonts is needed.
+Then it is better to store the Type1 font files in a central place and to tell
+PyX about the files as explained in the following example.
+
+Suppose the standard TeX fonts should be used without a TeX installation. The
+fonts can be obtained in Type1 format from
+`https://www.ams.org/publications/authors/tex/amsfonts <https://www.ams.org/publications/authors/tex/amsfonts>`_.
 Extract the zip file somewhere on your file system and generate an index file
-(ls-R) in the directory you just created by extracting the zip file by
-``ls -R > ls-R``. Finally create a ``.pyxrc`` file in your home directory. with the
+(ls-R) by running ``ls -R > ls-R`` in the directory to which the fonts were
+extracted. Finally create a ``.pyxrc`` file in your home directory with the
 following content::
 
     [filelocator]
     methods = local internal ls-R
-    ls-R = /<the full path of the diretory you extracted the amsfonts zip file>/ls-R
+    ls-R = /<the full path of the directory you extracted the amsfonts zip file>/ls-R
 
-You can skip the generation of the index file, and use the ``recursivedir``
+The generation of the index file can be skipped by using the ``recursivedir``
 locator instead::
 
     [filelocator]
     methods = local internal recursivedir
-    recursivedir = /<the full path of the diretory you extracted the amsfonts zip file>
+    recursivedir = /<the full path of the directory you extracted the amsfonts zip file>
 
-However, using an index file is faster, as PyX does not need to crawl the
+However, the use of an index file increases performance, as PyX does not need to crawl the
 directory structure to locate the actual files.
+
+
+.. _tex_and_unicode:
+
+Is it possible to use the Unicode engine in addition to the TeX engine?
+-----------------------------------------------------------------------
+
+Yes, it is possible to use different typesetting engines in the same script.
+The following example uses the Unicode engine and the TeX engine to typeset
+text on a canvas ``c``::
+
+    unicode_engine = text.UnicodeEngine()
+    c.insert(unicode_engine.text(0, 0, "Hello, world!"))
+    tex_engine = text.TexEngine()
+    c.insert(tex_engine.text(0, 1, "Hello, world!"))
+
+If needed, the font name and size can be passed as parameters to the
+``UnicodeEngine`` constructor::
+
+    engine = text.UnicodeEngine(fontname='cmss10', size=20)