Restructured
authorrgbecker
Sat, 11 Aug 2001 14:35:52 +0000
changeset 1128 bc5ca3b9a13b
parent 1127 9670c15dad4e
child 1129 b2ba26ffca73
Restructured
docs/graphguide/ch1_intro.py
docs/graphguide/ch2_concepts.py
docs/graphguide/ch3_shapes.py
docs/graphguide/ch4_widgets.py
docs/graphguide/ch5_charts.py
docs/graphguide/gengraphguide.py
docs/userguide/app_demos.py
docs/userguide/ch1_intro.py
docs/userguide/ch2_graphics.py
docs/userguide/ch3_pdffeatures.py
docs/userguide/ch4_platypus_concepts.py
docs/userguide/ch5_paragraphs.py
docs/userguide/ch6_tables.py
docs/userguide/ch7_custom.py
docs/userguide/ch9_future.py
docs/userguide/genuserguide.py
--- a/docs/graphguide/ch1_intro.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/ch1_intro.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,12 +1,11 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
-#history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/ch1_intro.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/ch1_intro.py,v 1.8 2001/08/10 16:00:08 dinu_gherman Exp $
-
-from gengraphguide import *
+#history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch1_intro.py?cvsroot=reportlab
+#$Header: /tmp/reportlab/docs/graphguide/ch1_intro.py,v 1.9 2001/08/11 14:33:58 rgbecker Exp $
+from rl_doc_utils import *
 import reportlab
 
-title("Graphics Guide")
+title("User Guide")
 centred('ReportLab Version ' + reportlab.Version)
 
 nextTemplate("Normal")
@@ -17,101 +16,379 @@
 #
 ########################################################################
 
+
 heading1("Introduction")
 
+
 heading2("About this document")
