#!/bin/env python

###############################################################################

#

#   ReportLab Public License Version 1.0

#

#   Except for the change of names the spirit and intention of this

#   license is the same as that of Python

#

#   (C) Copyright ReportLab Inc. 1998-2000.

#

#

# All Rights Reserved

#

# Permission to use, copy, modify, and distribute this software and its

# documentation for any purpose and without fee is hereby granted, provided

# that the above copyright notice appear in all copies and that both that

# copyright notice and this permission notice appear in supporting

# documentation, and that the name of ReportLab not be used

# in advertising or publicity pertaining to distribution of the software

# without specific, written prior permission. 

# 

#

# Disclaimer

#

# ReportLab Inc. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

# SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,

# IN NO EVENT SHALL ReportLab BE LIABLE FOR ANY SPECIAL, INDIRECT

# OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS

# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR

# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

# PERFORMANCE OF THIS SOFTWARE. 

#

###############################################################################

#   $Log: genuserguide.py,v $

#   Revision 1.14  2000/07/03 15:50:31  andy_robinson

#   Pushed down most existing lessons one level; added

#   functions heading1..heading3 for building story

#   unambiguously; spelled Hugh Hefner right!

#

#   Revision 1.13  2000/07/03 09:51:38  rgbecker

#   abspath is 1.5.2 only

#   

#   Revision 1.12  2000/06/28 16:10:00  rgbecker

#   Fix unwanted 'i'

#   

#   Revision 1.11  2000/06/28 14:52:43  rgbecker

#   Documentation changes

#   

#   Revision 1.10  2000/06/27 10:09:48  rgbecker

#   Minor cosmetic changes

#   

#   Revision 1.9  2000/06/23 21:09:03  aaron_watters

#   text text and more text

#   

#   Revision 1.8  2000/06/22 19:05:24  aaron_watters

#   added quickhack for font changes in paragraphs and lots of new text

#   

#   Revision 1.7  2000/06/22 13:55:59  aaron_watters

#   showPage resets all state parameters warning.

#   

#   Revision 1.6  2000/06/22 13:35:28  aaron_watters

#   textobject and pathobject methods, among other things

#   

#   Revision 1.5  2000/06/21 21:19:29  aaron_watters

#   colors, line styles, more examples

#   

#   Revision 1.4  2000/06/21 15:16:05  aaron_watters

#   Lots of graphical examples added

#   

#   Revision 1.3  2000/06/20 20:31:42  aaron_watters

#   typos and more examples

#   

#   Revision 1.2  2000/06/19 21:13:02  aaron_watters

#   2nd try. more text

#   

#   Revision 1.1  2000/06/17 02:57:56  aaron_watters

#   initial checkin. user guide generation framework.

#   

__doc__ = """

This module contains the script for building the user guide.

"""

_oldStyle=0     #change to 1 to get Aaron's original

if _oldStyle:

    from reportlab.lib.styles import getSampleStyleSheet

    styleSheet = getSampleStyleSheet()

else:

    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.platypus.flowables import Flowable

from reportlab.lib.units import inch

from reportlab.lib.pagesizes import letter

from reportlab.platypus import Paragraph, Spacer, Preformatted, PageBreak, CondPageBreak

from reportlab.lib.styles import ParagraphStyle

from reportlab.lib import colors

from reportlab.lib.sequencer import getSequencer

import examples

from reportlab.lib.corp import ReportLabLogo

LOGO = ReportLabLogo(0.25*inch, 0.25*inch, inch, 0.75*inch)

from t_parse import Template

QFcodetemplate = Template("X$X$", "X")

QFreptemplate = Template("X^X^", "X")

if _oldStyle:

    codesubst = "%s<font name=courier color=green>%s</font>"

    QFsubst = "%s<font name=Helvetica color=blue><i>%s</i></font>"

else:

    codesubst = "%s<b><font name=courier></b>%s</font>"

    QFsubst = "%s<font name=Helvetica><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^)$")

