docs/userguide/ch1_intro.py
author robin <robin@reportlab.com>
Tue, 07 Mar 2017 10:00:34 +0000
changeset 4330 617ffa6bbdc8
parent 4252 fe660f227cac
child 4336 d39c63b164bc
permissions -rw-r--r--
changes for release 3.4.0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4330
617ffa6bbdc8 changes for release 3.4.0
robin <robin@reportlab.com>
parents: 4252
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2017
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     2
#see license.txt for license details
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
     3
__version__ = '$Id$'
2966
c9df63ccabdf reportlab-2.2: major changes to make tests run
rgbecker
parents: 2963
diff changeset
     4
from tools.docco.rl_doc_utils import *
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
     5
from reportlab.platypus.tableofcontents import TableOfContents
3082
b7ceb99bcb86 Add creation date to userguide.
jonas
parents: 3064
diff changeset
     6
from datetime import datetime
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     7
import reportlab
4218
10f8064ef68b allow invariance in tests/manuals
robin
parents: 4151
diff changeset
     8
from reportlab.rl_config import invariant
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     9
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    10
title("ReportLab PDF Library")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    11
title("User Guide")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    12
centred('ReportLab Version ' + reportlab.Version)
4218
10f8064ef68b allow invariance in tests/manuals
robin
parents: 4151
diff changeset
    13
centred((datetime(2000,1,1,0,0,0) if invariant else datetime.now()).strftime('Document generated on %Y/%m/%d %H:%M:%S %Z'))
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    14
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    15
nextTemplate("TOC")
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    16
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3047
diff changeset
    17
headingTOC()
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    18
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3047
diff changeset
    19
toc = TableOfContents()
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    20
PS = ParagraphStyle
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3047
diff changeset
    21
