docs/userguide/ch5_paragraphs.py
author rgbecker
Wed, 25 Oct 2000 08:57:46 +0000
changeset 494 54257447cfe9
parent 399 600ebb5a92cf
child 546 8e17202e9067
permissions -rw-r--r--
Changed to indirect copyright
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
494
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 399
diff changeset
     1
#copyright ReportLab Inc. 2000
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 399
diff changeset
     2
#see license.txt for license details
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 399
diff changeset
     3
#history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch5_paragraphs.py?cvsroot=reportlab
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 399
diff changeset
     4
#$Header: /tmp/reportlab/docs/userguide/ch5_paragraphs.py,v 1.6 2000/10/25 08:57:45 rgbecker Exp $
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     5
from genuserguide import *
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     6
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     7
#begin chapter oon paragraphs
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     8
heading1("Paragraphs")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     9
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    10
The $reportlab.platypus.Paragraph$ class is one of the most useful of the Platypus $Flowables$;
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    11
it can format fairly arbitrary text and provides for inline font style and colour changes using
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    12
an XML style markup. The overall shape of the formatted text can be justified, right or left ragged
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    13
or centered. The XML markup can even be used to insert greek characters or to do subscripts.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    14
""")
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    15
disc("""The following text creates an instance of the $Paragraph$ class:""") 
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    16
eg("""Paragraph(text, style, bulletText=None)""")
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
    17
disc("""The $text$ argument contains the text of the
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    18
paragraph; excess white space is removed from the text at the ends and internally after
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    19
linefeeds. This allows easy use of indented triple quoted text in <b>Python</b> scripts.
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    20
The $bulletText$ argument provides the text of a default bullet for the paragraph.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    21
The font and other properties for the paragraph text and bullet are set using the style argument.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    22
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    23
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    24
The $style$ argument should be an instance of class $ParagraphStyle$ obtained typically
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    25
using""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    26
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    27
from reportlab.lib.styles import ParagraphStyle
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    28
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    29
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    30
this container class provides for the setting of multiple default paragraph attributes
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    31
in a structured way. The styles are arranged in a dictionary style object called a $stylesheet$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    32
which allows for the styles to be accessed as $stylesheet['BodyText']$. A sample style
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    33
sheet is provided.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    34
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    35
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    36
from reportlab.lib.styles import getSampleStyleSheet
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    37
stylesheet=getSampleStyleSheet()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    38
normalStyle = stylesheet['Normal']
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    39
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    40
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    41
The options which can be set for a $Paragraph$ can be seen from the $ParagraphStyle$ defaults.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    42
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    43
heading4("$class ParagraphStyle$")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    44
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    45
class ParagraphStyle(PropertySet):
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    46
    defaults = {
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    47
        'fontName':'Times-Roman',
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    48
        'fontSize':10,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    49
        'leading':12,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    50
        'leftIndent':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    51
        'rightIndent':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    52
        'firstLineIndent':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    53
        'alignment':TA_LEFT,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    54
        'spaceBefore':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    55
        'spaceAfter':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    56
        'bulletFontName':'Times-Roman',
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    57
        'bulletFontSize':10,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    58
        'bulletIndent':0,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    59
        'textColor': black
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    60
        }
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    61
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    62
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    63
heading2("Using Paragraph Styles")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    64
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    65
#this will be used in the ParaBox demos.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    66
sample = """You are hereby charged that on the 28th day of May, 1970, you did
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    67
willfully, unlawfully, and with malice of forethought, publish an
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    68
alleged English-Hungarian phrase book with intent to cause a breach
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    69
of the peace.  How do you plead?"""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    70
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    71
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    72
disc("""The $Paragraph$ and $ParagraphStyle$ classes together
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    73
handle most common formatting needs. The following examples
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    74
draw paragraphs in various styles, and add a bounding box
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    75
so that you can see exactly what space is taken up.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    76
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    77
s1 = ParagraphStyle('Normal')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    78
parabox(sample, s1, 'The default $ParagraphStyle$')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    79
    
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
    80
disc("""The two attributes $spaceBefore$ and $spaceAfter$ do what they
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    81
say, except at the top or bottom of a frame. At the top of a frame,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    82
$spaceBefore$ is ignored, and at the bottom, $spaceAfter$ is ignored.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    83
This means that you could specify that a 'Heading2' style had two
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    84
inches of space before when it occurs in mid-page, but will not
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
    85
get acres of whitespace at the top of a page.  These two attributes
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    86
should be thought of as 'requests' to the Frame and are not part
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    87
of the space occupied by the Paragraph itself.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    88
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    89
disc("""The $fontSize$ and $fontName$ tags are obvious, but it is
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    90
important to set the $leading$.  This is the spacing between
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    91
adjacent lines of text; a good rule of thumb is to make this
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    92
20% larger than the point size.  To get double-spaced text,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    93
use a high $leading$.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    94
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    95
disc("""The figure below shows space before and after and an
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    96
increased leading:""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    97
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    98
parabox(sample,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    99
        ParagraphStyle('Spaced',
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   100
                       spaceBefore=6,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   101
                       spaceAfter=6,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   102
                       leading=16),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   103
        'Space before and after and increased leading'
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   104
        )
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   105
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   106
disc("""The $firstLineIndent$, $leftIndent$ and $rightIndent$ attributes do exactly
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   107
what you would expect.  If you want a straight left edge, remember
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   108
to set $firstLineIndent$ equal to $leftIndent$.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   109
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   110
parabox(sample,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   111
        ParagraphStyle('indented',
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   112
                       firstLineIndent=48,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   113
                       leftIndent=24,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   114
                       rightIndent=24),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   115
        'one third inch indents at left and right, two thirds on first line'
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   116
        )
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   117
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   118
disc("""Setting $firstLineIndent$ equal to zero, $leftIndent$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   119
much higher, and using a
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   120
different font (we'll show you how later!) can give you a
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   121
definition list:.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   122
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   123
parabox('<b><i>Judge Pickles: </i></b>' + sample,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   124
        ParagraphStyle('dl',
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   125
                       leftIndent=36),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   126
        'Definition Lists'
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   127
        )
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   128
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   129
disc("""There are four possible values of $alignment$, defined as
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   130
constants in the module <i>reportlab.lib.enums</i>.  These are
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   131
TA_LEFT, TA_CENTER or TA_CENTRE, TA_RIGHT and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   132
TA_JUSTIFY, with values of 0, 1, 2 and 4 respectively.  These
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   133
do exactly what you would expect.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   134
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   135
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   136
heading2("Paragraph XML Markup Tags")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   137
disc("""XML markup can be used to modify or specify the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   138
overall paragraph style, and also to specify intra-
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   139
paragraph markup.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   140
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   141
heading3("The outermost &lt; para &gt; tag")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   142
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   143
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   144
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   145
The paragraph text may optionally be surrounded by
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   146
&lt;para attributes....&gt;
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   147
&lt;/para&gt;
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   148
tags. The attributes if any of the opening &lt;para&gt; tag affect the style that is used
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   149
with the $Paragraph$ $text$ and/or $bulletText$.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   150
""")
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   151
disc(" ")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   152
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   153
from reportlab.platypus.paraparser import _addAttributeNames, _paraAttrMap, _bulletAttrMap
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   154
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   155
def getAttrs(A):
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   156
    _addAttributeNames(A)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   157
    S={}
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   158
    for k, v in A.items():
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   159
        a = v[0]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   160
        if not S.has_key(a):
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   161
            S[a] = k
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   162
        else:
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   163
            S[a] = "%s, %s" %(S[a],k)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   164
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   165
    K = S.keys()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   166
    K.sort()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   167
    D=[('Attribute','Synonyms')]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   168
    for k in K:
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   169
        D.append((k,S[k]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   170
    cols=2*[None]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   171
    rows=len(D)*[None]
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
   172
    return D,cols,rows
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   173
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   174
t=apply(Table,getAttrs(_paraAttrMap))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   175
t.setStyle(TableStyle([
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   176
            ('FONT',(0,0),(-1,1),'Times-Bold',10,12),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   177
            ('FONT',(0,1),(-1,-1),'Courier',8,8),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   178
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   179
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   180
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   181
            ]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   182
getStory().append(t)
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   183
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Synonyms for style attributes""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   184
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   185
disc("""Some useful synonyms have been provided for our Python attribute
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   186
names, including lowercase versions, and the equivalent properties
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   187
from the HTML standard where they exist.  These additions make
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   188
it much easier to build XML-printing applications, since
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   189
much intra-paragraph markup may not need translating. The
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   190
table below shows the allowed attributes and synonyms in the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   191
outermost paragraph tag.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   192
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   193
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   194
heading2("Intra-paragraph markup")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   195
disc("""'<![CDATA[Within each paragraph, we use a basic set of XML tags
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   196
to provide markup.  The most basic of these are bold (<b>...</b>)
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   197
and italic (<i>...</i>).  It is also legal to use an underline
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   198
tag (<u>...</u> but it has no effect; PostScript fonts don't
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
   199
support underlining, and neither do we, yet.]]>""")
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   200
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   201
parabox2("""<b>You are hereby charged</b> that on the 28th day of May, 1970, you did
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   202
willfully, unlawfully, and <i>with malice of forethought</i>, publish an
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   203
alleged English-Hungarian phrase book with intent to cause a breach
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   204
of the peace.  <u>How do you plead</u>?""", "Simple bold and italic tags")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   205
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   206
heading3("The $&lt;font&gt;$ tag")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   207
disc("""The $&lt;font&gt;$ tag can be used to change the font name,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   208
size and text color for any substring within the paragraph.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   209
Legal attributes are $size$, $face$, $name$ (which is the same as $face$),
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   210
$color$, and $fg$ (which is the same as $color$). The $name$ is
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   211
the font family name, without any 'bold' or 'italic' suffixes.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   212
Colors may be
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   213
HTML color names or a hex string encoded in a variety of ways;
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   214
see ^reportlab.lib.colors^ for the formats allowed.""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   215
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   216
parabox2("""<font face="times" color="red">
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   217
You are hereby charged</font> that on the 28th day of May, 1970, you did
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   218
willfully, unlawfully, and <font size=14>with malice of forethought</font>,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   219
publish an
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   220
alleged English-Hungarian phrase book with intent to cause a breach
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   221
of the peace.  How do you plead?""", "The $font$ tag")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   222
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   223
heading3("Superscripts and Subscripts")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   224
disc("""Superscripts and subscripts are supported with the
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   225
<![CDATA[<super> and <sub> tags, which work exactly
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   226
as you might expect.  In addition, most greek letters
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   227
can be accessed by using the <greek></greek>
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   228
tag, or with mathML entity names.]]>""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   229
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   230
##parabox2("""<greek>epsilon</greek><super><greek>iota</greek>
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   231
##<greek>pi</greek></super> = -1""", "Greek letters and subscripts")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   232
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   233
parabox2("""Equation (&alpha;): <greek>e</greek> <super><greek>ip</greek></super>  = -1""",
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
   234
         "Greek letters and superscripts")
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   235
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   236
heading3("Numbering Paragraphs and Lists")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   237
disc("""The $&lt;seq&gt;$ tag provides comprehensive support
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   238
for numbering lists, chapter headings and so on.  It acts as
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   239
an interface to the $Sequencer$ class in ^reportlab.lib.sequencer^.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   240
These are used to number headings and figures throughout this
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   241
document.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   242
You may create as many separate 'counters' as you wish, accessed
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   243
with the $id$ attribute; these will be incremented by one each
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   244
time they are accessed.  The $seqreset$ tag resets a counter.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   245
If you want it to resume from a number other than 1, use
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   246
the syntax &lt;seqreset id="mycounter" base="42"&gt;.
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   247
Let's have a go:""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   248
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   249
parabox2("""<seq id="spam"/>, <seq id="spam"/>, <seq id="spam"/>.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   250
Reset<seqreset id="spam"/>.  <seq id="spam"/>, <seq id="spam"/>,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   251
<seq id="spam"/>.""",  "Basic sequences")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   252
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   253
disc("""You can save specifying an ID by designating a counter ID
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   254
as the <i>default</i> using the &lt;seqdefault id="Counter"&gt;
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   255
tag; it will then be used whenever a counter ID
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
   256
is not specified.  This saves some typing, especially when
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   257
doing multi-level lists; you just change counter ID when
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   258
stepping in or out a level.""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   259
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   260
parabox2("""<seqdefault id="spam"/>Continued... <seq/>,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   261
<seq/>, <seq/>, <seq/>, <seq/>, <seq/>, <seq/>.""",
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   262
"The default sequence")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   263
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   264
disc("""Finally, one can access multi-level sequences using
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   265
a variation of Python string formatting and the $template$
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   266
attribute in a &lt;seq&gt; tags.  This is used to do the
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   267
captions in all of the figures, as well as the level two
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   268
headings.  The substring $%(counter)s$ extracts the current
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   269
value of a counter without incrementing it; appending a
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   270
plus sign as in $%(counter)s$ increments the counter.
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   271
The figure captions use a pattern like the one below:""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   272
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   273
parabox2("""Figure <seq template="%(Chapter)s-%(FigureNo+)s"/> - Multi-level templates""",
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   274
"Multi-level templates")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   275
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   276
disc("""We cheated a little - the real document used 'Figure',
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   277
but the text above uses 'FigureNo' - otherwise we would have
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   278
messed up our numbering!""")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   279
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   280
heading2("Bullets and Paragraph Numbering")
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   281
disc("""In addition to the three indent properties, some other
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   282
parameters are needed to correctly handle bulleted and numbered
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   283
lists.  We discuss this here because you have now seen how
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   284
to handle numbering.  A paragraph may have an optional
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   285
^bulletText^ argument passed to its constructor; alternatively,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   286
bullet text may be placed in a $<![CDATA[<bullet>..</bullet>]]>$
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   287
tag at its head.  The text will be drawn on the first line of
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   288
the paragraph, with its x origin determined by the $bulletIndent$
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   289
attribute of the style, and in the font given in the
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   290
$bulletFontName$ attribute.  For genuine bullets, a good
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   291
idea is to select the Symbol font in the style, and
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   292
use a character such as $\\267)$:""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   293
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   294
t=apply(Table,getAttrs(_bulletAttrMap))
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   295
t.setStyle([
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   296
            ('FONT',(0,0),(-1,1),'Times-Bold',10,12),
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   297
            ('FONT',(0,1),(-1,-1),'Courier',8,8),
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   298
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   299
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   300
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   301
            ])
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   302
getStory().append(t)
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   303
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   304
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - &lt;bullet&gt; attributes &amp; synonyms""")
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 356
diff changeset
   305
disc("""The &lt;bullet&gt; tag is only allowed once in a given paragraph and its use
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   306
overrides the implied bullet style and ^bulletText^ specified in the  ^Paragraph^
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   307
creation.
d96f5098af2b Pargraph & Table
rgbecker
parents: 344
diff changeset
   308
""")
344
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   309
parabox("""<bullet>\267</bullet>this is a bullet point.  Spam
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   310
spam spam spam spam spam spam spam spam spam spam spam 
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   311
spam spam spam spam spam spam spam spam spam spam """,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   312
        styleSheet['Bullet'],
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   313
        'Basic use of bullet points')
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   314
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   315
disc("""Exactly the same technique is used for numbers,
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   316
except that a sequence tag is used.  It is also possible
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   317
to put  a multi-character string in the bullet; with a deep
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   318
indent and bold bullet font, you can make a compact
dd6e41c2b0ed Paragraphs chapter pretty much complete. Fancy cover.
andy_robinson
parents: 341
diff changeset
   319
definition list.""")