docs/userguide/ch1_intro.py
author rgbecker
Tue, 11 Jul 2000 11:20:23 +0000
changeset 348 218d4b40a55d
parent 346 179378979ab7
child 352 088c93328100
permissions -rw-r--r--
Unix novices info added
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
     1
#ch1_intro
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
     2
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
     3
from genuserguide import *
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 340
diff changeset
     4
import reportlab
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
     5
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 340
diff changeset
     6
title("User Guide")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 340
diff changeset
     7
centred('ReportLab Version ' + reportlab.Version)
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 340
diff changeset
     8
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 340
diff changeset
     9
nextTemplate("Normal")
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    10
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    11
########################################################################
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    12
#
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    13
#               Chapter 1
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    14
#
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    15
########################################################################
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    16
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    17
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    18
heading1("Introduction")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    19
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    20
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    21
heading2("About this document")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    22
disc("""This document is intended to be a conversational introduction
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    23
to the use of the ReportLab packages.  Some previous programming experience
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    24
is presumed and familiarity with the Python Programming language is
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    25
recommended.  If you are new to Python, we tell you in the next section
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    26
where to go for orientation.
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    27
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    28
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    29
disc("""After working your way throught this, you should be ready to begin
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    30
writing programs to produce sophisticated reports.
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    31
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    32
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    33
disc("""In this chapter, we will cover the groundwork:""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    34
bullet("What is ReportLab all about, and why should I use it?")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    35
bullet("What is Python?")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    36
bullet("How do I get everything set up and running?")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    37
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    38
todo("""
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    39
Be warned! This document is in a <em>very</em> preliminary form.  We need
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    40
your help to make sure it is complete and helpful.  Please send any
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    41
feedback to our mailing list, reportlab-users@egroups.com.
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    42
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    43
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    44
heading2("What is ReportLab?")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    45
disc("""ReportLab is a software library lets you directly create documents
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    46
in Adobe's Portabe Document Format (PDF) using the Python programming
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    47
language. """)
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    48
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    49
disc("""PDF is the global standard for electronic documents. It
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    50
supports high-quality printing yet is totally portable across
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    51
platforms, thanks the freely available Acrobat Reader.  Any
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    52
application which previously generated hard copy reports can
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    53
benefit from making PDF documents instead; these can be archived,
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    54
emailed, placed on the web, or printed out the old-fashioned way.
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    55
However, the PDF file format (600 pages long) is a complex
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    56
indexed binary format which is impossible to write directly.
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    57
Until now, most of the world's PDF documents have been produced
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    58
by Adobe's Acrobat tools, which act as a 'print driver.
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    59
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    60
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    61
disc("""The ReportLab library directly creates PDF based on
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    62
your graphics commands.  There are no intervening steps
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    63
and thus no time-consuming pipelines.  Your applications
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    64
can generate reports extremely fast - sometimes orders
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    65
of magnitude faster than traditional report-writing
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    66
tools.""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    67
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    68
disc("""In addition, because you are writing a program
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    69
in a powerful general purpose language, there are no
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    70
restrictions at all on where you get your data from,
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    71
how you transform it, and the the kind of output
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    72
you can create.  And you can reuse code across
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    73
whole families of reports.""")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
    74
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    75
disc("""The ReportLab library is expected to be useful
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    76
in at least the following contexts:""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    77
bullet("Dynamic PDF generation on the web")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    78
bullet("High-volume corporate reporting and database publishing")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    79
bullet("""An embeddable print engine for other applications, including
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    80
a 'report language' so that users can customize their own reports. <i>
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    81
This is particularly relevant to cross-platform apps which cannot
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    82
rely on a consistent printing or previewing API on each operating
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    83
system</i>.""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    84
bullet("""A 'build system' for complex documents with charts, tables
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    85
and text such as management accounts, statistical reports and
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    86
scientific papers """)
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
    87
bullet("""Going from XML to PDF in one step!""")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
    88
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
    89
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
    90
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
    91
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    92
heading2("What is Python?")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    93
disc("""<para lindent=+36>
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    94
<b>python</b>, (<i>Gr. Myth.</i> An enormous serpent that lurked in the cave of Mount Parnassus and was slain
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    95
by Apollo) <b>1.</b> any of a genus of large, non-poisonous snakes of Asia, Africa and Australia that
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    96
suffocate their prey to death. <b>2.</b> popularly, any large snake that crushes its prey. <b>3.</b> totally awesome,
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    97
bitchin' language that will someday crush the $'s out of certain <i>other</i> so-called VHLL's ;-)</para>
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    98
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
    99
disc("""
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   100
Python is an <i>interpreted, interactive, object-oriented</i> programming language. It is often compared to Tcl, Perl,
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   101
Scheme or Java. 
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   102
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   103
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   104
disc("""
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   105
Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   106
dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   107
various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily written in C or C++.
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   108
Python is also usable as an extension language for applications that need a programmable interface. 
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   109
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   110
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   111
disc("""
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   112
The Python implementation is portable: it runs on many brands of UNIX, on Windows, DOS, OS/2, Mac, Amiga... If
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   113
your favorite system isn't listed here, it may still be supported, if there's a C compiler for it. Ask around on
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   114
comp.lang.python -- or just try compiling Python yourself. 
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   115
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   116
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   117
disc("""
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   118
Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>. 
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   119
""")
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   120
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   121
heading2("Installation and Setup")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   122
heading3("Installation for experts")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   123
disc("""First of all, we'll give you the high-speed version for experienced
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   124
Python developers:""")
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   125
list("Install Python 1.5.1 or later")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   126
list("""If you want to produce compressed PDF files (recommended),
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   127
check zlib is installed.""")
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   128
list("""If you want to work with bitmap images, install and
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   129
test the Python Imaging Library""")
348
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   130
list("""Unpack the reportlab package (reportlab.zip
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   131
or reportlab.tgz) into a directory on your path""")
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   132
list("""$cd$ to ^reportlab/pdfgen/test^ and execute $testpdfen.py$,
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   133
which will create a file 'testpdfgen.pdf'.""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   134
disc(" ")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   135
disc("""If you have any problems, check the 'Detailed Instructions' section below""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   136
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   137
heading3("A note on available versions")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   138
disc("""The $reportlab$
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   139
library can be found at ftp.reportlab.com in the top-level directory.
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   140
Each successive version is stored in both zip and tgz format, but the
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   141
contents are identical.  Versions are numbered:  ReportLab_0_85.zip,
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   142
ReportLab_0_86.zip and so on.  The latest stable version is also
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   143
available as just 'reportlab.zip' (or 'reportlab.tgz'), which
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   144
is actually a symbolic link to the latest numbered version.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   145
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   146
disc("""We also make nightly snapshots of our CVS tree available.  In
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   147
general, these are very stable because we have a comprehensive test
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   148
suite that all developers can run at any time.  What happens is that
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   149
new modules and functions within the overall package may be in a state
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   150
of flux, but stable features can be assumed to be stable.  If a bug is
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   151
reported and fix, we assume people who need the fix in a hurry will
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   152
get $current.zip$""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   153
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   154
disc("""The next section assumes you
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   155
don't know much about Python.  We cover all of the steps for three
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   156
common platforms, including how to verify that each one is complete.
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   157
While this may seem like a long list, everything takes 5 minutes if
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   158
you have the binaries at hand.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   159
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   160
heading3("Instructions for novices: Windows")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   161
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   162
restartList()
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   163
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   164
list("""Get and install Python from http://www.python.org/.
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   165
Follow the links to 'Download' and get the latest official
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   166
version.  Currently this is Python 1.5.2 in the file 'py152.exe'.
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   167
It will prompt you for a directory location, which by default is
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   168
$C:\Program Files\Python$. This works, but we recommend entering
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   169
$C:\Python15$.  Python 1.6 will be out shortly and will adopt
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   170
C:\Python16 as its default; and quite often one wants to CD into the
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   171
Python directory from a command prompt, so a path without spaces saves
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   172
a lot of typing!  After installing, you should be able to run the
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   173
'Python (command line)' option from the Start Menu.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   174
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   175
list("""If on Win9x, we recommend either copying python.exe to a
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   176
location on your path, or adding your Python directory to the path, so
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   177
that you can execute Python from any directory.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   178
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   179
list("""If you want a nice editing environment or might need to
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   180
access Microsoft applications, get the Pythonwin add-on package from
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   181
the same page.  Once this is installed, you can start Pythonwin from
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   182
the Start Menu and get a GUI application.""")
337
76141601ec1f Broke out chapter 1
andy_robinson
parents:
diff changeset
   183
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   184
disc("""The next step is optional and only necessary if you want to
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   185
include images in your reports; it can also be carried out later.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   186
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   187
list("Install the Python Imaging Library.  (todo:  make up a bundle that works)")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   188
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   189
list("Add the DLLs in PIL to your Python\DLLs directory")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   190
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   191
list("""To verify,
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   192
start the command line Python and type "import Image", followed by
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   193
"import _imaging".  If you see no error messages, all is well.""")
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   194
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   195
disc("""Now for reportlab itself:""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   196
list("""Unzip the archive straight into
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   197
your Python directory; it creates a subdirectory named
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   198
"reportlab".  You should now be able to go to a Python
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   199
prompt and type $import reportlab$ without getting
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   200
an error message.""")
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   201
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   202
list("""Open up a DOS prompt and CD to
348
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   203
"..\\reportlab\\pdfgen\\test".  On NT, enter "testpdfgen.py"; on
340
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   204
Win9x, enter "python testpdfgen.py".  After a couple of seconds,
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   205
the script completes and the file testpdfgen.pdf should be ready for
f3f2af39e7d7 More work on chapter 1
andy_robinson
parents: 337
diff changeset
   206
viewing.  If PIL is installed, there should be a "Python Powered"
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   207
image on the last page.  You're done!""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   208
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   209
heading3("Instructions for Python novices: Unix")
348
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   210
restartList()
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   211
list("""First you need to decide if you want to install the Python sources
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   212
and compile these yourself or if you only want to install a binary package
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   213
for one of the many variants of Linux or Unix. If yes download the latest
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   214
sources from http://www.python.org (currently the latest source is
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   215
in http://www.python.org/ftp/python/src/py152.tgz). Otherwise
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   216
get the latest RPM or DEB or whatever package and install (or get your
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   217
super user to do the work).""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   218
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   219
list("""If you are building yourself, unpack the sources into a temporary directory using a tar command
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   220
eg $tar xzvf py152.tgz$; this will create a subdirectory called Python-1.5.2
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   221
(or whatever) cd into this directory. Then read the file $README$! It contains the 
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   222
latest information on how to install Python.""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   223
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   224
list("""Check that the zlib extension will be installed by default by editing
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   225
the file Modules/Setup.in and ensuring that (near line 405) the line
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   226
containing zlib zlibmodule.c is uncommented ie has no hash '#' character at the
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   227
beginning. You also need to decide if you will be installing in the default location
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   228
(/usr/local/) or in some other place.""")
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   229
348
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   230
list("""Invoke the command $./configure --prefix=/usr/local$ this should configure
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   231
the source directory for building. Then you can build the binaries with
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   232
a $make$ command. If your $make$ command is not up to it try building
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   233
with $make MAKE=make$. If all goes well install with $make install$.""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   234
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   235
list("""If all has gone well and python is in the execution search path
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   236
you should now be able to type $python$ and see a <b>Python</b> prompt.
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   237
Once you can do that it's time to try and install ReportLab.
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   238
First get the latest reportlab.tgz.
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   239
If ReportLab is to be available to all then the reportlab archive should be unpacked in
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   240
the lib/site-python directory (typically /usr/local/lib/site-python) if neccessary by
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   241
a superuser.
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   242
Otherwise unpack in a directory of your choice and arrange for that directory to be on your
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   243
$PYTHONPATH$ variable.
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   244
""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   245
eg("""
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   246
#put something like this in your
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   247
#shell rcfile
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   248
PYTHONPATH=$HOME/mypythonpackages
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   249
export PYTHONPATH
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   250
""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   251
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   252
disc("""You should now be able to run python and execute the python statement
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   253
""")
218d4b40a55d Unix novices info added
rgbecker
parents: 346
diff changeset
   254
eg("""import reportlab""")
346
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   255
heading3("Instructions for Python novices: Mac")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   256
todo("Just?")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   257
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   258
heading2("Getting Involved")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   259
disc("""ReportLab is an Open Source project.  Although we are
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   260
a commercial company, we do not have gazillions of dollars
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   261
of dot-com venture capital, and we make no income directly
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   262
from the product.  We therefore need help from the community
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   263
as much as any other Open Source project.  There are many
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   264
ways in which you can help:""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   265
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   266
bullet("""General feedback on the core A.P.I. Does it work for you?
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   267
are there any rough edges?  Does anything feel clunky and awkward?""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   268
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   269
bullet("""New objects to put in reports, or useful utilities for the library.
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   270
We have an open standard for report objects, so if you have written a nice
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   271
chart or table class, why not contribute it?""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   272
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   273
bullet("""Demonstrations and Case Studies: If you have produced some nice
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   274
output, send it to us (with or without scripts).  If ReportLab solved a
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   275
problem for you at work, write a little 'case study' and send it in!
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   276
And if your web site uses our tools to make reports, let us link to it!""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   277
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   278
bullet("""Working on the core code:  we have a long list of things
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   279
to refine or to implement.  If you are missing some features or
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   280
just want to help out, let us know!""")
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   281
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   282
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   283
disc("""The first step for anyone wanting to learn more or
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   284
get involved is to join the mailing list.  Just send an email
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   285
with the subject "Subscribe" to
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   286
$reportlab-users-subscribe@egroups.com$.  You can also browse
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   287
through the group's archives and contributions at
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   288
$http://www.egroups.com/group/reportlab-users$.  This list is
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   289
the place to report bugs and get support. """)
179378979ab7 Introduction is 'coherent' - if not exactly finished:-)
andy_robinson
parents: 344
diff changeset
   290