manual/document.rst

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