-
-disc("""
-This document is intended to be a conversational introduction
-to the use of the ReportLab Graphics package.
-As this package is a subcomponent of the general ReportLab document
-toolkit some previous exposure to the content of the general "ReportLab
-User Guide" is not only highly recommended, but absolutely necessary.
-If you haven't read the general User Guide yet, this is the time to
-do so!
+disc("""This document is intended to be a conversational introduction
+to the use of the ReportLab packages.  Some previous programming experience
+is presumed and familiarity with the Python Programming language is
+recommended.  If you are new to Python, we tell you in the next section
+where to go for orientation.
 """)
 
-disc("""
-After working your way through this, you should be ready to
-begin writing programs to produce reports containing graphics elements
-like simple drawings and charts.
+disc("""After working your way throught this, you should be ready to begin
+writing programs to produce sophisticated reports.
 """)
 
-# Hack to force a new paragraph before the todo() :-(
-disc("")
+disc("""In this chapter, we will cover the groundwork:""")
+bullet("What is ReportLab all about, and why should I use it?")
+bullet("What is Python?")
+bullet("How do I get everything set up and running?")
 
 todo("""
-Be warned! This document is in a preliminary form.
+Be warned! This document is in a <em>very</em> preliminary form.
 We need your help to make sure it is complete and helpful.
 Please send any feedback to our user mailing list,
 reportlab-users@yahoogroups.com.
 """)
 
 
-heading2("Background")
+heading2("What is ReportLab?")
+disc("""ReportLab is a software library that lets you directly
+create documents in Adobe's Portabe Document Format (PDF) using
+the Python programming language. """)
+
+disc("""PDF is the global standard for electronic documents. It
+supports high-quality printing yet is totally portable across
+platforms, thanks to the freely available Acrobat Reader.  Any
+application which previously generated hard copy reports can
+benefit from making PDF documents instead; these can be archived,
+emailed, placed on the web, or printed out the old-fashioned way.
+However, the PDF file format is a complex
+indexed binary format which is impossible to type directly.
+The PDF format specification is more than 600 pages long and
+PDF files must provide precise byte offsets -- a single extra
+character placed anywhere in a valid PDF document can render it
+invalid.
+Until now, most of the world's PDF documents have been produced
+by Adobe's Acrobat tools, which act as a 'print driver'.
+""")
+
+disc("""The ReportLab library directly creates PDF based on
+your graphics commands.  There are no intervening steps.  Your applications
+can generate reports extremely fast - sometimes orders
+of magnitude faster than traditional report-writing
+tools.""")
 
 disc("""
-The ReportLab library is a general document toolkit aiming to help
-generate documents for reporting solutions.
-One important aspect of such applications is to present data with
-graphics like diagrams or charts.
-Ideally, these graphics could be used not only to generate PDF
-documents, but other output formats, bitmap or vector ones, as
-well.
-ReportLab is in the middle of adding such a Graphics package to
-its standard distribution.
-This document is both the "design document" and the "tutorial".
+By contrast, many other methods for generating PDF documents
+involve "pipelines" of several processes, which make the generation process
+slow, and very difficult to manage and maintain.
+""")
+
+disc("""In addition, because you are writing a program
+in a powerful general purpose language, there are no
+restrictions at all on where you get your data from,
+how you transform it, and the the kind of output
+you can create.  And you can reuse code across
+whole families of reports.""")
+
+disc("""The ReportLab library is expected to be useful
+in at least the following contexts:""")
+bullet("Dynamic PDF generation on the web")
+bullet("High-volume corporate reporting and database publishing")
+bullet("""An embeddable print engine for other applications, including
+a 'report language' so that users can customize their own reports. <i>
+This is particularly relevant to cross-platform apps which cannot
+rely on a consistent printing or previewing API on each operating
+system</i>.""")
+bullet("""A 'build system' for complex documents with charts, tables
+and text such as management accounts, statistical reports and
+scientific papers """)
+bullet("""Going from XML to PDF in one step!""")
+
+
+heading2("What is Python?")
+disc("""<para lindent=+36>
+<b>python</b>, (<i>Gr. Myth.</i> An enormous serpent that lurked in the cave of Mount Parnassus and was slain
+by Apollo) <b>1.</b> any of a genus of large, non-poisonous snakes of Asia, Africa and Australia that
+suffocate their prey to death. <b>2.</b> popularly, any large snake that crushes its prey. <b>3.</b> totally awesome,
+bitchin' very high level programming language (which in <i>our</i> exceedingly humble opinions
+(for what they are worth)
+whallops the snot out of all the other contenders (but your
+mileage may vary real soon now, as far as we know).</para>
+""")
+disc("""
+Python is an <i>interpreted, interactive, object-oriented</i> programming language. It is often compared to Tcl, Perl,
+Scheme or Java. 
+""")
+
+disc("""
+Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level
+dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to
+various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily written in C or C++.
+Python is also usable as an extension language for applications that need a programmable interface. 
+""")
+
+disc("""
+The Python implementation is portable: it runs on most brands of UNIX
+(including clones such as Linux), on Windows, DOS, OS/2, Mac, Amiga, DEC/VMS,
+IBM operating systems, VxWorks, PSOS, ... If
+your favorite system isn't listed here, it may still be supported, if there's a C
+programming language compiler for it. Ask around on
+comp.lang.python -- or just try compiling Python yourself. 
+""")
+
+disc("""
+Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>. 
+The ReportLab core modules share the same copyright with the name of the copyright holder
+modified.  Both packages use the "Berkeley Standard Distribution (BSD) style" free software copyright.
+""")
+
+
+heading2("Installation and Setup")
+
+disc("""
+Below we provide an abbreviated setup procedure for Python experts and a more
+verbose procedure for people who are new to Python.
 """)
 
 
-heading2("Requirements")
+heading3("Installation for experts")
+disc("""First of all, we'll give you the high-speed version for experienced
+Python developers:""")
+list("Install Python 1.5.1 or later")
+list("""If you want to produce compressed PDF files (recommended),
+check that zlib is installed.""")
+list("""If you want to work with bitmap images, install and
+test the Python Imaging Library""")
+list("""Unpack the reportlab package (reportlab.zip
+or reportlab.tgz) into a directory on your path""")
+list("""$cd$ to ^reportlab/pdfgen/test^ and execute $testpdfgen.py$,
+which will create a file 'testpdfgen.pdf'.""")
+disc(" ")
+disc("""If you have any problems, check the 'Detailed Instructions' section below.""")
+
+
+heading3("A note on available versions")
+disc("""The $reportlab$
+library can be found at $ftp.reportlab.com$ in the top-level directory.
+Each successive version is stored in both zip and tgz format, but the
+contents are identical.  Versions are numbered:  $ReportLab_0_85.zip$,
+$ReportLab_0_86.zip$ and so on.  The latest stable version is also
+available as just $reportlab.zip$ (or $reportlab.tgz$), which
+is actually a symbolic link to the latest numbered version.""")
+
+disc("""We also make nightly snapshots of our CVS 
+(version control) tree available.  In
+general, these are very stable because we have a comprehensive test
+suite that all developers can run at any time.
+New modules and functions within the overall package may be in a state
+of flux, but stable features can be assumed to be stable.  If a bug is
+reported and fixed, we assume people who need the fix in a hurry will
+get $current.zip$""")
+
+
+heading3("Instructions for novices: Windows")
+
+
+
+disc("""This section assumes you
+don't know much about Python.  We cover all of the steps for three
+common platforms, including how to verify that each one is complete.
+While this may seem like a long list, everything takes 5 minutes if
+you have the binaries at hand.""")
+
+
+restartList()
+
+list("""Get and install Python from $http://www.python.org/.$
+Follow the links to 'Download' and get the latest official
+version.  Currently this is Python 1.5.2 in the file $py152.exe$.
+It will prompt you for a directory location, which by default is
+$C:\Program Files\Python$. This works, but we recommend entering
+$C:\Python15$.  Python 1.6 will be out shortly and will adopt
+$C:\Python16$ as its default; and quite often one wants to change directory into the
+Python directory from a command prompt, so a path without spaces saves
+a lot of typing!  After installing, you should be able to run the
+'Python (command line)' option from the Start Menu.""")
+
+list("""If on Win9x, we recommend either copying python.exe to a
+location on your path, or adding your Python directory to the path, so
+that you can execute Python from any directory.""")
+
+list("""If you want a nice editing environment or might need to
+access Microsoft applications, get the Pythonwin add-on package from
+the same page.  Once this is installed, you can start Pythonwin from
+the Start Menu and get a GUI application.""")
+
+disc("""The next step is optional and only necessary if you want to
+include images in your reports; it can also be carried out later.""")
+
+list("Install the Python Imaging Library ($PIL$).  (todo:  make up a bundle that works)")
+
+list("Add the $DLL$s in $PIL$ to your $Python\DLLs$ directory")
+
+list("""To verify,
+start the Python interpreter (command line) and type $from PIL import Image$, followed by
+$import _imaging$.  If you see no error messages, all is well.""")
+
+disc("""Now you are ready to install reportlab itself.""")
+
+list("""Unzip the archive straight into
+your Python directory; it creates a subdirectory named
+$reportlab$.  You should now be able to go to a Python
+command line interpreter and type $import reportlab$ without getting
+an error message.""")
+
+list("""Open up a $MS-DOS$ command prompt and CD to
+"..\\reportlab\\pdfgen\\test".  On NT, enter "testpdfgen.py"; on
+Win9x, enter "python testpdfgen.py".  After a couple of seconds,
+the script completes and the file testpdfgen.pdf should be ready for
+viewing.  If PIL is installed, there should be a "Python Powered"
+image on the last page.  You're done!""")
 
 disc("""
-The Graphics library should support the creation of custom
-graphical applications containing charts, diagrams, drawings, plans,
-etc. in various domains like business, finance, publishing, engineering
-and research.
-It is especially intended as a foundation for a chart library that
-happens to be the first major subpackage for a real-world client
-in the financial industry.
+[Note: the "couple of seconds" delay is mainly due to
+compilation of the python scripts in the ReportLab package.
+The next time the ReportLab modules are used the execution
+will be noticably faster because the $pyc$ compiled python
+files will be used in place of the $py$ python source files.]""")
+
+
+heading3("Instructions for Python novices: Unix")
+
+restartList()
+list("""First you need to decide if you want to install the Python sources
+and compile these yourself or if you only want to install a binary package
+for one of the many variants of Linux or Unix. If you want to compile from
+source download the latest
+sources from http://www.python.org (currently the latest source is
+in http://www.python.org/ftp/python/src/py152.tgz). If you wish to use
+binaries
+get the latest RPM or DEB or whatever package and install (or get your
+super user (system administrator) to do the work).""")
+
+list("""If you are building Python yourself, unpack the sources into a temporary directory using a tar command
+e.g. $tar xzvf py152.tgz$; this will create a subdirectory called Python-1.5.2
+(or whatever) cd into this directory. Then read the file $README$! It contains the 
+latest information on how to install Python.""")
+
+list("""If your system has the gzip libz library installed
+check that the zlib extension will be installed by default by editing
+the file Modules/Setup.in and ensuring that (near line 405) the line
+containing zlib zlibmodule.c is uncommented i.e. has no hash '#' character at the
+beginning. You also need to decide if you will be installing in the default location
+(/usr/local/) or in some other place.
+The zlib module is needed if you want compressed PDF and for some images.""")
+
+list("""Invoke the command $./configure --prefix=/usr/local$ this should configure
+the source directory for building. Then you can build the binaries with
+a $make$ command. If your $make$ command is not up to it try building
+with $make MAKE=make$. If all goes well install with $make install$.""")
+
+list("""If all has gone well and python is in the execution search path
+you should now be able to type $python$ and see a <b>Python</b> prompt.
+Once you can do that it's time to try and install ReportLab.
+First get the latest reportlab.tgz.
+If ReportLab is to be available to all then the reportlab archive should be unpacked in
+the lib/site-python directory (typically /usr/local/lib/site-python) if neccessary by
+a superuser.
+Otherwise unpack in a directory of your choice and arrange for that directory to be on your
+$PYTHONPATH$ variable.
+""")
+eg("""
+#put something like this in your
+#shell rcfile
+PYTHONPATH=$HOME/mypythonpackages
+export PYTHONPATH
+""",after=0.1)
+
+list("""You should now be able to run python and execute the python statement
+""",doBullet=0)
+eg("""import reportlab""",after=0.1)
+list("""If you want to use images you should certainly consider
+getting &amp; installing the Python Imaging Library from
+<font color=blue>http://www.pythonware.com/products/pil</font>.
 """)
 
-disc("The general graphics package should help with the following activities: ")
 
-bullet("creating reusable shapes collections")
-bullet("supporting paths, clipping and coordinate transformations")
-bullet("writing output to PDF, Postscript, bitmap and vector formats")
-bullet("using a consistent font model (Type 1)")
-bullet("providing identical metrics on all platforms")
-bullet("""using a framework for creating, documenting and reusing graphical "widgets" """)
-
-disc("""Within the charting domain the target features are:""")
-
-bullet("Horizontal/vertical bar charts based on category/value axes.")
-bullet("Horizontal/vertical line charts based on category/value axes.")
-bullet("""Special time series charts based on genuine x/y values.""")
-bullet("Simple pie charts.")
-bullet("""Compounding - one can define 'multiples' placing several charts on one 
-       drawing, or arbitrary decorations around the chart. This technique 
-       also allows easy overlaying of lines on bars, or of different axes on 
-       the right and left side of a plot.""")
-bullet("""'Plug-In Architecture' - with training (and possibly supported by
-       additional tools), you can write a new chart type based on an existing
-       one but only changing/adding the features you need to.""")
-bullet("Control over drawing size, plot rectangle size and position within drawing.")
-bullet("""Control over width, dash style, line cap/join style and
-       color for all lines.""")
-bullet("""Choice of any solid color (or gray level, or transparent) for any
-       enclosed area. Fill patterns may be added later. The public library
-       will be limited to RGB and possibly plain CMYK colors but we can
-       cleanly layer custom Postscript requirements on top.""")
-bullet("""Control over font name (any Type 1 font on the system) and size, plus
-       the ability to scale, stretch and rotate the text
-       right, left and centre alignment of label text strings with correct
-       metrics.""")
+heading3("Instructions for Python novices: Mac")
+#this stuff was provided by humbert@ls12.cs.uni-dortmund.de
+disc("""
+First install Python,
+the latest stable release is 1.52, but it is also possible to run Reportlab with 1.6a2
+and probably with 1.6b1/b2.
+You get the software (ready to run) at font color=blue>http://www.python.org</font>
+When this is successful done you should have the following folder structure.
+""")
+image('Python_1.6a2.gif', 3*inch, 3*inch )
+disc("""
+Now you can put Extensions in the Extensions-Folder;
+which is where you should unpack the <b>reportlab.zip</b> with your favorite unpack-utility.
+You'll get a subfolder named <b>reportlab</b>.
+""")
 
 disc("""
-The charting requirements are based on a commercial sponsor who
-needs to effeciently create batches of charts with precise control
-over layout.
+After this step, you have to tell the PythonInterpreter, where to look for extensions.
+Start EditPythonPrefs (by double-clicking the icon).
+""")
+image('Python_1.6a2_HINT.gif',3*inch,3*inch)
+disc("""
+You should get the following modal dialog.
+This is the point, where your special data goes in.
+Reportlab is on the path in Extensions. So all you have to do is add
+the last line 
+<b>$(PYTHON):Extensions</b>. 
+""")
+image('Edit_Prefs.gif',3*inch,3*inch)
+disc("""
+Now you should test one or more of the demo scripts include with with the sources; eg
+<b>reportlab:demos:pythonpoint:pythonpoint.py</b>.
+One Problem on the Mac is solved gracefully in Python:
+if you want a script that takes some arguments, hold down the alt or option-key,
+while activating Python.
 """)
+
+
+heading2("Getting Involved")
+disc("""ReportLab is an Open Source project.  Although we are
+a commercial company we provide the core PDF generation
+sources freely, even for commercial purposes, and we make no income directly
+from these modules.  We also welcome help from the community
+as much as any other Open Source project.  There are many
+ways in which you can help:""")
+
+bullet("""General feedback on the core API. Does it work for you?
+Are there any rough edges?  Does anything feel clunky and awkward?""")
+
+bullet("""New objects to put in reports, or useful utilities for the library.
+We have an open standard for report objects, so if you have written a nice
+chart or table class, why not contribute it?""")
+
+bullet("""Demonstrations and Case Studies: If you have produced some nice
+output, send it to us (with or without scripts).  If ReportLab solved a
+problem for you at work, write a little 'case study' and send it in.
+And if your web site uses our tools to make reports, let us link to it.
+We will be happy to display your work (and credit it with your name
+and company) on our site!""")
+
+bullet("""Working on the core code:  we have a long list of things
+to refine or to implement.  If you are missing some features or
+just want to help out, let us know!""")
+
+disc("""
+The first step for anyone wanting to learn more or
+get involved is to join the mailing list.
+Just send an email with the subject "Subscribe" to
+$reportlab-users-subscribe@yahoogroups.com$.
+You can also browse through the group's archives and
+contributions at $http://www.yahoogroups.com/group/reportlab-users$.
+This list is the place to report bugs and get support.
+""")
+
+
+heading2("Site Configuration")
+disc("""There are a number of options which most likely need to be configured globally for a site.
+The python script module $reportlab/rl_config.py$ may be edited to change the values of several
+important sitewide properties.""")
+bullet("""shapeChecking: set this to zero to turn off a lot of error checking in the graphis modules""") 
+bullet("""defaultEncoding: set this to WinAnsiEncoding or MacRomanEncoding.""")
+bullet("""defaultPageSize: set this to one of the values defined in reportlab/lib/pagesizes.py; as delivered
+it is set to pagesizes.A4; other values are pagesizes.letter etc.""")
+bullet("""defaultImageCaching: set to zero to inhibit the creation of .a85 files on your
+hard-drive. The default is to create these preprocessed PDF compatible image files for faster loading""")
+bullet("""T1SearchPathPath: this is a python list of strings representing directories that
+may be queried for information on Type 1 fonts""")
--- a/docs/graphguide/ch2_concepts.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/ch2_concepts.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,9 +1,8 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/ch2_graphics.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/ch2_concepts.py,v 1.2 2001/08/10 16:00:08 dinu_gherman Exp $
-
-from gengraphguide import *
+#$Header: /tmp/reportlab/docs/graphguide/ch2_concepts.py,v 1.3 2001/08/11 14:33:58 rgbecker Exp $
+from rl_doc_utils import *
 
 heading1("General Concepts")
 
--- a/docs/graphguide/ch3_shapes.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/ch3_shapes.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,10 +1,9 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/ch2_graphics.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/ch3_shapes.py,v 1.2 2001/08/10 16:00:08 dinu_gherman Exp $
+#$Header: /tmp/reportlab/docs/graphguide/ch3_shapes.py,v 1.3 2001/08/11 14:33:58 rgbecker Exp $
 
-from gengraphguide import *
-
+from rl_doc_utils import *
 from reportlab.graphics.shapes import *
 from reportlab.graphics.widgets import signsandsymbols
 
--- a/docs/graphguide/ch4_widgets.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/ch4_widgets.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,10 +1,9 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/ch2_graphics.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/ch4_widgets.py,v 1.2 2001/08/10 16:00:08 dinu_gherman Exp $
+#$Header: /tmp/reportlab/docs/graphguide/ch4_widgets.py,v 1.3 2001/08/11 14:33:58 rgbecker Exp $
 
-from gengraphguide import *
-
+from rl_doc_utils import *
 from reportlab.graphics.shapes import *
 from reportlab.graphics.widgets import signsandsymbols
 
--- a/docs/graphguide/ch5_charts.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/ch5_charts.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,10 +1,9 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/ch2_graphics.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/ch5_charts.py,v 1.4 2001/08/10 16:00:08 dinu_gherman Exp $
+#$Header: /tmp/reportlab/docs/graphguide/ch5_charts.py,v 1.5 2001/08/11 14:33:58 rgbecker Exp $
 
-from gengraphguide import *
-
+from rl_doc_utils import *
 from reportlab.graphics.shapes import *
 
 heading1("Charts")
--- a/docs/graphguide/gengraphguide.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/graphguide/gengraphguide.py	Sat Aug 11 14:35:52 2001 +0000
@@ -2,447 +2,40 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/graphguide/gengraphguide.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/graphguide/gengraphguide.py,v 1.5 2001/08/08 18:52:06 rgbecker Exp $
-__version__=''' $Id: gengraphguide.py,v 1.5 2001/08/08 18:52:06 rgbecker Exp $ '''
-
-
+#$Header: /tmp/reportlab/docs/graphguide/gengraphguide.py,v 1.6 2001/08/11 14:33:58 rgbecker Exp $
+__version__=''' $Id: gengraphguide.py,v 1.6 2001/08/11 14:33:58 rgbecker Exp $ '''
 __doc__ = """
 This module contains the script for building the graphics guide.
 """
-
-import os, sys, glob
-import string
-import StringIO
-
+import sys, os
 sys.path.insert(0,os.path.join(os.path.dirname(sys.argv[0]),'..','tools'))
-from rltemplate import RLDocTemplate
-from stylesheet import getStyleSheet
-styleSheet = getStyleSheet()
-
-#from reportlab.platypus.doctemplate import SimpleDocTemplate
-from reportlab.lib.units import inch
-from reportlab.lib.pagesizes import letter, A4, A5, A3  # latter two for testing
-from reportlab.rl_config import defaultPageSize
-from reportlab.platypus import Paragraph, Spacer, Preformatted,\
-            PageBreak, CondPageBreak, Flowable, Table, TableStyle, \
-            NextPageTemplate, KeepTogether, Image, XPreformatted
-from reportlab.lib.styles import ParagraphStyle
-from reportlab.lib import colors
-from reportlab.lib.sequencer import getSequencer
-
-import examples
-import platdemos
-
-appmode=0
-
-
-from t_parse import Template
-QFcodetemplate = Template("X$X$", "X")
-QFreptemplate = Template("X^X^", "X")
-codesubst = "%s<font name=Courier>%s</font>"
-QFsubst = "%s<font name=Courier><i>%s</i></font>"
-    
-
-def quickfix(text):
-    """inside text find any subsequence of form $subsequence$.
-       Format the subsequence as code.  If similarly if text contains ^arg^
-       format the arg as replaceable.  The escape sequence for literal
-       $ is $\\$ (^ is ^\\^.
-    """
-    from string import join
-    for (template,subst) in [(QFcodetemplate, codesubst), (QFreptemplate, QFsubst)]:
-        fragment = text
-        parts = []
-        try:
-            while fragment:
-                try:
-                    (matches, index) = template.PARSE(fragment)
-                except: raise ValueError
-                else:
-                    [prefix, code] = matches
-                    if code == "\\":
-                        part = fragment[:index]
-                    else:
-                        part = subst % (prefix, code)
-                    parts.append(part)
-                    fragment = fragment[index:]
-        except ValueError:
-            parts.append(fragment)
-        text = join(parts, "")
-    return text
-#print quickfix("$testing$ testing $one$ ^two^ $three(^four^)$")
-
-
-
-H1 = styleSheet['Heading1']
-H2 = styleSheet['Heading2']
-H3 = styleSheet['Heading3']
-H4 = styleSheet['Heading4']
-B = styleSheet['BodyText']
-BU = styleSheet['Bullet']
-Comment = styleSheet['Comment']
-Centred = styleSheet['Centred']
-Caption = styleSheet['Caption']
-
-#set up numbering
-seq = getSequencer()
-seq.setFormat('Chapter','1')
-seq.setFormat('Section','1')
-seq.setFormat('Appendix','A')
-seq.setFormat('Figure', '1')
-seq.chain('Chapter','Section')
-seq.chain('Chapter','Figure')
-
-lessonnamestyle = H2
-discussiontextstyle = B
-exampletextstyle = styleSheet['Code']
-# size for every example
-examplefunctionxinches = 5.5
-examplefunctionyinches = 3
-examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)
-
-
-# for testing
-def NOP(*x,**y):
-    return None
-
-def CPage(inches):
-    getStory().append(CondPageBreak(inches*inch))
-    
-def newPage():
-    getStory().append(PageBreak())
+from rl_doc_utils import *
+def run(pagesize):
+	doc = RLDocTemplate('graphguide.pdf',pagesize = pagesize)
+	import ch1_intro
+	import ch2_concepts
+	import ch3_shapes
+	import ch4_widgets
+	import ch5_charts
 