if _oldStyle:

    class PageAnnotations:

        """ "closure" containing onfirstpage, onnextpage actions

            and any data they might want to use.

        """

        pagesize = letter

        pagenumber = 1

        def onFirstPage(self, canvas, doc):

            (xsize, ysize) = self.pagesize

            LOGO.draw(canvas)

            #  width=6.25*inch,height=0.62*inch)

            canvas.setFont("Helvetica", 12)

            canvas.drawRightString(xsize-inch, ysize-0.8*inch, "ReportLab User Guide")

            self.pagenumber = self.pagenumber+1

        def onNextPage(self, canvas, doc):

            canvas.saveState()

            (xsize, ysize) = self.pagesize

            canvas.setFont("Helvetica", 12)

            canvas.drawString(inch, ysize-0.8*inch, "Page %s" % self.pagenumber)

            self.onFirstPage(canvas, doc)

            canvas.restoreState()

class Guide:

    def __init__(self):

        if _oldStyle:

            self.myannotations = PageAnnotations()

        self.story = story()

    def go(self, filename="userguide.pdf"):

        # generate the doc...

        doc = RLDocTemplate(filename,pagesize = letter)

        story = self.story

        if _oldStyle:

            doc.build(story, self.myannotations.onFirstPage, self.myannotations.onNextPage)

        else:

            doc.build(story)

seq = getSequencer()

H1 = styleSheet['Heading1']

H2 = styleSheet['Heading2']

H3 = styleSheet['Heading3']

B = styleSheet['BodyText']

Comment = styleSheet['Comment']

if _oldStyle:

    lessonnamestyle = ParagraphStyle("lessonname", parent=H2)

    lessonnamestyle.fontName = 'Helvetica-Bold'

    discussiontextstyle = ParagraphStyle("discussiontext", parent=B)

    discussiontextstyle.fontName= 'Helvetica'

else:

    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

BODY = []

def story():

    return BODY

def disc(text, klass=Paragraph, style=discussiontextstyle):

    text = quickfix(text)

    P = klass(text, style)

    BODY.append(P)

def eg(text):

    BODY.append(Spacer(0.1*inch, 0.1*inch))

    disc(text, klass=Preformatted, style=exampletextstyle)

#eg("""

#this

#  is 

#    an 

#     example""")

##def head(text,style=lessonnamestyle):

##    BODY.append(CondPageBreak(inch))

##    disc(text, style=style)

def title(text):

    """Use this for the document title only"""

    disc(text,style=styleSheet['Title'])

##def lesson(text):

##    BODY.append(PageBreak())

##    heading3(text,style=H1)

#heading3("this is a header")

#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."""

    BODY.append(PageBreak())

    p = Paragraph('Chapter <seq id="Chapter"/> - ' + quickfix(text), H1)

    BODY.append(p)

def heading2(text):

    """Used to be 'lesson'"""

    BODY.append(CondPageBreak(inch))

    p = Paragraph('<seq template="%(Chapter)s.%(Section+)s - "/>' + quickfix(text), H2)

    BODY.append(p)

def heading3(text):

    """Used to be most of the plain old 'head' sections"""

    BODY.append(CondPageBreak(inch))

    p = Paragraph(quickfix(text), H3)

    BODY.append(p)

def todo(text):

    """Used for notes to ourselves"""

    BODY.append(Paragraph(quickfix(text), Comment))

def canvasdemo(function):

    BODY.append(Spacer(0.1*inch, 0.1*inch))

    BODY.append(OperationWrapper(function))

class OperationWrapper(Flowable):

    """wrap a drawing operation as a flowable.

       the operation should respect the examplefunctiondisplaysizes

       limitations.

       This example wraps a drawing operator f(pdfgen.canvas).

       Always enclosed in a rectangle.

    """

    def __init__(self, operation):

        self.operation = operation

    def wrap(self, aw, ah):

        return examplefunctiondisplaysizes # always the same

    def draw(self):

        canvas = self.canv

        canvas.saveState()

        (x,y) = examplefunctiondisplaysizes

        self.operation(canvas)

        canvas.restoreState()

        canvas.rect(0,0,x,y)

def pencilnote():

    BODY.append(examples.NoteAnnotation())

###### testing...

#canvasdemo(NOP)

#heading2("this is a new lesson")

#disc("this explains the example")

#eg("""

#this

#  is the

#    example

#      code""")

#disc("the execution of the example follows")

#canvasdemo(NOP) # execute some code

#pencilnote()

title("ReportLab User Guide")

