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. *title* is used as the
  48    document title, *strip_fonts* enabled font stripping (removal of unused glyphs),
  49    *text_as_path* converts all text to paths instead of using fonts in the output,
  50    *mesh_as_bitmap* converts meshs (like 3d surface plots) to bitmaps (to reduce
  51    complexity in the output) and *mesh_as_bitmap_resolution* is the resolution of
  52    this conversion in dots per inch.
  53
  54
  55 .. method:: document.writePSfile(file, writebbox=False, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300)
  56
  57    Write :class:`document` to a PS file. *writebbox* add the page bounding boxes to
  58    the output. All other parameters are identical to the :meth:`writeEPSfile`
  59    method.
  60
  61
  62 .. 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)
  63
  64    Write :class:`document` to a PDF file. *author*, *subject*, and *keywords* are
  65    used for the document author, subject, and keyword information, respectively.
  66    *fullscreen* enabled fullscreen mode when the document is opened, *writebbox*
  67    enables writing of the crop box to each page, *compress* enables output stream
  68    compression and *compresslevel* sets the compress level to be used (from 1 to
  69    9). All other parameters are identical to the :meth:`writeEPSfile`.
  70
  71
  72 .. method:: document.writetofile(filename, *args, **kwargs)
  73
  74    Determine the file type (EPS, PS, or PDF) from the file extension of *filename*
  75    and call the corresponding write method with the given arguments *arg* and
  76    *kwargs*.
  77
  78
  79 Class :class:`paperformat`
  80 --------------------------
  81
  82
  83 .. class:: paperformat(width, height, name=None)
  84
  85    Define a :class:`paperformat` with the given *width* and *height* and the
  86    optional *name*.
  87
  88 Predefined paperformats are listed in the following table
  89
  90 +--------------------------------------+--------+----------+---------+
  91 | instance                             | name   | width    | height  |
  92 +======================================+========+==========+=========+
  93 | :const:`document.paperformat.A0`     | A0     | 840 mm   | 1188 mm |
  94 +--------------------------------------+--------+----------+---------+
  95 | :const:`document.paperformat.A0b`    |        | 910 mm   | 1370 mm |
  96 +--------------------------------------+--------+----------+---------+
  97 | :const:`document.paperformat.A1`     | A1     | 594 mm   | 840 mm  |
  98 +--------------------------------------+--------+----------+---------+
  99 | :const:`document.paperformat.A2`     | A2     | 420 mm   | 594 mm  |
 100 +--------------------------------------+--------+----------+---------+
 101 | :const:`document.paperformat.A3`     | A3     | 297 mm   | 420 mm  |
 102 +--------------------------------------+--------+----------+---------+
 103 | :const:`document.paperformat.A4`     | A4     | 210 mm   | 297 mm  |
 104 +--------------------------------------+--------+----------+---------+
 105 | :const:`document.paperformat.A5`     | A5     | 148.5 mm | 210 mm  |
 106 +--------------------------------------+--------+----------+---------+
 107 | :const:`document.paperformat.Letter` | Letter | 8.5 inch | 11 inch |
 108 +--------------------------------------+--------+----------+---------+
 109 | :const:`document.paperformat.Legal`  | Legal  | 8.5 inch | 14 inch |
 110 +--------------------------------------+--------+----------+---------+
 111