-def nextTemplate(templName):
-    f = NextPageTemplate(templName)
-    getStory().append(f)
-    
-def disc(text, klass=Paragraph, style=discussiontextstyle):
-    text = quickfix(text)
-    P = klass(text, style)
-    getStory().append(P)
-
-def restartList():
-    getSequencer().reset('list1')
-
-def list(text, doBullet=1):
-    text=quickfix(text)
-    if doBullet:
-        text='<bullet><seq id="list1"/>.</bullet>'+text
-    P = Paragraph(text, BU)
-    getStory().append(P)
-    
-def bullet(text):
-    text='<bullet><font name="Symbol">'+chr(183)+'</font></bullet>' + quickfix(text)
-    P = Paragraph(text, BU)
-    getStory().append(P)
-    
-def eg(text,before=0.1,after=0):
-    space(before)
-    disc(text, klass=Preformatted, style=exampletextstyle)
-    space(after)
-
-def space(inches=1./6):
-	if inches: getStory().append(Spacer(0,inches*inch))
-
-def EmbeddedCode(code,name='t'):
-    eg(code)
-    disc("produces")
-    exec code+("\ngetStory().append(%s)\n"%name)
-
-def startKeep():
-    return len(getStory())
-
-def endKeep(s):
-    S = getStory()
-    k = KeepTogether(S[s:])
-    S[s:] = [k]
- 
-def title(text):
-    """Use this for the document title only"""
-    disc(text,style=styleSheet['Title'])
-
-#AR 3/7/2000 - defining three new levels of headings; code
-#should be swapped over to using them.
-
-def heading1(text):
-    """Use this for chapters.  Lessons within a big chapter
-    should now use heading2 instead.  Chapters get numbered."""
-    getStory().append(PageBreak())
-    p = Paragraph('Chapter <seq id="Chapter"/> ' + quickfix(text), H1)
-    getStory().append(p)
-
-def Appendix1(text,):
-    global appmode
-    getStory().append(PageBreak())
-    if not appmode:
-        seq.setFormat('Chapter','A')
-        seq.reset('Chapter')
-        appmode = 1
-    p = Paragraph('Appendix <seq id="Chapter"/> ' + quickfix(text), H1)
-    getStory().append(p)
-
-def heading2(text):
-    """Used to be 'lesson'"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph('<seq template="%(Chapter)s.%(Section+)s "/>' + quickfix(text), H2)
-    getStory().append(p)
-
-def heading3(text):
-    """Used to be most of the plain old 'head' sections"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph(quickfix(text), H3)
-    getStory().append(p)
-
-def image(path, width=None, height=None ):
-	s = startKeep()
-	space(.2)
-	getStory().append(Image(os.path.join(os.path.dirname(sys.argv[0]),'..','images',path),width,height))
-	space(.2)
-	endKeep(s)
- 
-def heading4(text):
-    """Used to be most of the plain old 'head' sections"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph(quickfix(text), H4)
-    getStory().append(p)
-    
-def todo(text):
-    """Used for notes to ourselves"""
-    getStory().append(Paragraph(quickfix(text), Comment))
-
-def centred(text):
-    getStory().append(Paragraph(quickfix(text), Centred))
-                      
-def caption(text):
-    getStory().append(Paragraph(quickfix(text), Caption))
+	story = getStory()
+	print 'Built story contains %d flowables...' % len(story)
+	doc.build(story)
+	print 'Saved graphguide.pdf'
 
-class Illustration(platdemos.Figure):
-    """The examples are all presented as functions which do
-    something to a canvas, with a constant height and width
-    used.  This puts them inside a figure box with a caption."""
-    
-    def __init__(self, operation, caption):
-        stdwidth, stdheight = examplefunctiondisplaysizes
-        #platdemos.Figure.__init__(self, stdwidth * 0.75, stdheight * 0.75)
-        platdemos.Figure.__init__(self, stdwidth, stdheight,
-                    'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption))
-        self.operation = operation
-        
-    def drawFigure(self):
-        #shrink it a little...
-        #self.canv.scale(0.75, 0.75)
-        self.operation(self.canv)
-
-
-def illust(operation, caption):
-    i = Illustration(operation, caption)
-    getStory().append(i)
-
-
-class GraphicsDrawing(Illustration):
-    """Lets you include reportlab/graphics drawings seamlessly,
-    with the right numbering."""
-    def __init__(self, drawing, caption):
-        platdemos.Figure.__init__(self,
-                                  drawing.width,
-                                  drawing.height,
-                    'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                                  )
-        self.drawing = drawing
-        
-    def drawFigure(self):
-        d = self.drawing
-        d.wrap(d.width, d.height)
-        d.drawOn(self.canv, 0, 0)
-        
-def draw(drawing, caption):
-    d = GraphicsDrawing(drawing, caption)
-    getStory().append(d)
-        
-class ParaBox(platdemos.Figure):
-    """Illustrates paragraph examples, with style attributes on the left"""
-    descrStyle = ParagraphStyle('description',
-                                fontName='Courier',
-                                fontSize=8,
-                                leading=9.6)
-
-    def __init__(self, text, style, caption):
-        platdemos.Figure.__init__(self, 0, 0, caption)
-        self.text = text
-        self.style = style
-        self.para = Paragraph(text, style)
-
-        styleText = self.getStyleText(style)
-        self.pre = Preformatted(styleText, self.descrStyle)
-
-    def wrap(self, availWidth, availHeight):
-        """Left 30% is for attributes, right 50% for sample,
-        10% gutter each side."""
-        self.x0 = availWidth * 0.05  #left of box
-        self.x1 = availWidth * 0.1   #left of descriptive text
-        self.x2 = availWidth * 0.5   #left of para itself
-        self.x3 = availWidth * 0.9   #right of para itself
-        self.x4 = availWidth * 0.95  #right of box
-        self.width = self.x4 - self.x0
-        self.dx = 0.5 * (availWidth - self.width)
-
-        paw, self.pah = self.para.wrap(self.x3 - self.x2, availHeight)
-        self.pah = self.pah + self.style.spaceBefore + self.style.spaceAfter
-        prw, self.prh = self.pre.wrap(self.x2 - self.x1, availHeight)
-        self.figureHeight = max(self.prh, self.pah) * 10.0/9.0
-        return platdemos.Figure.wrap(self, availWidth, availHeight)
-
-    def getStyleText(self, style):
-        """Converts style to preformatted block of text"""
-        lines = []
-        for (key, value) in style.__dict__.items():
-            lines.append('%s = %s' % (key, value))
-        lines.sort()
-        return string.join(lines, '\n')        
-        
-    def drawFigure(self):
-        
-        #now we fill in the bounding box and before/after boxes       
-        self.canv.saveState()
-        self.canv.setFillGray(0.95)
-        self.canv.setDash(1,3)
-        self.canv.rect(self.x2 - self.x0,
-                       self.figureHeight * 0.95 - self.pah,
-                       self.x3-self.x2, self.para.height,
-                       fill=1,stroke=1)
-        
-        self.canv.setFillGray(0.90)
-        self.canv.rect(self.x2 - self.x0, #spaceBefore
-                       self.figureHeight * 0.95 - self.pah + self.para.height,
-                       self.x3-self.x2, self.style.spaceBefore,
-                       fill=1,stroke=1)
-        
-        self.canv.rect(self.x2 - self.x0, #spaceBefore
-                       self.figureHeight * 0.95 - self.pah - self.style.spaceAfter,
-                       self.x3-self.x2, self.style.spaceAfter,
-                       fill=1,stroke=1)
+	# remove *.pyc files
+	pat = os.path.join(os.path.dirname(sys.argv[0]), '*.pyc')
+	for file in glob.glob(pat):
+		os.remove(file)
 
-        self.canv.restoreState()
-        #self.canv.setFillColor(colors.yellow)
-        self.para.drawOn(self.canv, self.x2 - self.x0,
-                         self.figureHeight * 0.95 - self.pah)
-        self.pre.drawOn(self.canv, self.x1 - self.x0,
-                         self.figureHeight * 0.95 - self.prh)
-        
-        
-    def getStyleText(self, style):
-        """Converts style to preformatted block of text"""
-        lines = []
-        for (key, value) in style.__dict__.items():
-            if key not in ('name','parent'):
-                lines.append('%s = %s' % (key, value))
-        return string.join(lines, '\n')
-
-
-class ParaBox2(platdemos.Figure):
-    """Illustrates a paragraph side-by-side with the raw
-    text, to show how the XML works."""
-    def __init__(self, text, caption):
-        platdemos.Figure.__init__(self, 0, 0, caption)
-        descrStyle = ParagraphStyle('description',
-                                fontName='Courier',
-                                fontSize=8,
-                                leading=9.6)
-        textStyle = B
-        self.text = text
-        self.left = Paragraph('<![CDATA[' + text + ']]>', descrStyle)
-        self.right = Paragraph(text, B)
-        
-
-    def wrap(self, availWidth, availHeight):
-        self.width = availWidth * 0.9
-        colWidth = 0.4 * self.width
-        lw, self.lh = self.left.wrap(colWidth, availHeight)
-        rw, self.rh = self.right.wrap(colWidth, availHeight)
-        self.figureHeight = max(self.lh, self.rh) * 10.0/9.0
-        return platdemos.Figure.wrap(self, availWidth, availHeight)
-
-    def drawFigure(self):
-        self.left.drawOn(self.canv,
-                         self.width * 0.05,
-                         self.figureHeight * 0.95 - self.lh
-                         ) 
-        self.right.drawOn(self.canv,
-                         self.width * 0.55,
-                         self.figureHeight * 0.95 - self.rh
-                         ) 
-
-def parabox(text, style, caption):
-    p = ParaBox(text, style,
-                'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                )
-    getStory().append(p)
-    
-def parabox2(text, caption):
-    p = ParaBox2(text, 
-                'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                )
-    getStory().append(p)
-
-def pencilnote():
-    getStory().append(examples.NoteAnnotation())
-    
-
-from reportlab.lib.colors import tan, green
-def handnote(xoffset=0, size=None, fillcolor=tan, strokecolor=green):
-    getStory().append(examples.HandAnnotation(xoffset,size,fillcolor,strokecolor))
-    
-        
-#make a singleton, created when requested rather
-#than each time a chapter imports it.
-_story = None
-def getStory():
-    global _story
-    if _story is None:
-        _story = []
-    return _story
-
-
-def run(pagesize):
-    
-    doc = RLDocTemplate('graphguide.pdf',pagesize = pagesize)
-
-    #this builds the story    
-    #resetStory()
-
-    import ch1_intro
-    import ch2_concepts
-    import ch3_shapes
-    import ch4_widgets
-    import ch5_charts
-
-    # I don't know WHAT is going on here.
-    # the submodules all do 'import *',
-    # and the story they have access to
-    # contains it all; but the one defined
-    # in this module seems to be empty.
-    #if I just call getStory, it has no
-    #items!
-    
-    story = ch5_charts.getStory()
-    print 'Built story contains %d flowables...' % len(story)
-    doc.build(story)
-    print 'Saved graphguide.pdf'
-
-    # remove *.pyc files
-    pat = os.path.join(os.path.dirname(sys.argv[0]), '*.pyc')
-    for file in glob.glob(pat):
-        os.remove(file)
-
-        
 if __name__=="__main__":
-    if len(sys.argv) > 1:
-        try:
-            (w, h) = eval(sys.argv[1])
-        except:
-            print 'Expected page size in argument 1', sys.argv[1]
-            raise
-        print 'set page size to',sys.argv[1]
-    else:
-        (w, h) = defaultPageSize
-    run((w, h))
+	if len(sys.argv) > 1:
+		try:
+			(w, h) = eval(sys.argv[1])
+		except:
+			print 'Expected page size in argument 1', sys.argv[1]
+			raise
+		print 'set page size to',sys.argv[1]
+	else:
+		(w, h) = defaultPageSize
+	run((w, h))
--- a/docs/userguide/app_demos.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/app_demos.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/app_demos.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/app_demos.py,v 1.7 2000/10/25 08:57:45 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/app_demos.py,v 1.8 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 Appendix1("ReportLab Demos")
 disc("""In the subdirectories of $reportlab/demos$ there are a number of working examples showing
