manual/document.rst

   1
   2 .. module:: document
   3
   4 ======================
   5 Module :mod:`document`
   6 ======================
   7
   8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
   9
  10 The document module contains two classes: :class:`document` and :class:`page`. A
  11 :class:`document` consists of one or several :class:`page`\ s.
  12
  13
  14 Class :class:`page`
  15 -------------------
  16
  17 A :class:`page` is a thin wrapper around a :class:`canvas`, which defines some
  18 additional properties of the page.
  19
  20
  21 .. class:: page(canvas, pagename=None, paperformat=None, rotated=0, centered=1, fittosize=0, margin=1 * unit.t_cm, bboxenlarge=1 * unit.t_pt, bbox=None)
  22
  23    Construct a new :class:`page` from the given :class:`canvas` instance. A string
  24    *pagename* and the *paperformat* can be defined. See below, for a list of known
  25    paper formats. If *rotated* is set, the output is rotated by 90 degrees on the
  26    page. If *centered* is set, the output is centered on the given paperformat. If
  27    *fittosize* is set, the output is scaled to fill the full page except for a
  28    given *margin*.  Normally, the bounding box of the canvas is calculated
  29    automatically from the bounding box of its elements.  Alternatively, you may
  30    specify the *bbox* manually. In any case, the bounding box is enlarged on all
  31    sides by *bboxenlarge*.
  32
  33
  34 Class :class:`document`
  35 -----------------------
  36
  37
  38 .. class:: document(pages=[])
  39
  40    Construct a :class:`document` consisting of a given list of *pages*.
  41
  42 A :class:`document` can be written to a file using one of the following methods:
  43
  44
  45 .. method:: document.writeEPSfile(file, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300)
  46
  47    Write a single page :class:`document` to an EPS file or to stdout if *file* is
  48    set to *-*. *title* is used as the document title, *strip_fonts* enabled
  49    font stripping (removal of unused glyphs), *text_as_path* converts all text
  50    to paths instead of using fonts in the output, *mesh_as_bitmap* converts
  51    meshs (like 3d surface plots) to bitmaps (to reduce complexity in the
  52    output) and *mesh_as_bitmap_resolution* is the resolution of this conversion
  53    in dots per inch.
  54
  55
  56 .. method:: document.writePSfile(file, writebbox=False, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300)
  57
  58    Write :class:`document` to a PS file or to to stdout if *file* is set to
  59    *-*. *writebbox* add the page bounding boxes to the output. All other
  60    parameters are identical to the :meth:`writeEPSfile` method.
  61
  62
  63 .. method:: document.writePDFfile(file, title=None, author=None, subject=None, keywords=None, fullscreen=False, writebbox=False, compress=True, compresslevel=6, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300)
  64
  65    Write :class:`document` to a PDF file or to stdout if *file* is set to *-*.
  66    *author*, *subject*, and *keywords* are used for the document author,
  67    subject, and keyword information, respectively. *fullscreen* enabled
  68    fullscreen mode when the document is opened, *writebbox* enables writing of
  69    the crop box to each page, *compress* enables output stream compression and
  70    *compresslevel* sets the compress level to be used (from 1 to 9). All other
  71    parameters are identical to the :meth:`writeEPSfile`.
  72
  73
  74 .. method:: document.writeSVGfile(file, text_as_path=True, mesh_as_bitmap_resolution=300)
  75
  76    Write :class:`document` to a SVG file or to stdout if *file* is set to *-*.
  77    The *text_as_path* and *mesh_as_bitmap_resolution* have the same meaning as
  78    in :meth:`writeEPSfile`. However, not the different default for
  79    *text_as_path* due to the missing SVG font support by current browsers.
  80    In addition, there is no *mesh_as_bitmap* flag, as meshs are always stored
  81    using bitmaps in SVG.
  82
  83
  84 .. method:: document.writetofile(filename, *args, **kwargs)
  85
  86    Determine the file type (EPS, PS, PDF, or SVG) from the file extension of *filename*
  87    and call the corresponding write method with the given arguments *arg* and
  88    *kwargs*.
  89
  90
  91 Class :class:`paperformat`
  92 --------------------------
  93
  94
  95 .. class:: paperformat(width, height, name=None)
  96
  97    Define a :class:`paperformat` with the given *width* and *height* and the
  98    optional *name*.
  99
 100 Predefined paperformats are listed in the following table
 101
 102 +--------------------------------------+--------+----------+---------+
 103 | instance                             | name   | width    | height  |
 104 +======================================+========+==========+=========+
 105 | :const:`document.paperformat.A0`     | A0     | 840 mm   | 1188 mm |
 106 +--------------------------------------+--------+----------+---------+
 107 | :const:`document.paperformat.A0b`    |        | 910 mm   | 1370 mm |
 108 +--------------------------------------+--------+----------+---------+
 109 | :const:`document.paperformat.A1`     | A1     | 594 mm   | 840 mm  |
 110 +--------------------------------------+--------+----------+---------+
 111 | :const:`document.paperformat.A2`     | A2     | 420 mm   | 594 mm  |
 112 +--------------------------------------+--------+----------+---------+
 113 | :const:`document.paperformat.A3`     | A3     | 297 mm   | 420 mm  |
 114 +--------------------------------------+--------+----------+---------+
 115 | :const:`document.paperformat.A4`     | A4     | 210 mm   | 297 mm  |
 116 +--------------------------------------+--------+----------+---------+
 117 | :const:`document.paperformat.A5`     | A5     | 148.5 mm | 210 mm  |
 118 +--------------------------------------+--------+----------+---------+
 119 | :const:`document.paperformat.Letter` | Letter | 8.5 inch | 11 inch |
 120 +--------------------------------------+--------+----------+---------+
 121 | :const:`document.paperformat.Legal`  | Legal  | 8.5 inch | 14 inch |
 122 +--------------------------------------+--------+----------+---------+
 123