README.txt
author robin <robin@reportlab.com>
Tue, 07 Mar 2017 10:00:34 +0000
changeset 4330 617ffa6bbdc8
parent 4318 40df5b03ecad
child 4516 99e01611df97
permissions -rw-r--r--
changes for release 3.4.0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4171
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     1
=====================================
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     2
README
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     3
=====================================
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     4
4330
617ffa6bbdc8 changes for release 3.4.0
robin <robin@reportlab.com>
parents: 4318
diff changeset
     5
(C) Copyright ReportLab Europe Ltd. 2000-2017.
4171
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     6
See ``LICENSE.txt`` for license details.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     7
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     8
This is the ReportLab PDF Toolkit. It allows rapid creation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
     9
of rich PDF documents, and also creation of charts in a variety
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    10
of bitmap and vector formats.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    11
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    12
This library is also the foundation for our commercial product
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    13
Report Markup Language (RML), available in the ReportLab PLUS
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    14
package. RML offers many more features, a template-based style
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    15
of document development familiar to all web developers, and
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    16
higher development productivity.  Please consider trying out
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    17
RML for your project, as the license sales support our open
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    18
source development.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    19
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    20
Contents of this file:
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    21
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    22
1. Licensing
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    23
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    24
2. Installation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    25
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    26
   2.1 Source Distribution or Subversion
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    27
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    28
   2.2 Manual Installation without C Compiler (e.g. Windows)
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    29
4318
40df5b03ecad documentation changes
robin <robin@reportlab.com>
parents: 4252
diff changeset
    30
   2.3 Windows packages
4171
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    31
4318
40df5b03ecad documentation changes
robin <robin@reportlab.com>
parents: 4252
diff changeset
    32
   2.4 Mac OSX installation
4171
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    33
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    34
   2.5 Ubuntu and other Debian-based Systems
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    35
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    36
3. Prerequisites / Dependencies
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    37
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    38
4. Documentation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    39
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    40
5. Acknowledgements and Thanks
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    41
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    42
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    43
1. Licensing
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    44
============
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    45
BSD license.  See ``LICENSE.txt`` for details.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    46
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    47
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    48
2. Installation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    49
===============
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    50
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    51
In most cases, ``easy_install reportlab`` or ``pip install reportlab`` will
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    52
do the job.  Full details follow below for each platform.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    53
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    54
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    55
2.1 General prerequisites
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    56
--------------------------
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    57
You need to have installed Python (versions 2.7 or >=3.3),
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    58
and ideally PIL or Pillow with Freetype support; more notes on prerequisites
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    59
follow below.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    60
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    61
2.2. Where to get the code
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    62
------------------------------------------
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    63
Latest builds are available from ReportLab's
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    64
open source download area::
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    65
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    66
    https://www.reportlab.com/pypi/
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    67
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    68
Main releases are also available from the Python Package Index:
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    69
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    70
    http://pypi.python.org/
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    71
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    72
From March 2013, the code is being hosted in Mercurial on BitBucket.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    73
You can obtain the latest code from our Mercurial repository with::
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    74
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    75
    hg clone https://bitbucket.org/rptlab/reportlab
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    76
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    77
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    78
Users of our commercial libraries, and/or anyone who registers on our site,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    79
can also access our commercial area which has exactly the same packages,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    80
paired with the matching commercial ones (rlextra); it is important to keep
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    81
both in sync.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    82
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    83
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    84
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    85
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    86
2.3 Windows Packages
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    87
--------------------
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    88
We no longer made .exe or .msi files.  We provide ``.whl`` files with compiled
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    89
C extensions for all supported python versions at
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    90
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    91
    http://pypi.python.org/pypi/reportlab/
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    92
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    93
These may be installed using recent `pip` or other competent distribution
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    94
package.  If you aren't comfortable with the command line, we recommend pip-win:
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    95
    https://sites.google.com/site/pydatalog/python/pip-for-windows
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    96
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    97
This will NOT install the tests, examples and documentation.  If you want
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    98
to learn your way around the package or do development with it on Windows,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
    99