--- a/docs/userguide/ch1_intro.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch1_intro.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch1_intro.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch1_intro.py,v 1.13 2001/03/30 10:24:21 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch1_intro.py,v 1.14 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 import reportlab
 
 title("User Guide")
--- a/docs/userguide/ch2_graphics.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch2_graphics.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch2_graphics.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch2_graphics.py,v 1.15 2001/08/03 10:23:33 dinu_gherman Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch2_graphics.py,v 1.16 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 heading1("Graphics and Text with $pdfgen$")
 
--- a/docs/userguide/ch3_pdffeatures.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch3_pdffeatures.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch3_pdffeatures.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch3_pdffeatures.py,v 1.7 2000/10/25 08:57:45 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch3_pdffeatures.py,v 1.8 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 
 heading1("Exposing PDF Special Capabilities")
--- a/docs/userguide/ch4_platypus_concepts.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch4_platypus_concepts.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch4_platypus_concepts.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch4_platypus_concepts.py,v 1.10 2001/03/07 18:57:11 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch4_platypus_concepts.py,v 1.11 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 #####################################################################################################3
 
--- a/docs/userguide/ch5_paragraphs.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch5_paragraphs.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch5_paragraphs.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch5_paragraphs.py,v 1.8 2001/02/09 11:52:27 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch5_paragraphs.py,v 1.9 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 #begin chapter oon paragraphs
 heading1("Paragraphs")
