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. In any case, the bounding
  30    box is enlarged on all sides by *bboxenlarge*. Alternatively, you may specify
  31    the *bbox* manually.
  32
  33 Class :class:`document`
  34 -----------------------
  35
  36
  37 .. class:: document(pages=[])
  38
  39    Construct a :class:`document` consisting of a given list of *pages*.
  40
  41 A :class:`document` can be written to a file using one of the following methods:
  42
  43
  44 .. method:: document.writeEPSfile(file, title=None, strip_fonts=True, text_as_path=False, mesh_as_bitmap=False, mesh_as_bitmap_resolution=300)
  45
  46    Write a single page :class:`document` to an EPS file or to stdout if *file* is
  47    set to *-*. *title* is used as the document title, *strip_fonts* enabled
  48    font stripping (removal of unused glyphs), *text_as_path* converts all text
  49    to paths instead of using fonts in the output, *mesh_as_bitmap* converts
  50    meshs (like 3d surface plots) to bitmaps (to reduce complexity in the
  51    output) and *mesh_as_bitmap_resolution* is the resolution of this conversion
  52    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 or to to stdout if *file* is set to
  58    *-*. *writebbox* add the page bounding boxes to the output. All other
  59    parameters are identical to the :meth:`writeEPSfile` 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 or to stdout if *file* is set to *-*.
  65    *author*, *subject*, and *keywords* are used for the document author,
  66    subject, and keyword information, respectively. *fullscreen* enabled
  67    fullscreen mode when the document is opened, *writebbox* enables writing of
  68    the crop box to each page, *compress* enables output stream compression and
  69    *compresslevel* sets the compress level to be used (from 1 to 9). All other
  70    parameters are identical to the :meth:`writeEPSfile`.
  71
  72
  73 .. method:: document.writeSVGfile(file, text_as_path=True, mesh_as_bitmap_resolution=300)
  74
  75    Write :class:`document` to a SVG file or to stdout if *file* is set to *-*.
  76    The *text_as_path* and *mesh_as_bitmap_resolution* have the same meaning as
  77    in :meth:`writeEPSfile`. However, not the different default for
  78    *text_as_path* due to the missing SVG font support by current browsers.
  79    In addition, there is no *mesh_as_bitmap* flag, as meshs are always stored
  80    using bitmaps in SVG.
  81
  82
  83 .. method:: document.writetofile(filename, *args, **kwargs)
  84
  85    Determine the file type (EPS, PS, PDF, or SVG) from the file extension of *filename*
  86    and call the corresponding write method with the given arguments *arg* and
  87    *kwargs*.
  88
  89
  90 Class :class:`paperformat`
  91 --------------------------
  92
  93
  94 .. class:: paperformat(width, height, name=None)
  95
  96    Define a :class:`paperformat` with the given *width* and *height* and the
  97    optional *name*.
  98
  99 Predefined paperformats are listed in the following table
 100
 101 +--------------------------------------+--------+----------+---------+
 102 | instance                             | name   | width    | height  |
 103 +======================================+========+==========+=========+
 104 | :const:`document.paperformat.A0`     | A0     | 840 mm   | 1188 mm |
 105 +--------------------------------------+--------+----------+---------+
 106 | :const:`document.paperformat.A0b`    |        | 910 mm   | 1370 mm |
 107 +--------------------------------------+--------+----------+---------+
 108 | :const:`document.paperformat.A1`     | A1     | 594 mm   | 840 mm  |
 109 +--------------------------------------+--------+----------+---------+
 110 | :const:`document.paperformat.A2`     | A2     | 420 mm   | 594 mm  |
 111 +--------------------------------------+--------+----------+---------+
 112 | :const:`document.paperformat.A3`     | A3     | 297 mm   | 420 mm  |
 113 +--------------------------------------+--------+----------+---------+
 114 | :const:`document.paperformat.A4`     | A4     | 210 mm   | 297 mm  |
 115 +--------------------------------------+--------+----------+---------+
 116 | :const:`document.paperformat.A5`     | A5     | 148.5 mm | 210 mm  |
 117 +--------------------------------------+--------+----------+---------+
 118 | :const:`document.paperformat.Letter` | Letter | 8.5 inch | 11 inch |
 119 +--------------------------------------+--------+----------+---------+
 120 | :const:`document.paperformat.Legal`  | Legal  | 8.5 inch | 14 inch |
 121 +--------------------------------------+--------+----------+---------+
 122