RL2

bzr revid: pinky-6e2b8c053bc91a80362d7d3867ff412eb65b09c7

3 files changed, 249 insertions, 0 deletions

diff --git a/bin/reportlab/docs/reference/build.bat b/bin/reportlab/docs/reference/build.bat
new file mode 100755
index 00000000000..483af7b9b6c
--- /dev/null
+++ b/bin/reportlab/docs/reference/build.bat
@@ -0,0 +1,3 @@
+del reference.pdf
+python ..\tools\yaml2pdf.py reference.yml
+start reference.pdf
diff --git a/bin/reportlab/docs/reference/genreference.py b/bin/reportlab/docs/reference/genreference.py
new file mode 100644
index 00000000000..c2b6afd7598
--- /dev/null
+++ b/bin/reportlab/docs/reference/genreference.py
@@ -0,0 +1,29 @@
+#!/bin/env python
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/reference/genreference.py
+__version__=''' $Id: genreference.py 2385 2004-06-17 15:26:05Z rgbecker $ '''
+__doc__ = """
+This module contains the script for building the reference.
+"""
+def run(verbose=None, outDir=None):
+    import os, sys, shutil
+    from reportlab.tools.docco import yaml2pdf
+    from reportlab.lib.utils import _RL_DIR
+    if verbose is None: verbose=('-s' not in sys.argv)
+    yaml2pdf.run('reference.yml','reference.pdf')
+    if verbose: print 'Saved reference.pdf'
+    docdir = os.path.join(_RL_DIR,'docs')
+    if outDir: docDir = outDir
+    destfn = docdir + os.sep + 'reference.pdf'
+    shutil.copyfile('reference.pdf', destfn)
+    if verbose: print 'copied to %s' % destfn
+
+def makeSuite():
+    "standard test harness support - run self as separate process"
+    from reportlab.test.utils import ScriptThatMakesFileTest
+    return ScriptThatMakesFileTest('../docs/reference', 'genreference.py', 'reference.pdf')
+
+
+if __name__=='__main__':
+    run()
diff --git a/bin/reportlab/docs/reference/reference.yml b/bin/reportlab/docs/reference/reference.yml
new file mode 100644
index 00000000000..65e4091af5c
--- /dev/null
+++ b/bin/reportlab/docs/reference/reference.yml
@@ -0,0 +1,217 @@
+.t ReportLab API Reference
+
+.nextPageTemplate Normal
+
+.h1 Introduction
+
+This is the API reference for the ReportLab library.  All public
+classes, functions and methods are documented here.
+
+Most of the reference text is built automatically from the
+documentation strings in each class, method and function.
+That's why it uses preformatted text and doesn't look very
+pretty.
+
+Please note the following points:
+.bu <seqdefault id='list'/><bullet>(<seq/>)</bullet>Items with one leading underscore are considered private
+to the modules they are defined in; they are not documented
+here and we make no commitment to their maintenance.
+.bu <bullet>(<seq/>)</bullet>Items ending in a digit (usually zero) are experimental;
+they are released to allow widespread testing, but are
+guaranteed to be broken in future (if only by dropping the
+zero).  By all means play with these and give feedback, but
+do not use them in production scripts.
+
+.h2 Package Architecture
+
+The reportlab package is broken into a number of subpackages.
+These are as follows:
+
+.df <font name="Courier"><b>reportlab.pdfgen</b></font>
+- this is the programming
+interface to the PDF file format.  The Canvas (and its co-workers,
+TextObject and PathObject) provide everything you need to
+create PDF output working at a low level - individual shapes
+and lines of text.  Internally, it constructs blocks of
+<i>page marking operators</i> which match your drawing commands,
+and hand them over to the <font name="Courier">pdfbase</font>
+package for drawing.
+
+.df <font name="Courier"><b>reportlab.pdfbase</b></font>
+- this is not part of the
+public interface.  It contains code to handle the 'outer
+structure' of PDF files, and utilities to handle text metrics
+and compressed streams.
+
+.df <font name="Courier"><b>reportlab.platypus</b></font>
+- PLATYPUS stands for
+"Page Layout and Typography Using Scripts".  It provides a
+higher level of abstraction dealing with paragraphs, frames
+on the page, and document templates.  This is used for multi-
+page documents such as this reference.
+
+.df <font name="Courier"><b>reportlab.lib</b></font>
+- this contains code of
+interest to application developers which cuts across
+both of our libraries, such as standard colors, units, and
+page sizes.  It will also contain more drawable and flowable
+objects in future.
+
+There is also a demos directory containing various demonstrations,
+and a docs directory.  These can be accessed with package
+notation but should not be thought of as packages.
+
+Each package is documented in turn.
+
+.pageBreak
+.h1 <i>reportlab.pdfgen</i> subpackage
+
+This package contains three modules, canvas.py, textobject.py
+and pathobject.py, which define three classes of corresponding 
+names.  The only class users should construct directly is
+the Canvas, defined in reportlab.pdfgen.canvas; it provides
+methods to obtain PathObjects and TextObjects.
+
+
+.getClassDoc reportlab.pdfgen.canvas Canvas
+.pageBreak
+The method Canvas.beginPath allows users to construct
+a PDFPathObject, which is defined in reportlab/pdfgen/pathobject.py.
+
+.getClassDoc reportlab.pdfgen.pathobject PDFPathObject
+.pageBreak
+The method Canvas.beginText allows users to construct
+a PDFTextObject, which is defined in reportlab/pdfgen/textobject.py.
+
+.getClassDoc reportlab.pdfgen.textobject PDFTextObject
+
+.pageBreak
+.h1 <i>reportlab.platypus</i> subpackage
+
+The platypus package defines our high-level page layout API.
+The division into modules is far from final and has been
+based more on balancing the module lengths than on any
+particular programming interface.  The __init__ module
+imports the key classes into the top level of the package.
+
+.h2 Overall Structure
+
+Abstractly Platypus currently can be thought of has having four
+levels: documents, pages, frames and flowables (things which can fit into frames in some way).
+In practice there is a fifth level, the canvas, so that if you want
+you can do anything that pdfgen's canvas allows.
+
+.h2 Document Templates
+.h3 BaseDocTemplate
+
+The basic document template class; it provides for initialisation and 
+rendering of documents. A whole bunch of methods 
+<b><font name=courier>handle_XXX</font></b> handle document
+rendering events. These event routines all contain some
+significant semantics so while these may be overridden that
+may require some detailed knowledge. Some other methods are
+completely virtual and are designed to be overridden.
+.h3 BaseDocTemplate
+.getClassDoc reportlab.platypus.doctemplate BaseDocTemplate
+
+.pageBreak
+A simple document processor can be made using derived class,
+<b><font name=courier>SimpleDocTemplate</font></b>.
+
+.pageBreak
+.h3 SimpleDocTemplate
+.getClassDoc reportlab.platypus.doctemplate SimpleDocTemplate
+
+.pageBreak
+.h2 Flowables
+.getClassDoc reportlab.platypus.paragraph Paragraph
+.getClassDoc reportlab.platypus.flowables Flowable
+.getClassDoc reportlab.platypus.flowables XBox
+.getClassDoc reportlab.platypus.flowables Preformatted
+.getClassDoc reportlab.platypus.flowables Image
+.getClassDoc reportlab.platypus.flowables Spacer
+.getClassDoc reportlab.platypus.flowables PageBreak
+.getClassDoc reportlab.platypus.flowables CondPageBreak
+.getClassDoc reportlab.platypus.flowables KeepTogether
+.getClassDoc reportlab.platypus.flowables Macro
+.getClassDoc reportlab.platypus.xpreformatted XPreformatted
+.getClassDoc reportlab.platypus.xpreformatted PythonPreformatted
+
+.pageBreak
+.h1 <i>reportlab.lib</i> subpackage
+
+This package contains a number of modules which either add utility
+to pdfgen and platypus, or which are of general use in graphics
+applications.
+
+.h2 <i>reportlab.lib.colors</i> module
+.getModuleDoc reportlab.lib.colors
+
+.h2 <i>reportlab.lib.corp</i> module
+.getModuleDoc reportlab.lib.corp
+
+.h2 <i>reportlab.lib.enums</i> module
+.getModuleDoc reportlab.lib.enums
+
+.h2 <i>reportlab.lib.fonts</i> module
+.getModuleDoc reportlab.lib.fonts
+
+.h2 <i>reportlab.lib.pagesizes</i> module
+.getModuleDoc reportlab.lib.pagesizes
+
+.h2 <i>reportlab.lib.sequencer</i> module
+.getModuleDoc reportlab.lib.sequencer
+
+
+
+
+.pageBreak
+.h1 Appendix A - CVS Revision History
+.beginPre Code
+$Log: reference.yml,v $
+Revision 1.1  2001/10/05 12:33:33  rgbecker
+Moved from original project docs, history lost
+
+Revision 1.13  2001/08/30 10:32:38  dinu_gherman
+Added missing flowables.
+
+Revision 1.12  2001/07/11 09:21:27  rgbecker
+Typo fix from Jerome Alet
+
+Revision 1.11  2000/07/10 23:56:09  andy_robinson
+Paragraphs chapter pretty much complete.  Fancy cover.
+
+Revision 1.10  2000/07/03 15:39:51  rgbecker
+Documentation fixes
+
+Revision 1.9  2000/06/28 14:52:43  rgbecker
+Documentation changes
+
+Revision 1.8  2000/06/19 23:52:31  andy_robinson
+rltemplate now simple, based on UserDocTemplate
+
+Revision 1.7  2000/06/17 07:46:45  andy_robinson
+Small text changes
+
+Revision 1.6  2000/06/14 21:22:52  andy_robinson
+Added docs for library
+
+Revision 1.5  2000/06/12 11:26:34  andy_robinson
+Numbered list added
+
+Revision 1.4  2000/06/12 11:13:09  andy_robinson
+Added sequencer tags to paragraph parser
+
+Revision 1.3  2000/06/09 01:44:24  aaron_watters
+added automatic generation for pathobject and textobject modules.
+
+Revision 1.2  2000/06/07 13:39:22  andy_robinson
+Added some text to the first page of reference, and a build batch file
+
+Revision 1.1.1.1  2000/06/05 16:39:04  andy_robinson
+initial import
+
+.endPre
+
+
+