--- a/docs/userguide/ch6_tables.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch6_tables.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch6_tables.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch6_tables.py,v 1.17 2001/03/21 14:12:02 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch6_tables.py,v 1.18 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 from reportlab.platypus import Image
 
 heading1("Tables and TableStyles")
--- a/docs/userguide/ch7_custom.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch7_custom.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,8 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch7_custom.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch7_custom.py,v 1.7 2001/03/21 14:12:02 rgbecker Exp $
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch7_custom.py,v 1.8 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 heading1("Writing your own $Flowable$ Objects")
 disc("""
--- a/docs/userguide/ch9_future.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/ch9_future.py	Sat Aug 11 14:35:52 2001 +0000
@@ -1,9 +1,8 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch9_future.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/ch9_future.py,v 1.3 2001/04/17 06:39:10 andy_robinson Exp $
-
-from genuserguide import *
+#$Header: /tmp/reportlab/docs/userguide/ch9_future.py,v 1.4 2001/08/11 14:35:52 rgbecker Exp $
+from rl_doc_utils import *
 
 heading1("Future Directions")
 
@@ -34,4 +33,4 @@
 look to $http://www.reportlab.com$ for the latest mailing list and
 contact information.""")
 
-# this comment is a trivial test of SF checkin rights - delete it some time!  AR 2001-04-17
\ No newline at end of file
+# this comment is a trivial test of SF checkin rights - delete it some time!  AR 2001-04-17
--- a/docs/userguide/genuserguide.py	Sat Aug 11 14:33:13 2001 +0000
+++ b/docs/userguide/genuserguide.py	Sat Aug 11 14:35:52 2001 +0000
@@ -2,444 +2,54 @@
 #copyright ReportLab Inc. 2001
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/genuserguide.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/docs/userguide/genuserguide.py,v 1.47 2001/08/08 18:52:06 rgbecker Exp $
+#$Header: /tmp/reportlab/docs/userguide/genuserguide.py,v 1.48 2001/08/11 14:35:52 rgbecker Exp $
 