todo("""To-do items to authors, or points under discussion,

appear in italics like this.""")

todo("""The examples should go in slightly smaller boxes,

centred in the frame, with a 'Figure 1.2...' style caption

beneath them.  We can just scale things down a little.

A Figure widget can be found in platdemos.py; they should

draw inside that.""")

heading1("Introduction")

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.

""")

heading2("What is PDFgen all about")

todo("rationale - from Andy")

#canvasdemo(NOP) # execute some code

heading2("About Python")

todo("If they don't know Python, rave a little then tell them where to get it")

heading2("Installation and Setup")

todo("need notes on packages, Windows, PIL and zlib; how to test it works")

pencilnote()

disc("""

This document is in a <em>very</em> preliminary form.

""")

heading1("Graphics and Text with $pdfgen$")

heading2("Basic Concepts")

disc("""

The $pdfgen$ package is the lowest level interface for

generating PDF documents.  A $pdfgen$ program is essentially

a sequence of instructions for "painting" a document onto

a sequence of pages.  The interface object which provides the

painting operations is the $pdfgen$ canvas.  

""")

disc("""

The canvas should be thought of as a sheet of white paper

with points on the sheet identified using Cartesian ^(X,Y)^ coordinates

which by default have the ^(0,0)^ origin point at the lower

left corner of the page.  Furthermore the first coordinate ^x^

goes to the right and the second coordinate ^y^ goes up, by

default.""")

disc("""

A simple example

program that uses a canvas follows.

""")

eg("""

    from reportlab.pdfgen import canvas

    c = canvas.Canvas("hello.pdf")

    hello(c)

    c.showPage()

    c.save()

""")

disc("""

The above code creates a $canvas$ object which will generate

a PDF file named $hello.pdf$ in the current working directory.

It then calls the $hello$ function passing the $canvas$ as an argument.

Finally the $showPage$ method saves the current page of the canvas

and the $save$ method stores the file and closes the canvas.""")

disc("""

The $showPage$ method causes the $canvas$ to stop drawing on the

current page and any further operations will draw on a subsequent

page (if there are any further operations -- if not no

new page is created).  The $save$ method must be called after the

construction of the document is complete -- it generates the PDF

document, which is the whole purpose of the $canvas$ object.

""")

disc("""

Suppose the $hello$ function referenced above is implemented as

follows (we will not explain each of the operations in detail

yet).

""")

eg(examples.testhello)

disc("""

Examining this code notice that there are essentially two types

of operations performed using a canvas.  The first type draws something

on the page such as a text string or a rectangle or a line.  The second

type changes the state of the canvas such as

changing the current fill or stroke color or changing the current font

type and size.  

""")

disc("""

If we imagine the program as a painter working on

the canvas the "draw" operations apply paint to the canvas using

the current set of tools (colors, line styles, fonts, etcetera)

and the "state change" operations change one of the current tools

(changing the fill color from whatever it was to blue, or changing

the current font to $Times-Roman$ in 15 points, for example).

""")

disc("""

The document generated by the "hello world" program listed above would contain

the following graphics.

""")

canvasdemo(examples.hello)

heading3("About the demos in this document")

disc("""

This document contains demonstrations of the code discussed like the one shown

in the rectangle above.  These demos are drawn on a "tiny page" embedded

within the real pages of the guide.  The tiny pages are %s inches wide

and %s inches tall.  The demo displays show the actual output of the demo

code.

""" % (examplefunctionxinches, examplefunctionyinches))

heading2('The tools: the "draw" operations')

disc("""

This section briefly lists the tools available to the program

for painting information onto a page using the canvas interface.

These will be discussed in detail in later sections.  They are listed

here for easy reference and for summary purposes.

""")

heading3("Line methods")

eg("""canvas.line(x1,y1,x2,y2)""")

eg("""canvas.lines(linelist)""")

disc("""

The line methods draw straight line segments on the canvas.

""")

heading3("Shape methods")

eg("""canvas.grid(xlist, ylist) """)

eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")

eg("""canvas.arc(x1,y1,x2,y2) """)

eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)

eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")

eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)

eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")

eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)

disc("""

The shape methods draw common complex shapes on the canvas.

""")

heading3("String drawing methods")