<commit_before>#ch4_platypus_concepts
from genuserguide import *

#####################################################################################################3


heading1("PLATYPUS - Page Layout and Typography Using Scripts")

heading2("Design Goals")

disc("""
Platypus stands for &quot;Page Layout and Typography Using Scripts&quot;.  It is a high
level page layout library which lets you programmatically create complex
documents with a minimum of effort.
""")

disc("""
The overall design of PLATYPUS can be thought of has having
several layers, top down, these are""")

disc("<b>$DocTemplates$</b> the outermost container for the document;")
 
disc("<b>$PageTemplates$</b> specifications for layouts of pages of various kinds;")
 
disc("<b>$Frames$</b> specifications of regions in pages that can contain flowing text or graphics.")
 
disc("""<b>$Flowables$</b> text or graphic elements that should be "flowed 
   into the document (ie things like images, paragraphs and tables, but not things
   like page footers or fixed page graphics).""")
   
disc("""<b>$pdfgen.Canvas$</b> the lowest level which ultimately receives the painting of the
   document from the other layers.""")
 
illust(examples.doctemplateillustration, "Illustration of DocTemplate structure")
 
disc("""
 The illustration above graphically illustrates the concepts of $DocTemplates$,
 $PageTemplates$ and $Flowables$.  It is deceptive, however, because each
 of the $PageTemplates$ actually may specify the format for any number of pages
 (not just one as might be inferred from the diagram).
""")

disc("""
$DocTemplates$ contain one or more $PageTemplates$ each of which contain one or more
$Frames$. $Flowables$ are things which can be <i>flowed</i> into a $Frame$ eg
a $Paragraph$ or a $Table$.
""")

disc("""
To use platypus you do approximately the following:
create a document from a $DocTemplate$ class and pass
a list of $Flowable$s to its $build$ method. The document
$build$ method knows how to process the list of flowables
into something reasonable.
""")

disc("""
Internally the $DocTemplate$ class implements page layout and formatting
using various events. Each of the events has a corresponding handler method
called $handle_XXX$ where $XXX$ is the event name. A typical event is
$frameBegin$ which occurs when the machinery begins to use a frame for the
first time.
""")

disc("""
The logic behind this is that the story consists of basic elements called $Flowables$
and these can be used to drive the machinery which leads to a data driven approach, but
instead of producing another macro driven troff like language we are programming
in python and can use $ActionFlowables$ to tell the layout engine to skip to the next
column or change to another $PageTemplate$.
""")