-__version__=''' $Id: genuserguide.py,v 1.47 2001/08/08 18:52:06 rgbecker Exp $ '''
+__version__=''' $Id: genuserguide.py,v 1.48 2001/08/11 14:35:52 rgbecker Exp $ '''
 
 __doc__ = """
 This module contains the script for building the user guide.
 """
 
-import os, sys, string
-
+import os, sys
 sys.path.insert(0,os.path.join(os.path.dirname(sys.argv[0]),'..','tools'))
-from rltemplate import RLDocTemplate
-from stylesheet import getStyleSheet
-styleSheet = getStyleSheet()
-
-#from reportlab.platypus.doctemplate import SimpleDocTemplate
-from reportlab.lib.units import inch
-from reportlab.lib.pagesizes import letter, A4, A5, A3  # latter two for testing
-from reportlab.rl_config import defaultPageSize
-from reportlab.platypus import Paragraph, Spacer, Preformatted,\
-            PageBreak, CondPageBreak, Flowable, Table, TableStyle, \
-            NextPageTemplate, KeepTogether, Image, XPreformatted
-from reportlab.lib.styles import ParagraphStyle
-from reportlab.lib import colors
-from reportlab.lib.sequencer import getSequencer
-import examples
-import platdemos
-import StringIO
-appmode=0
-
-from t_parse import Template
-QFcodetemplate = Template("X$X$", "X")
-QFreptemplate = Template("X^X^", "X")
-codesubst = "%s<font name=Courier>%s</font>"
-QFsubst = "%s<font name=Courier><i>%s</i></font>"
-    
-
-def quickfix(text):
-    """inside text find any subsequence of form $subsequence$.
-       Format the subsequence as code.  If similarly if text contains ^arg^
-       format the arg as replaceable.  The escape sequence for literal
-       $ is $\\$ (^ is ^\\^.
-    """
-    from string import join
-    for (template,subst) in [(QFcodetemplate, codesubst), (QFreptemplate, QFsubst)]:
-        fragment = text
-        parts = []
-        try:
-            while fragment:
-                try:
-                    (matches, index) = template.PARSE(fragment)
-                except: raise ValueError
-                else:
-                    [prefix, code] = matches
-                    if code == "\\":
-                        part = fragment[:index]
-                    else:
-                        part = subst % (prefix, code)
-                    parts.append(part)
-                    fragment = fragment[index:]
-        except ValueError:
-            parts.append(fragment)
-        text = join(parts, "")
-    return text
-#print quickfix("$testing$ testing $one$ ^two^ $three(^four^)$")
-
-
-
-H1 = styleSheet['Heading1']
-H2 = styleSheet['Heading2']
-H3 = styleSheet['Heading3']
-H4 = styleSheet['Heading4']
-B = styleSheet['BodyText']
-BU = styleSheet['Bullet']
-Comment = styleSheet['Comment']
-Centred = styleSheet['Centred']
-Caption = styleSheet['Caption']
-
-#set up numbering
-seq = getSequencer()
-seq.setFormat('Chapter','1')
-seq.setFormat('Section','1')
-seq.setFormat('Appendix','A')
-seq.setFormat('Figure', '1')
-seq.chain('Chapter','Section')
-seq.chain('Chapter','Figure')
-
-
-lessonnamestyle = H2
-discussiontextstyle = B
-exampletextstyle = styleSheet['Code']
-# size for every example
-examplefunctionxinches = 5.5
-examplefunctionyinches = 3
-examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)
-
-# for testing
-def NOP(*x,**y):
-    return None
-
-def CPage(inches):
-    getStory().append(CondPageBreak(inches*inch))
-    
-def newPage():
-    getStory().append(PageBreak())
-
-def nextTemplate(templName):
-    f = NextPageTemplate(templName)
-    getStory().append(f)
-    
-def disc(text, klass=Paragraph, style=discussiontextstyle):
-    text = quickfix(text)
-    P = klass(text, style)
-    getStory().append(P)
-
-def restartList():
-    getSequencer().reset('list1')
-
-def list(text, doBullet=1):
-    text=quickfix(text)
-    if doBullet:
-        text='<bullet><seq id="list1"/>.</bullet>'+text
-    P = Paragraph(text, BU)
-    getStory().append(P)
-    
-def bullet(text):
-    text='<bullet><font name="Symbol">'+chr(183)+'</font></bullet>' + quickfix(text)
-    P = Paragraph(text, BU)
-    getStory().append(P)
-    
-def eg(text,before=0.1,after=0):
-    space(before)
-    disc(text, klass=Preformatted, style=exampletextstyle)
-    space(after)
-
-def space(inches=1./6):
-	if inches: getStory().append(Spacer(0,inches*inch))
-
-def EmbeddedCode(code,name='t'):
-    eg(code)
-    disc("produces")
-    exec code+("\ngetStory().append(%s)\n"%name)
-
-def startKeep():
-    return len(getStory())
-
-def endKeep(s):
-    S = getStory()
-    k = KeepTogether(S[s:])
-    S[s:] = [k]
- 
-def title(text):
-    """Use this for the document title only"""
-    disc(text,style=styleSheet['Title'])
-
-#AR 3/7/2000 - defining three new levels of headings; code
-#should be swapped over to using them.
-
-def heading1(text):
-    """Use this for chapters.  Lessons within a big chapter
-    should now use heading2 instead.  Chapters get numbered."""
-    getStory().append(PageBreak())
-    p = Paragraph('Chapter <seq id="Chapter"/> ' + quickfix(text), H1)
-    getStory().append(p)
-
-def Appendix1(text,):
-    global appmode
-    getStory().append(PageBreak())
-    if not appmode:
-        seq.setFormat('Chapter','A')
-        seq.reset('Chapter')
-        appmode = 1
-    p = Paragraph('Appendix <seq id="Chapter"/> ' + quickfix(text), H1)
-    getStory().append(p)
-
-def heading2(text):
-    """Used to be 'lesson'"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph('<seq template="%(Chapter)s.%(Section+)s "/>' + quickfix(text), H2)
-    getStory().append(p)
-
-def heading3(text):
-    """Used to be most of the plain old 'head' sections"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph(quickfix(text), H3)
-    getStory().append(p)
-
-def image(path, width=None, height=None ):
-	s = startKeep()
-	space(.2)
-	getStory().append(Image(os.path.join(os.path.dirname(sys.argv[0]),'..','images',path),width,height))
-	space(.2)
-	endKeep(s)
- 
-def heading4(text):
-    """Used to be most of the plain old 'head' sections"""
-    getStory().append(CondPageBreak(inch))
-    p = Paragraph(quickfix(text), H4)
-    getStory().append(p)
-    
-def todo(text):
-    """Used for notes to ourselves"""
-    getStory().append(Paragraph(quickfix(text), Comment))
-
-def centred(text):
-    getStory().append(Paragraph(quickfix(text), Centred))
-                      
-def caption(text):
-    getStory().append(Paragraph(quickfix(text), Caption))
-
-class Illustration(platdemos.Figure):
-    """The examples are all presented as functions which do
-    something to a canvas, with a constant height and width
-    used.  This puts them inside a figure box with a caption."""
-    
-    def __init__(self, operation, caption):
-        stdwidth, stdheight = examplefunctiondisplaysizes
-        #platdemos.Figure.__init__(self, stdwidth * 0.75, stdheight * 0.75)
-        platdemos.Figure.__init__(self, stdwidth, stdheight,
-                    'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption))
-        self.operation = operation
-        
-    def drawFigure(self):
-        #shrink it a little...
-        #self.canv.scale(0.75, 0.75)
-        self.operation(self.canv)
-
-
-def illust(operation, caption):
-    i = Illustration(operation, caption)
-    getStory().append(i)
-
-
-class GraphicsDrawing(Illustration):
-    """Lets you include reportlab/graphics drawings seamlessly,
-    with the right numbering."""
-    def __init__(self, drawing, caption):
-        platdemos.Figure.__init__(self,
-                                  drawing.width,
-                                  drawing.height,
-                    'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                                  )
-        self.drawing = drawing
-        
-    def drawFigure(self):
-        d = self.drawing
-        d.wrap(d.width, d.height)
-        d.drawOn(self.canv, 0, 0)
-        
-def draw(drawing, caption):
-    d = GraphicsDrawing(drawing, caption)
-    getStory().append(d)
-        
-class ParaBox(platdemos.Figure):
-    """Illustrates paragraph examples, with style attributes on the left"""
-    descrStyle = ParagraphStyle('description',
-                                fontName='Courier',
-                                fontSize=8,
-                                leading=9.6)
-
-    def __init__(self, text, style, caption):
-        platdemos.Figure.__init__(self, 0, 0, caption)
-        self.text = text
-        self.style = style
-        self.para = Paragraph(text, style)
-
-        styleText = self.getStyleText(style)
-        self.pre = Preformatted(styleText, self.descrStyle)
-
-    def wrap(self, availWidth, availHeight):
-        """Left 30% is for attributes, right 50% for sample,
-        10% gutter each side."""
-        self.x0 = availWidth * 0.05  #left of box
-        self.x1 = availWidth * 0.1   #left of descriptive text
-        self.x2 = availWidth * 0.5   #left of para itself
-        self.x3 = availWidth * 0.9   #right of para itself
-        self.x4 = availWidth * 0.95  #right of box
-        self.width = self.x4 - self.x0
-        self.dx = 0.5 * (availWidth - self.width)
-
-        paw, self.pah = self.para.wrap(self.x3 - self.x2, availHeight)
-        self.pah = self.pah + self.style.spaceBefore + self.style.spaceAfter
-        prw, self.prh = self.pre.wrap(self.x2 - self.x1, availHeight)
-        self.figureHeight = max(self.prh, self.pah) * 10.0/9.0
-        return platdemos.Figure.wrap(self, availWidth, availHeight)
-
-    def getStyleText(self, style):
-        """Converts style to preformatted block of text"""
-        lines = []
-        for (key, value) in style.__dict__.items():
-            lines.append('%s = %s' % (key, value))
-        lines.sort()
-        return string.join(lines, '\n')        
-        
-    def drawFigure(self):
-        
-        #now we fill in the bounding box and before/after boxes       
-        self.canv.saveState()
-        self.canv.setFillGray(0.95)
-        self.canv.setDash(1,3)
-        self.canv.rect(self.x2 - self.x0,
-                       self.figureHeight * 0.95 - self.pah,
-                       self.x3-self.x2, self.para.height,
-                       fill=1,stroke=1)
-        
-        self.canv.setFillGray(0.90)
-        self.canv.rect(self.x2 - self.x0, #spaceBefore
-                       self.figureHeight * 0.95 - self.pah + self.para.height,
-                       self.x3-self.x2, self.style.spaceBefore,
-                       fill=1,stroke=1)
-        
-        self.canv.rect(self.x2 - self.x0, #spaceBefore
-                       self.figureHeight * 0.95 - self.pah - self.style.spaceAfter,
-                       self.x3-self.x2, self.style.spaceAfter,
-                       fill=1,stroke=1)
-
-        self.canv.restoreState()
-        #self.canv.setFillColor(colors.yellow)
-        self.para.drawOn(self.canv, self.x2 - self.x0,
-                         self.figureHeight * 0.95 - self.pah)
-        self.pre.drawOn(self.canv, self.x1 - self.x0,
-                         self.figureHeight * 0.95 - self.prh)
-        
-        
-
-    def getStyleText(self, style):
-        """Converts style to preformatted block of text"""
-        lines = []
-        for (key, value) in style.__dict__.items():
-            if key not in ('name','parent'):
-                lines.append('%s = %s' % (key, value))
-        return string.join(lines, '\n')
-
-
-class ParaBox2(platdemos.Figure):
-    """Illustrates a paragraph side-by-side with the raw
-    text, to show how the XML works."""
-    def __init__(self, text, caption):
-        platdemos.Figure.__init__(self, 0, 0, caption)
-        descrStyle = ParagraphStyle('description',
-                                fontName='Courier',
-                                fontSize=8,
-                                leading=9.6)
-        textStyle = B
-        self.text = text
-        self.left = Paragraph('<![CDATA[' + text + ']]>', descrStyle)
-        self.right = Paragraph(text, B)
-        
-
-    def wrap(self, availWidth, availHeight):
-        self.width = availWidth * 0.9
-        colWidth = 0.4 * self.width
-        lw, self.lh = self.left.wrap(colWidth, availHeight)
-        rw, self.rh = self.right.wrap(colWidth, availHeight)
-        self.figureHeight = max(self.lh, self.rh) * 10.0/9.0
-        return platdemos.Figure.wrap(self, availWidth, availHeight)
-
-    def drawFigure(self):
-        self.left.drawOn(self.canv,
-                         self.width * 0.05,
-                         self.figureHeight * 0.95 - self.lh
-                         ) 
-        self.right.drawOn(self.canv,
-                         self.width * 0.55,
-                         self.figureHeight * 0.95 - self.rh
-                         ) 
-
-def parabox(text, style, caption):
-    p = ParaBox(text, style,
-                'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                )
-    getStory().append(p)
-    
-def parabox2(text, caption):
-    p = ParaBox2(text, 
-                'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
-                )
-    getStory().append(p)
-
-def pencilnote():
-    getStory().append(examples.NoteAnnotation())
-    
-
-from reportlab.lib.colors import tan, green
-def handnote(xoffset=0, size=None, fillcolor=tan, strokecolor=green):
-    getStory().append(examples.HandAnnotation(xoffset,size,fillcolor,strokecolor))
-    
-        
-#make a singleton, created when requested rather
-#than each time a chapter imports it.
-_story = None
-def getStory():
-    global _story
-    if _story is None:
-        _story = []
-    return _story
-
+from rl_doc_utils import *
 
 def run(pagesize):
-    
-    doc = RLDocTemplate('userguide.pdf',pagesize = pagesize)
+
+	doc = RLDocTemplate('userguide.pdf',pagesize = pagesize)
 
-    #this builds the story    
-    #resetStory()
+	#this builds the story
+	#resetStory()
 
-    import ch1_intro
-    import ch2_graphics
-    import ch3_pdffeatures
-    import ch4_platypus_concepts
-    import ch5_paragraphs
-    import ch6_tables
-    import ch7_custom
-    import ch9_future
-    
-    import app_demos
+	import ch1_intro
+	import ch2_graphics
+	import ch3_pdffeatures
+	import ch4_platypus_concepts
+	import ch5_paragraphs
+	import ch6_tables
+	import ch7_custom
+	import ch9_future
+
+	import app_demos
 
-    # I don't know WHAT is going on here.
-    # the submodules all do 'import *',
-    # and the story they have access to
-    # contains it all; but the one defined
-    # in this module seems to be empty.
-    #if I just call getStory, it has no
-    #items!
-    
-    story = ch9_future.getStory()
-    print 'Built story contains %d flowables...' % len(story)
-    doc.build(story)
-    print 'Saved userguide.pdf'
+	story = getStory()
+	print 'Built story contains %d flowables...' % len(story)
+	doc.build(story)
+	print 'Saved userguide.pdf'
+
+	# remove *.pyc files
+	pat = os.path.join(os.path.dirname(sys.argv[0]), '*.pyc')
+	for file in glob.glob(pat):
+		os.remove(file)
 
-    
 if __name__=="__main__":
-    if len(sys.argv) > 1:
-        try:
-            (w, h) = eval(sys.argv[1])
-        except:
-            print 'Expected page size in argument 1', sys.argv[1]
-            raise
-        print 'set page size to',sys.argv[1]
-    else:
-        (w, h) = defaultPageSize
-    run((w, h))
+	if len(sys.argv) > 1:
+		try:
+			(w, h) = eval(sys.argv[1])
+		except:
+			print 'Expected page size in argument 1', sys.argv[1]
+			raise
+		print 'set page size to',sys.argv[1]
+	else:
+		(w, h) = defaultPageSize
+	run((w, h))