author  andy_robinson 
Tue, 11 Jul 2000 06:48:31 +0000  
changeset 346  179378979ab7 
parent 344  dd6e41c2b0ed 
child 348  218d4b40a55d 
permissions  rwrr 
337  1 
#ch1_intro 
2 

3 
from genuserguide import * 

344
dd6e41c2b0ed
Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents:
340
diff
changeset

4 
import reportlab 
337  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  10 

11 
######################################################################## 

12 
# 

13 
# Chapter 1 

14 
# 

15 
######################################################################## 

16 

17 

18 
heading1("Introduction") 

19 

20 

21 
heading2("About this document") 

22 
disc("""This document is intended to be a conversational introduction 

23 
to the use of the ReportLab packages. Some previous programming experience 

24 
is presumed and familiarity with the Python Programming language is 

25 
recommended. If you are new to Python, we tell you in the next section 

26 
where to go for orientation. 

27 
""") 

28 

29 
disc("""After working your way throught this, you should be ready to begin 

30 
writing programs to produce sophisticated reports. 

31 
""") 

32 

33 
disc("""In this chapter, we will cover the groundwork:""") 

34 
bullet("What is ReportLab all about, and why should I use it?") 

35 
bullet("What is Python?") 

36 
bullet("How do I get everything set up and running?") 

37 

38 
todo(""" 

39 
Be warned! This document is in a <em>very</em> preliminary form. We need 

40 
your help to make sure it is complete and helpful. Please send any 

41 
feedback to our mailing list, reportlabusers@egroups.com. 

42 
""") 

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 highquality 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 oldfashioned 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  59 
""") 
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 timeconsuming 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 reportwriting 
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  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("Highvolume 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 crossplatform 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  88 

89 

90 

91 

337  92 
heading2("What is Python?") 
93 
disc("""<para lindent=+36> 

94 
<b>python</b>, (<i>Gr. Myth.</i> An enormous serpent that lurked in the cave of Mount Parnassus and was slain 

95 
by Apollo) <b>1.</b> any of a genus of large, nonpoisonous snakes of Asia, Africa and Australia that 

96 
suffocate their prey to death. <b>2.</b> popularly, any large snake that crushes its prey. <b>3.</b> totally awesome, 

97 
bitchin' language that will someday crush the $'s out of certain <i>other</i> socalled VHLL's ;)</para> 

98 
""") 

99 
disc(""" 

100 
Python is an <i>interpreted, interactive, objectoriented</i> programming language. It is often compared to Tcl, Perl, 

101 
Scheme or Java. 

102 
""") 

103 

104 
disc(""" 

105 
Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level 

106 
dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to 

107 
various windowing systems (X11, Motif, Tk, Mac, MFC). New builtin modules are easily written in C or C++. 

108 
Python is also usable as an extension language for applications that need a programmable interface. 

109 
""") 

110 

111 
disc(""" 

112 
The Python implementation is portable: it runs on many brands of UNIX, on Windows, DOS, OS/2, Mac, Amiga... If 

113 
your favorite system isn't listed here, it may still be supported, if there's a C compiler for it. Ask around on 

114 
comp.lang.python  or just try compiling Python yourself. 

115 
""") 

116 

117 
disc(""" 

118 
Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>. 