toc.levelStyles = [
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    22
    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1', leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    23
    PS(fontSize=12, name='TOCHeading2', leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    24
    PS(fontSize=10, name='TOCHeading3', leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    25
    PS(fontSize=10, name='TOCHeading4', leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    26
]
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3047
diff changeset
    27
getStory().append(toc)
3047
ddf424d4c290 Added table of content to userguide.
jonas
parents: 2977
diff changeset
    28
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    29
nextTemplate("Normal")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    30
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    31
########################################################################
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    32
#
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    33
#               Chapter 1
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    34
#
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    35
########################################################################
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    36
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    37
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    38
heading1("Introduction")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    39
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    40
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    41
heading2("About this document")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    42
disc("""This document is an introduction to the ReportLab PDF library.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    43
Some previous programming experience
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    44
is presumed and familiarity with the Python Programming language is
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    45
recommended.  If you are new to Python, we tell you in the next section
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    46
where to go for orientation.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    47
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    48
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    49
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    50
This manual does not cover 100% of the features, but should explain all
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    51
the main concepts and help you get started, and point you at other
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    52
learning resources. 
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    53
After working your way through this, you should be ready to begin
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    54
writing programs to produce sophisticated reports.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    55
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    56
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    57
disc("""In this chapter, we will cover the groundwork:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    58
bullet("What is ReportLab all about, and why should I use it?")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    59
bullet("What is Python?")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    60
bullet("How do I get everything set up and running?")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    61
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    62
todo("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    63
We need your help to make sure this manual is complete and helpful.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    64
Please send any feedback to our user mailing list,
3311
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
    65
which is signposted from <a href="http://www.reportlab.com/">www.reportlab.com</a>.
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    66
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    67
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    68
heading2("What is the ReportLab PDF Library?")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    69
disc("""This is a software library that lets you directly
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    70
create documents in Adobe's Portable Document Format (PDF) using
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    71
the Python programming language.   It also creates charts and data graphics
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    72
in various bitmap and vector formats as well as PDF.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    73
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    74
disc("""PDF is the global standard for electronic documents. It
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    75
supports high-quality printing yet is totally portable across
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    76
platforms, thanks to the freely available Acrobat Reader.  Any
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    77
application which previously generated hard copy reports or driving a printer
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    78
can benefit from making PDF documents instead; these can be archived,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    79
emailed, placed on the web, or printed out the old-fashioned way.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    80
However, the PDF file format is a complex
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    81
indexed binary format which is impossible to type directly.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    82
The PDF format specification is more than 600 pages long and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    83
PDF files must provide precise byte offsets -- a single extra
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    84
character placed anywhere in a valid PDF document can render it
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    85
invalid.  This makes it harder to generate than HTML.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    86
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    87
disc("""Most of the world's PDF documents have been produced
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    88
by Adobe's Acrobat tools, or rivals such as JAWS PDF Creator, which act
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    89
as 'print drivers'.  Anyone wanting to automate PDF production would
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    90
typically use a product like Quark, Word or Framemaker running in a loop
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    91
with macros or plugins, connected to Acrobat. Pipelines of several
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    92
languages and products can be slow and somewhat unwieldy.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    93
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    94
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    95
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    96
disc("""The ReportLab library directly creates PDF based on
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    97
your graphics commands.  There are no intervening steps.  Your applications
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    98
can generate reports extremely fast - sometimes orders
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    99
of magnitude faster than traditional report-writing
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   100
tools.   This approach is shared by several other libraries - PDFlib for C,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   101
iText for Java, iTextSharp for .NET and others.  However, The ReportLab library
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   102
differs in that it can work at much higher levels, with a full featured engine
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   103
for laying out documents complete with tables and charts.  """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   104
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   105
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   106
disc("""In addition, because you are writing a program
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   107
in a powerful general purpose language, there are no
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   108
restrictions at all on where you get your data from,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   109
how you transform it, and the kind of output
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   110
you can create.  And you can reuse code across
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   111
whole families of reports.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   112
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   113
disc("""The ReportLab library is expected to be useful
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   114
in at least the following contexts:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   115
bullet("Dynamic PDF generation on the web")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   116
bullet("High-volume corporate reporting and database publishing")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   117
bullet("""An embeddable print engine for other applications, including
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   118
a 'report language' so that users can customize their own reports. <i>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   119
This is particularly relevant to cross-platform apps which cannot
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   120
rely on a consistent printing or previewing API on each operating
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   121
system</i>.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   122
bullet("""A 'build system' for complex documents with charts, tables
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   123
and text such as management accounts, statistical reports and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   124
scientific papers """)
3310
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   125
bullet("""Going from XML to PDF in one step""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   126
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   127
3310
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   128
heading2("ReportLab's commercial software")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   129
disc("""
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   130
The ReportLab library forms the foundation of our commercial solution for
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   131
PDF generation, Report Markup Language (RML).  This is available for evaluation
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   132
on our web site with full documentation.   We believe that RML is the fastest
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   133
and easiest way to develop rich PDF workflows.  You work in a markup language
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   134
at a similar level to HTML, using your favorite templating system to populate
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   135
an RML document; then call our rml2pdf API function to generate a PDF.  It's
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   136
what ReportLab staff use to build all of the solutions you can see on reportlab.com.
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   137
Key differences:
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   138
""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   139
bullet("""Fully documented with two manuals, a formal specification (the DTD) and extensive self-documenting tests.  (By contrast, we try to make sure the open source documentation isn't wrong, but we don't always keep up with the code)""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   140
bullet("""Work in high-level markup rather than constructing graphs of Python objects """)
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   141
bullet("""Requires no Python expertise - your colleagues may thank you after you've left!'""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   142
bullet("""Support for vector graphics and inclusion of other PDF documents""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   143
bullet("""Many more useful features expressed with a single tag, which would need a lot
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   144
of coding in the open source package""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   145
bullet("""Commercial support is included""")
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   146
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   147
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   148
disc("""
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   149
We ask open source developers to consider trying out RML where it is appropriate.
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   150
You can register on our site and try out a copy before buying.
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   151
The costs are reasonable and linked to the volume of the project, and the revenue
dadf804c1f06 plug commercial package, tidy up readme
andy
parents: 3293
diff changeset
   152
helps us spend more time developing this software.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   153
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   154
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   155
heading2("What is Python?")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   156
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   157
Python is an <i>interpreted, interactive, object-oriented</i> programming language. It is often compared to Tcl, Perl,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   158
Scheme or Java.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   159
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   160
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   161
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   162
Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   163
dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   164
various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily written in C or C++.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   165
Python is also usable as an extension language for applications that need a programmable interface.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   166
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   167
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   168
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   169
disc("""
3064
3a05ee120941 changed install instructions
tim
parents: 3059
diff changeset
   170
Python is as old as Java and has been growing steadily in popularity for years; since our
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   171
library first came out it has entered the mainstream.  Many ReportLab library users are
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   172
already Python devotees, but if you are not, we feel that the language is an excellent
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   173
choice for document-generation apps because of its expressiveness and ability to get
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   174
data from anywhere.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   175
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   176
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   177
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   178
Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   179
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   180
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   181
heading2("Acknowledgements")
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   182
disc("""Many people have contributed to ReportLab.  We would like to thank in particular 
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   183
(in alphabetical order): 
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   184
Albertas Agejevas, 
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   185
Alex Buck, 
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   186
Andre Reitz, 
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   187
Andrew Cutler,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   188
Andrew Mercer, 
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   189
Ben Echols,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   190
Benjamin Dumke,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   191
Benn B,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   192
Chad Miller, 
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   193
Chris Buergi,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   194
Chris Lee, 
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   195
Christian Jacobs, 
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   196
Dinu Gherman,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   197
Edward Greve,
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   198
Eric Johnson,
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   199
Felix Labrecque,  
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   200
Fubu @ bitbucket,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   201
Gary Poster, 
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   202
Germán M. Bravo,
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   203
Guillaume Francois, 
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   204
Hans Brand,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   205
Henning Vonbargen,
3288
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   206
Hosam Aly,
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   207
Ian Stevens, 
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   208
James Martin-Collar, 
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   209
Jeff Bauer,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   210
Jerome Alet,
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   211
Jerry Casiano,
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   212
Jorge Godoy,
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   213
Keven D Smith,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   214
Kyle MacFarlane,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   215
Magnus Lie Hetland,
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   216
Marcel Tromp, 
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   217
Marius Gedminas,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   218
Mark de Wit,
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   219
Matthew Duggan,
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   220
Matthias Kirst,
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   221
Matthias Klose,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   222
Max M, 
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   223
Michael Egorov,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   224
Michael Spector,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   225
Mike Folwell,
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   226
Mirko Dziadzka,
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   227
Moshe Wagner,
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   228
Nate Silva,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   229
Paul McNett, 
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   230
Peter Johnson, 
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   231
PJACock,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   232
Publio da Costa Melo,  
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   233
Randolph Bentson,
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   234
Robert Alsina,
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   235
Robert Hölzl,
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   236
Robert Kern,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   237
Ron Peleg,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   238
Ruby Yocum,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   239
Simon King,
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   240
Stephan Richter,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   241
Steve Halasz, 
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   242
Stoneleaf @ bitbucket,
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   243
T Blatter,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   244
Tim Roberts,
3450
ccd0dd56336d userguide: Updated acknowledgements.
juraj
parents: 3311
diff changeset
   245
Tomasz Swiderski,
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   246
Ty Sarna,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   247
Volker Haas,
4252
fe660f227cac changes for release 3.3.0
robin
parents: 4218
diff changeset
   248
Yoann Roman,
3287
c7d13481010e userguide changes
meitham
parents: 3082
diff changeset
   249
and many more.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   250
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   251
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   252
disc("""Special thanks go to Just van Rossum for his valuable assistance with
2977
beca8d75f400 reportlab: remove LetErrorRobot-Chrome, rina & luxi. Add DarkGardenMK and fix tests
rgbecker
parents: 2967
diff changeset
   253
font technicalities.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   254
4151
fbc7f3aeb4c7 userguide - fix minor typos
James P-K <jamespk@reportlab.com>
parents: 4040
diff changeset
   255
disc("""Moshe Wagner and Hosam Aly deserve a huge thanks for contributing to the RTL patch, which is not yet on the trunk.""")
3288
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   256
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   257
disc("""Marius Gedminas deserves a big hand for contributing the work on TrueType fonts and we
2977
beca8d75f400 reportlab: remove LetErrorRobot-Chrome, rina & luxi. Add DarkGardenMK and fix tests
rgbecker
parents: 2967
diff changeset
   258
are glad to include these in the toolkit. Finally we thank Michal Kosmulski for the DarkGarden font
beca8d75f400 reportlab: remove LetErrorRobot-Chrome, rina & luxi. Add DarkGardenMK and fix tests
rgbecker
parents: 2967
diff changeset
   259
for and Bitstream Inc. for the Vera fonts.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   260
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   261
heading2("Installation and Setup")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   262
3672
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   263
disc("""To avoid duplication, the installation instructions are kept in the README file
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   264
in our distribution, which can be viewed online at ^http://bitbucket.org/rptlab/reportlab/^""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   265
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   266
disc("""This release (3.0) of ReportLab requires Python versions 2.7, 3.3 or higher.  
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   267
	If you need to use Python 2.5 or 2.6, please use the latest ReportLab 2.x package.
3064
3a05ee120941 changed install instructions
tim
parents: 3059
diff changeset
   268
""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   269
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   270
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   271
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   272
heading2("Getting Involved")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   273
disc("""ReportLab is an Open Source project.  Although we are
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   274
a commercial company we provide the core PDF generation
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   275
sources freely, even for commercial purposes, and we make no income directly
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   276
from these modules.  We also welcome help from the community
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   277
as much as any other Open Source project.  There are many
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   278
ways in which you can help:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   279
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   280
bullet("""General feedback on the core API. Does it work for you?
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   281
Are there any rough edges?  Does anything feel clunky and awkward?""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   282
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   283
bullet("""New objects to put in reports, or useful utilities for the library.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   284
We have an open standard for report objects, so if you have written a nice
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   285
chart or table class, why not contribute it?""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   286
3288
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   287
bullet("""Snippets and Case Studies: If you have produced some nice
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   288
output, register online on ^http://www.reportlab.com^ and submit a snippet
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   289
of your output (with or without scripts).  If ReportLab solved a
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   290
problem for you at work, write a little 'case study' and submit it.
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   291
And if your web site uses our tools to make reports, let us link to it.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   292
We will be happy to display your work (and credit it with your name
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   293
and company) on our site!""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   294
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   295
bullet("""Working on the core code:  we have a long list of things
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   296
to refine or to implement.  If you are missing some features or
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   297
just want to help out, let us know!""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   298
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   299
disc("""The first step for anyone wanting to learn more or
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   300
get involved is to join the mailing list.  To Subscribe visit
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   301
$http://two.pairlist.net/mailman/listinfo/reportlab-users$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   302
From there you can also browse through the group's archives
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   303
and contributions.  The mailing list is
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   304
the place to report bugs and get support. """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   305
3672
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   306
disc("""The code now lives on BitBucket ($http://bitbucket.org/rptlab/reportlab/$)
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   307
in a Mercurial repository, along with an issue tracker and wiki.  Everyone should
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   308
feel free to contribute, but if you are working actively on some improvements
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   309
or want to draw attention to an issue, please use the mailing list to let us know.""")
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   310
a7563a34f803 slimmed down manual to not duplicate website release notes
Andy Robinson <andy@reportlab.com>
parents: 3618
diff changeset
   311
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   312
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   313
heading2("Site Configuration")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   314
disc("""There are a number of options which most likely need to be configured globally for a site.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   315
The python script module $reportlab/rl_config.py$ may be edited to change the values of several
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   316
important sitewide properties.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   317
bullet("""verbose: set to integer values to control diagnostic output.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   318
bullet("""shapeChecking: set this to zero to turn off a lot of error checking in the graphics modules""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   319
bullet("""defaultEncoding: set this to WinAnsiEncoding or MacRomanEncoding.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   320
bullet("""defaultPageSize: set this to one of the values defined in reportlab/lib/pagesizes.py; as delivered
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   321
it is set to pagesizes.A4; other values are pagesizes.letter etc.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   322
bullet("""defaultImageCaching: set to zero to inhibit the creation of .a85 files on your
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   323
hard-drive. The default is to create these preprocessed PDF compatible image files for faster loading""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   324
bullet("""T1SearchPath: this is a python list of strings representing directories that
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   325
may be queried for information on Type 1 fonts""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   326
bullet("""TTFSearchPath: this is a python list of strings representing directories that
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   327
may be queried for information on TrueType fonts""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   328
bullet("""CMapSearchPath: this is a python list of strings representing directories that
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   329
may be queried for information on font code maps.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   330
bullet("""showBoundary: set to non-zero to get boundary lines drawn.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   331
bullet("""ZLIB_WARNINGS: set to non-zero to get warnings if the Python compression extension is not found.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   332
bullet("""pageComression: set to non-zero to try and get compressed PDF.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   333
bullet("""allowtableBoundsErrors: set to 0 to force an error on very large Platypus table elements""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   334
bullet("""emptyTableAction: Controls behaviour for empty tables, can be 'error' (default), 'indicate' or 'ignore'.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   335
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   336
heading2("Learning More About Python")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   337
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   338
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   339
If you are a total beginner to Python, you should check out one or more from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   340
growing number of resources on Python programming. The following are freely
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   341
available on the web:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   342
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   343
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   344
3311
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
   345
bullet("""<b>Python Documentation.  </b>
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
   346
A list of documentation on the Python.org web site.
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
   347
$http://www.python.org/doc/$
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   348
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   349
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   350
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   351
bullet("""<b>Python Tutorial.  </b>
3311
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
   352
The official Python Tutorial , originally written by Guido van Rossum himself.
7d7b485c76c3 updated links in userguide
tim
parents: 3310
diff changeset
   353
$http://docs.python.org/tutorial/$
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   354
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   355
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   356
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   357
bullet("""<b>Learning to Program.  </b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   358
A tutorial on programming by Alan Gauld. Has a heavy emphasis on
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   359
Python, but also uses other languages.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   360
$http://www.freenetpages.co.uk/hp/alan.gauld/$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   361
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   362
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   363
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   364
bullet("""<b>Instant Python</b>.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   365
A 6-page minimal crash course by Magnus Lie Hetland.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   366
$http://www.hetland.org/python/instant-python.php$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   367
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   368
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   369
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   370
bullet("""<b>Dive Into Python</b>.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   371
A free Python tutorial for experienced programmers.
3613
8117583a482c Updated user guide to drop support of Python 2.4
rptlab
parents: 3611
diff changeset
   372
$http://www.diveintopython.net/$
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   373
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   374
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   375
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   376
from reportlab.lib.codecharts import SingleByteEncodingChart
2966
c9df63ccabdf reportlab-2.2: major changes to make tests run
rgbecker
parents: 2963
diff changeset
   377
from tools.docco.stylesheet import getStyleSheet
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   378
styles = getStyleSheet()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   379
indent0_style = styles['Indent0']
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   380
indent1_style = styles['Indent1']
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   381
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   382
heading2("Goals for the 3.x release series")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   383
disc("""ReportLab 3.0 has been produced to help in the migration to Python 3.x.  Python 3.x will
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   384
be standard in future Ubuntu releases and is gaining popularity, and a good proportion
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   385
of major Python packages now run on Python 3.  """)
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   386
3288
d361ad4e5bf6 user guide changes
meitham
parents: 3287
diff changeset
   387
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   388
4040
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   389
bullet("""Python 3.x compatibility.  A single line of code should run on 2.7 and 3.3""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   390
bullet(""" __init__.py restricts to 2.7 or >=3.3""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   391
bullet("""__init__.py allow the import of on optional reportlab.local_rl_mods to allow monkey patching etc.""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   392
bullet("""rl_config now imports rl_settings & optionally local_rl_settings""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   393
bullet("""ReportLab C extensions now live inside reportlab; _rl_accel is no longer required. All _rl_accel imports now pass through reportlab.lib.rl_accel""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   394
bullet("""xmllib is gone, alongside the paraparser stuff that caused issues in favour of HTMLParser.""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   395
bullet("""some obsolete C extensions (sgmlop and pyHnj) are gone""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   396
bullet("""Improved support for multi-threaded systems to the _rl_accel C extension module.""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   397
bullet("""Removed reportlab/lib/ para.py & pycanvas.py.  These would better belong in third party packages, which can make use of the monkeypatching feature above.""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   398
bullet("""Add ability to output greyscale and 1-bit PIL images without conversion to RGB. (contributed by Matthew Duggan)""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   399
bullet("""highlight annotation (contributed by Ben Echols)""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   400
bullet("""full compliance with pip, easy_install, wheels etc""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   401
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   402
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   403
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   404
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   405
disc("""Detailed release notes are available at 
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   406
$http://www.reportlab.com/software/documentation/relnotes/30/$""")
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   407
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   408
60080318e740 release 3.0 documentation updates
Andy Robinson <andy@reportlab.com>
parents: 3678
diff changeset
   409