heading2("$Flowables$")
disc("""
$Flowables$ are things which can be drawn and which have $wrap$, $draw$ and perhaps $split$ methods.
$Flowable$ is an abstract base class for things to be drawn an instance knows its size
and draws in its own coordinate system (this requires the base API to provide an absolute coordinate
system when the $Flowable.draw$ method is called). To get an instance use $f=Flowable()$.
""")
disc("""
It should be noted that the $Flowable$ class is an <i>abstract</i> class and is normally
only used as a base class.
""")
k=startKeep()
disc("""
To illustrate the general way in which $Flowables$ are used we show how a derived class $Paragraph$
is used and drawn on a canvas. $Paragraphs$ are so important they will get a whole chapter
to themselves.
""")
eg("""
    from reportlab.lib.styles import getSampleStyleSheet
    from reportlab.platypus import Paragraph
    from reportlab.pdfgen.canvas import Canvas
    styleSheet = getSampleStyleSheet()
    style = styleSheet['BodyText']
    P=Paragraph('This is a very silly example',style)
    canv = Canvas('doc.pdf')
    aW = 460    # available width and height
    aH = 800
    w,h = P.wrap(aW, aH)    # find required space
    if w<aW and h<aH:
        P.drawOn(canv,0,aH)<commit_msg>platypus hello worlk example<commit_after>#ch4_platypus_concepts
from genuserguide import *

#####################################################################################################3


heading1("PLATYPUS - Page Layout and Typography Using Scripts")

heading2("Design Goals")

disc("""
Platypus stands for &quot;Page Layout and Typography Using Scripts&quot;.  It is a high
level page layout library which lets you programmatically create complex
documents with a minimum of effort.
""")



disc("""
The design of Platypus seeks to separate "high level" layout decisions
from the document content as much as possible.  Thus, for example paragraphs
are constructed using paragraph styles and pages are constructed
using page templates with the intention that hundreds of
documents with thousands of pages can be reformatted to different
style specifications with the modifications of a few lines in a single
shared file which contains the paragraph styles and page layout specifications.
""")


disc("""
The overall design of PLATYPUS can be thought of has having
several layers, top down, these are""")

disc("<b>$DocTemplates$</b> the outermost container for the document;")
 
disc("<b>$PageTemplates$</b> specifications for layouts of pages of various kinds;")
 
disc("<b>$Frames$</b> specifications of regions in pages that can contain flowing text or graphics.")
 
disc("""<b>$Flowables$</b> text or graphic elements that should be "flowed 
   into the document (ie things like images, paragraphs and tables, but not things
   like page footers or fixed page graphics).""")
   
disc("""<b>$pdfgen.Canvas$</b> the lowest level which ultimately receives the painting of the
   document from the other layers.""")
 
illust(examples.doctemplateillustration, "Illustration of DocTemplate structure")
 
disc("""
 The illustration above graphically illustrates the concepts of $DocTemplates$,
 $PageTemplates$ and $Flowables$.  It is deceptive, however, because each
 of the $PageTemplates$ actually may specify the format for any number of pages
 (not just one as might be inferred from the diagram).
""")

disc("""
$DocTemplates$ contain one or more $PageTemplates$ each of which contain one or more
$Frames$. $Flowables$ are things which can be <i>flowed</i> into a $Frame$ eg
a $Paragraph$ or a $Table$.
""")

disc("""
To use platypus you create a document from a $DocTemplate$ class and pass
a list of $Flowable$s to its $build$ method. The document
$build$ method knows how to process the list of flowables
into something reasonable.
""")

disc("""
Internally the $DocTemplate$ class implements page layout and formatting
using various events. Each of the events has a corresponding handler method
called $handle_XXX$ where $XXX$ is the event name. A typical event is
$frameBegin$ which occurs when the machinery begins to use a frame for the
first time.
""")

disc("""
A Platypus story consists of a sequence of basic elements called $Flowables$
and these elements drive the data driven platypus formatting engine.
To modify the behavior of the engine
a special kind of flowable, $ActionFlowables$, tell the layout engine to,
for example, skip to the next
column or change to another $PageTemplate$.
""")


heading2("""Getting started""")

disc("""Consider the following code sequence which provides
a very simple "hello world" example for Platypus.""")

eg(examples.platypussetup)

disc("""First we import some constructors, some paragraph styles
and other conveniences from other modules.""")

eg(examples.platypusfirstpage)

disc("""We define the fixed features of the first page of the document
with the function above.""")

eg(examples.platypusnextpage)

disc("""Since we want pages after the first to look different from the
first we define an alternate layout for the fixed features
of the other pages.  Note that the two functions above use
the $pdfgen$ level canvas operations to paint the annotations for
the pages.  
""")

eg(examples.platypusgo)

disc("""
Finally we create a story and build the document.
Note that we are using a "canned" document template here which
comes pre-built with page templates.  We are also using a pre-built
paragraph style.  We are only using two types of flowables here
-- $Spacers$ and $Paragraphs$.  The first $Spacer$ ensures that the
Paragraphs skip past the title string. 
""")

disc("""
To see the output of this example program run the module
$docs/userguide/examples.py$ (from the ReportLab $docs$ distribution)
as a "top level script".  The script interpretation $python examples.py$ will
generate the Platypus output $phello.pdf$.
""")


heading2("$Flowables$")
disc("""
$Flowables$ are things which can be drawn and which have $wrap$, $draw$ and perhaps $split$ methods.
$Flowable$ is an abstract base class for things to be drawn an instance knows its size
and draws in its own coordinate system (this requires the base API to provide an absolute coordinate
system when the $Flowable.draw$ method is called). To get an instance use $f=Flowable()$.
""")
disc("""
It should be noted that the $Flowable$ class is an <i>abstract</i> class and is normally
only used as a base class.
""")
k=startKeep()
disc("""
To illustrate the general way in which $Flowables$ are used we show how a derived class $Paragraph$
is used and drawn on a canvas. $Paragraphs$ are so important they will get a whole chapter
to themselves.
""")
eg("""
    from reportlab.lib.styles import getSampleStyleSheet
    from reportlab.platypus import Paragraph
    from reportlab.pdfgen.canvas import Canvas
    styleSheet = getSampleStyleSheet()
    style = styleSheet['BodyText']
    P=Paragraph('This is a very silly example',style)
    canv = Canvas('doc.pdf')
    aW = 460    # available width and height
    aH = 800
    w,h = P.wrap(aW, aH)    # find required space
    if w<aW and h<aH:
        P.drawOn(canv,0,aH)
{'fraction_non_alphanumeric': 0.10306153379812064, 'fraction_numerical': 0.0025260179852480548, 'mean_word_length': 4.818930041152264, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5549712', 'n_tokens_mistral': 2789, 'n_tokens_neox': 2629, 'n_words': 1324}