119 
""") 

120 

121 
heading2("Installation and Setup") 

340  122 
heading3("Installation for experts") 
123 
disc("""First of all, we'll give you the highspeed version for experienced 

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  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  129 
test the Python Imaging Library""") 
346
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

130 
list("""Unzip the reportlab package (reportlab.zip 
340  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  135 
disc("""If you have any problems, check the 'Detailed Instructions' section below""") 
136 

137 
heading3("A note on available versions") 

138 
disc("""The $reportlab$ 

139 
library can be found at ftp.reportlab.com in the toplevel directory. 

140 
Each successive version is stored in both zip and tgz format, but the 

141 
contents are identical. Versions are numbered: ReportLab_0_85.zip, 

142 
ReportLab_0_86.zip and so on. The latest stable version is also 

143 
available as just 'reportlab.zip' (or 'reportlab.tgz'), which 

144 
is actually a symbolic link to the latest numbered version.""") 

145 

146 
disc("""We also make nightly snapshots of our CVS tree available. In 

147 
general, these are very stable because we have a comprehensive test 

148 
suite that all developers can run at any time. What happens is that 

149 
new modules and functions within the overall package may be in a state 

150 
of flux, but stable features can be assumed to be stable. If a bug is 

151 
reported and fix, we assume people who need the fix in a hurry will 

152 
get $current.zip$""") 

153 

346
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

154 
disc("""The next section assumes you 
340  155 
don't know much about Python. We cover all of the steps for three 
156 
common platforms, including how to verify that each one is complete. 

157 
While this may seem like a long list, everything takes 5 minutes if 

158 
you have the binaries at hand.""") 

159 

346
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

160 
heading3("Instructions for novices: Windows") 
340  161 

162 
restartList() 

337  163 

340  164 
list("""Get and install Python from http://www.python.org/. 
165 
Follow the links to 'Download' and get the latest official 

166 
version. Currently this is Python 1.5.2 in the file 'py152.exe'. 

167 
It will prompt you for a directory location, which by default is 

168 
$C:\Program Files\Python$. This works, but we recommend entering 

169 
$C:\Python15$. Python 1.6 will be out shortly and will adopt 

170 
C:\Python16 as its default; and quite often one wants to CD into the 

171 
Python directory from a command prompt, so a path without spaces saves 

172 
a lot of typing! After installing, you should be able to run the 

173 
'Python (command line)' option from the Start Menu.""") 

174 

175 
list("""If on Win9x, we recommend either copying python.exe to a 

176 
location on your path, or adding your Python directory to the path, so 

177 
that you can execute Python from any directory.""") 

178 

179 
list("""If you want a nice editing environment or might need to 

180 
access Microsoft applications, get the Pythonwin addon package from 

181 
the same page. Once this is installed, you can start Pythonwin from 

182 
the Start Menu and get a GUI application.""") 

337  183 

340  184 
disc("""The next step is optional and only necessary if you want to 
185 
include images in your reports; it can also be carried out later.""") 

186 

187 
list("Install the Python Imaging Library. (todo: make up a bundle that works)") 

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  190 

346
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

191 
list("""To verify, 
340  192 
start the command line Python and type "import Image", followed by 
193 
"import _imaging". If you see no error messages, all is well.""") 

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  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  201 

202 
list("""Open up a DOS prompt and CD to 

203 
"..\reportlab\pdfgen\test". On NT, enter "testpdfgen.py"; on 

204 
Win9x, enter "python testpdfgen.py". After a couple of seconds, 

205 
the script completes and the file testpdfgen.pdf should be ready for 

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") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

210 
todo("""Aaron? Robin?""") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

211 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

212 
heading3("Instructions for Python novices: Mac") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

213 
todo("Just?") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

214 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

215 
heading2("Getting Involved") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

216 
disc("""ReportLab is an Open Source project. Although we are 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

217 
a commercial company, we do not have gazillions of dollars 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

218 
of dotcom venture capital, and we make no income directly 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

219 
from the product. We therefore need help from the community 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

220 
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

221 
ways in which you can help:""") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

222 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

223 
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

224 
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

225 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

226 
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

227 
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

228 
chart or table class, why not contribute it?""") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

229 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

230 
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

231 
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

232 
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

233 
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

234 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

235 
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

236 
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

237 
just want to help out, let us know!""") 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

238 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

239 

179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

240 
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

241 
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

242 
with the subject "Subscribe" to 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

243 
$reportlabuserssubscribe@egroups.com$. You can also browse 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

244 
through the group's archives and contributions at 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

245 
$http://www.egroups.com/group/reportlabusers$. This list is 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

246 
the place to report bugs and get support. """) 
179378979ab7
Introduction is 'coherent'  if not exactly finished:)
andy_robinson
parents:
344
diff
changeset

247 