we suggest you also obtain source from https://bitbucket.org/rptlab/reportlab
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   100
and work with the examples/tests within that directory.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   101
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   102
2.4 Mac OS
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   103
-------------
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   104
On Mac OS, you will need XCode with the Command Line Tools option installed
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   105
in order to compile the C extensions.  On Lion
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   106
or later, type ``clang`` at a prompt; if you get ``command not found`` or
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   107
similar, the C compiler is not installed.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   108
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   109
We then recommend the *brew* installation tool to fetch open source packages.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   110
You should run::
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   111
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   112
    brew install freetype
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   113
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   114
before instaling *reportlab* to ensure that the Python Imaging Library gets
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   115
compiled with JPEG support.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   116
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   117
Thereafter, you can install with  ``easy_install reportlab`` or by fetching
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   118
the source and using ``python setup.py install``
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   119
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   120
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   121
2.5 Unix / Linux
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   122
-----------------
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   123
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   124
On Unix and Mac OS we assume a C compiler is available to compile the
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   125
C extensions.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   126
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   127
On Ubuntu, you will need
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   128
*build-essential*, *libfreetype6-dev*, *python-dev* and *python-imaging*.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   129
Most other Linux and xBSD distributions have packages with
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   130
similar names.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   131
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   132
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   133
Thereafter, you can use ``easy_install reportlab``, ``pip install reportlab``,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   134
or fetch the source and use ``python setup.py install``.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   135
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   136
From Ubuntu 12.04 desktop onwards, a copy of reportlab is already installed.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   137
Take care not to confuse it with any releases you download.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   138
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   139
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   140
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   141
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   142
3. Prerequisites / Dependencies
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   143
===============================
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   144
This works with Python versions 2.7 or >=3.3. Older versions are available
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   145
going back to Python 1.5 or thereabouts.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   146
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   147
There are no absolute prerequisites beyond the Python
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   148
standard library; but the Python Imaging Library (PIL or Pillow)
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   149
is needed to include images other than JPG inside PDF files.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   150
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   151
The C extension are optional but anyone able to do so should
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   152
use _rl_accel as it helps achieve acceptable speeds when wrapping
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   153
paragraphs and measuring text string lengths.  The
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   154
_renderPM extension allows graphics (such as charts) to be saved
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   155
as bitmap images for the web, as well as inside PDFs.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   156
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   157
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   158
4. Documentation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   159
================
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   160
Naturally, we generate our own manuals using the library.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   161
In a 'built' distribution, they may already be present in the
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   162
docs/ directory.  If not, execute ``python genAll.py`` in
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   163
that directory, and it will create three PDF manuals::
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   164
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   165
    reportlab-userguide.pdf
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   166
    reportlab-reference.pdf
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   167
    reportlab-graphics-reference.pdf
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   168
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   169
These are also available in daily build form from the documentation
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   170
page on our web site.   The manuals are very useful 'how-to' examples
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   171
if you are aiming to create long documents.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   172
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   173
5. Test suite
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   174
=============
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   175
Tests are in the ``tests/`` directory.  They can be executed by cd'ing into the
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   176
directory and executing ``python runAll.py``, or from ``python setup.py tests``.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   177
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   178
The tests will simply try to 'import reportlab'.  Be warned that if you already have a copy
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   179
of reportlab installed (which happens by default in Ubuntu 12.04 desktop), it may try to
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   180
run the installed reportlab and cause permission errors as it can't generate PDF files
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   181
without sudo rights.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   182
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   183
If you do not have a copy insralled and run them prior to installation/compilation,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   184
there may be one or two failures from tests which exercise the C extensions that have not
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   185
been compiled.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   186
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   187
The tests mostly produce output files with the same name as the test, but extension
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   188
.pdf.  It is worth reviewing the list of test scripts as they provide valuable 'how
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   189
to' information.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   190
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   191
If you have no internet connection, one or two tests may fail where we try to load images
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   192
from URLs.  This is normal.  The next release of this package will silently skip
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   193
such tests using features only available in Python 2.7.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   194
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   195
6. Demos
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   196
========
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   197
A small number of demo programs are included in ``demos/``, none of which are particularly
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   198
exciting, but which may have some intructional value.  These were the first programs we
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   199
wrote back in 2000.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   200
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   201
The *odyssey* demo serves as our benchmark suite.  If you download the full Odyssey text,
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   202
you can generate a PDF of Homer's Odyssey with either (a) no wrapping, (b) simple paragraphs
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   203
or (c) paragraphs with enough artificial markup (bold/italic on certain words) to exercise
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   204
the parser.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   205
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   206
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   207
7. Acknowledgements and Thanks
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   208
==============================
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   209
``lib/normalDate.py`` originally by Jeff Bauer.
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   210
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4171
diff changeset
   211
Many, many contributors have helped out between 2000 and 2016.
4171
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   212
We try to keep a list in the first chapter of the User Guide; if you
b8639001d315 README.txt space removal
robin
parents: 4170
diff changeset
   213
have contributed and are not listed there, please let us know.