<!-- partName "Part II - Advanced Features" -->

<!-- chapterName "Miscellaneous useful features" -->

<!-- sectionName "pageNumber" -->

<para>
As you'd expect from the name, this tag adds page numbers to your document.
This has nothing tricky to remember - all you have to do is put the a
<font face="Courier">&lt;pageNumber/&gt;</font> tag where you want the page number to appear.
</para>

<!-- sectionName "name and getName" -->

<para>
The <font face="Courier">&lt;name&gt;</font> tag allows you to set a variable
as you would in a programming language. You can then retrieve this to put in
another place by using the <font face="Courier">&lt;getName&gt;</font> tag. You
can do this as many or as few times as you need - so it is handy for things
like headers and footers, or for items that you see changing many times over the
life of your document such as version or revision numbers. If you set them using
a <font face="Courier">&lt;name&gt;</font> tag, you only have to revise them in one place every time they change,
rather than having to plough through the document changing them manually in each
location and inevitably missing one.
</para>

<para>
<font face="Courier">&lt;name&gt;</font> has three attributes: <font face="Courier">id</font>
and <font face="Courier">value</font> are required, but <font face="Courier">type</font> is optional.
<font face="Courier">&lt;getName&gt;</font> only has one attribute (<font face="Courier">id</font>),
and this is required so that it knows which name to "yank".
</para>

<para>
In practice, it would look something like this example:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<stylesheet>
    <initialize>
        <name id="YourVariableName"
              value="Type anything you want between these quotes..."/>
    </initialize>
</stylesheet>

<story>
    <para>
        <b><getName id="YourVariableName"/></b>
    </para>
</story>
        ]]>
</codesnippet>
<spacer length="15"/>

<para>
You can also use the <font face="Courier">&lt;name&gt;</font> tag inside the story of a document.
In this case, as well as setting the value for the variable, it is also displayed on the page
(i.e. the name has a "textual value").
</para>

<!-- sectionName "Seq, seqReset, seqChain and SeqFormat" -->

<para>
The "seq" in <font face="Courier">&lt;seq&gt;</font>, <font face="Courier">&lt;seqDefault&gt;</font> and
<font face="Courier">&lt;seqReset&gt;</font> stands for sequence. These tags are all
used for paragraph numbering (or indeed anything that requires numbering items
in a sequence, such as list items or figures and illustrations).
</para>

<para> This is how they look in use:</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<seq/>
<seqDefault id="myID"/>
<seqReset/> or <seqReset id="myID"/>
<seqChain order="id0 id1 id2...idn"/>
<seqFormat id="myID" value="i"/>
]]>
</codesnippet>
<spacer length="15"/>

<para>
Each time you call
<font face="Courier">&lt;seq/&gt;</font>,
its value is automatically incremented.
</para>
<para>
With <font face="Courier">&lt;seqReset&gt;</font>, the <font face="Courier">id</font> is an optional
attribute. However, it is still best to use it to save confusion.
</para>
<para>The
<font face="Courier">&lt;seqChain order="id0 id1 id2"/&gt;</font> tag is used to make multi sequence use easier.
When sequence
<font face="Courier">id0</font> is changed
sequence <font face="Courier">id1</font> is reset; likewise
when sequence
<font face="Courier">id1</font> is changed
sequence <font face="Courier">id2</font> is reset and so on for the identifiers in the
<font face="Courier">order</font> attribute.
</para>
<para>The tag
<font face="Courier">&lt;seqFormat id="myID" value="i"/&gt;</font>
is used to associate a numbering format to
<font face="Courier">myID</font>. The allowed values for the
<font face="Courier">value</font>
attribute are given in the table below.</para>
<blockTable colWidths="2.0cm, 4.75cm" style="simpleStyle">
<tr><td align="center" fontName="Helvetica-Bold">Value</td><td><para><b>Meaning</b></para></td></tr>
<tr><td align="center" fontName="Helvetica-Bold">1</td><td><para><b>Decimal</b></para></td></tr>
<tr><td align="center" fontName="Helvetica-Bold">i</td><td><para><b>Lowercase Roman</b></para></td></tr>
<tr><td align="center" fontName="Helvetica-Bold">I</td><td><para><b>Uppercase Roman</b></para></td></tr>
<tr><td align="center" fontName="Helvetica-Bold">a</td><td><para><b>Lowercase Alphabetic</b></para></td></tr>
<tr><td align="center" fontName="Helvetica-Bold">A</td><td><para><b>Uppercase Alphabetic</b></para></td></tr>
</blockTable>
<spacer length="10"/>
<para>
Here is an example that shows <font face="Courier">&lt;seq/&gt;</font>, <font face="Courier">&lt;seqReset&gt;</font>
and <font face="Courier">&lt;seqDefault&gt;</font> in use:
</para>

<para style="figureCaption">EXAMPLE 6</para>
<codesnippet language="xml" style="code"><![CDATA[

<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<!DOCTYPE document SYSTEM "rml.dtd">
<document filename="example_6.pdf">

    <template>
        <pageTemplate id="main">
            <frame id="first" x1="72" y1="72" width="451" height="698"/>
        </pageTemplate>
    </template>

    <stylesheet>
    </stylesheet>

    <story>
        <h1>
            seq in seq, seqDefault and seqReset
        </h1>
        <para>copied: <seq id="spam"/>, <seq id="spam"/>, <seq id="spam"/>.
            Reset<seqReset id="spam"/>.  <seq id="spam"/>, <seq id="spam"/>,
            <seq id="spam"/>.</para>
        <h2>
            <i>simple use of seq</i>
        </h2>
        <para>
            First seq: <seq/>
        </para>
        <para>
            Second seq: <seq/>
        </para>
        <spacer length="6"/>
        <para>
            <seqReset/>
            We have just done a &lt;seqReset/&gt;
        </para>
        <spacer length="6"/>
        <para>
            First seq after seqReset: <seq/>
        </para>
        <para>
            second seq after seqReset: <seq/>
        </para>
        <spacer length="6"/>
        <para>
            If you are going to use multiple seq tags, 
            you need to use the "id" attribute.
        </para>

        <h2>
            <i>Better use of seq</i>
        </h2>
        <para>
            <seqDefault id="test"/>
            We have just done a &lt;seqDefault id="test"/&gt;
        </para>
        <para>
            <seqReset id="test"/>
            We have just done a &lt;seqReset id="test"/&gt;
        </para>
        <spacer length="6"/>
        <para>
            First seq: <seq id="test"/>
        </para>
        <para>
            Second seq: <seq id="test"/>
        </para>
        <spacer length="6"/>
        <para>
            <seqReset id="test"/>
            We have just done a &lt;seqReset id="test"/&gt;
        </para>
        <spacer length="6"/>
        <para>
            First seq after seqReset: <seq id="test"/>
        </para>
        <para>
            second seq after seqReset: <seq id="test"/>
        </para>

        <h2>
            <i>Using two seqs independently</i>
        </h2>
        <para>
            <seqReset id="testOne"/>
            We have just done a &lt;seqReset id="testOne"/&gt;
        </para>
        <para>
            <seqReset id="testTwo"/>
            We have just done a &lt;seqReset id="testTwo"/&gt;
        </para>
        <spacer length="6"/>
        <para>
            First seq for testOne: <seq id="testOne"/>
        </para>
        <para>
            Second seq for testOne: <seq id="testOne"/>
        </para>
        <spacer length="6"/>
        <para>
            First seq for testTwo: <seq id="testTwo"/>
        </para>
        <para>
            Second seq for testTwo: <seq id="testTwo"/>
        </para>
        <spacer length="6"/>
        <para>
            <seqReset id="testOne"/>
            We have just done a &lt;seqReset id="testOne"/&gt;
        </para>
        <spacer length="6"/>
        <para>
            First seq after seqReset for testOne: <seq id="testOne"/>
        </para>
        <para>
            second seq after seqReset for testOne: <seq id="testOne"/>
        </para>
        <spacer length="6"/>
        <para>
            First seq after seqReset for testTwo: <seq id="testTwo"/>
        </para>
        <para>
            second seq after seqReset for testTwo: <seq id="testTwo"/>
        </para>
        <spacer length="15"/>
        <para>
            Notice how resetting testOne doesn't affect testTwo at all.
        </para>

    </story>

</document>

]]></codesnippet>


<spacer length="15"/>

<blockTable
rowHeights="18cm"
colWidths="12cm"
>
<tr><td>
<para style="h2">
seq in seq, seqDefault and seqReset
</para>
<para style="nospace">
copied: <seq id="spam"/>, <seq id="spam"/>, <seq id="spam"/>.
Reset<seqReset id="spam"/>.  <seq id="spam"/>, <seq id="spam"/>,
<seq id="spam"/>.</para>
<para style="style.h3">
<b><i>simple use of seq</i></b>
</para>
<para style="nospace">
First seq: <seq/>
</para>
<para style="nospace">
Second seq: <seq/>
</para>
<spacer length="6"/>
<para style="nospace">
<seqReset/>
We have just done a &lt;seqReset"/&gt;
</para>
<spacer length="6"/>
<para style="nospace">
First seq after seqReset: <seq/>
</para>
<para style="nospace">
second seq after seqReset: <seq/>
</para>
<spacer length="6"/>
<para>
If you are going to use multiple seq tags, you need to use the "id" attribute.
</para>

<para style="style.h3">
<b><i>Better use of seq</i></b>
</para>
<para style="nospace">
<seqDefault id="test"/>
We have just done a &lt;seqDefault id="test"/&gt;
</para>
<para style="nospace">
<seqReset id="test"/>
We have just done a &lt;seqReset id="test"/&gt;
</para>
<spacer length="6"/>
<para style="nospace">
First seq: <seq id="test"/>
</para>
<para style="nospace">
Second seq: <seq id="test"/>
</para>
<spacer length="6"/>
<para style="nospace">
<seqReset id="test"/>
We have just done a &lt;seqReset id="test"/&gt;
</para>
<spacer length="6"/>
<para style="nospace">
First seq after seqReset: <seq id="test"/>
</para>
<para>
second seq after seqReset: <seq id="test"/>
</para>

<para style="style.h3">
<b><i>Using two seqs independently</i></b>
</para>
<para style="nospace">
<seqReset id="testOne"/>
We have just done a &lt;seqReset id="testOne"/&gt;
</para>
<para style="nospace">
<seqReset id="testTwo"/>
We have just done a &lt;seqReset id="testTwo"/&gt;
</para>
<spacer length="6"/>
<para style="nospace">
First seq for testOne: <seq id="testOne"/>
</para>
<para style="nospace">
Second seq for testOne: <seq id="testOne"/>
</para>
<spacer length="6"/>
<para style="nospace">
First seq for testTwo: <seq id="testTwo"/>
</para>
<para style="nospace">
Second seq for testTwo: <seq id="testTwo"/>
</para>
<spacer length="6"/>
<para style="nospace">
<seqReset id="testOne"/>
We have just done a &lt;seqReset id="testOne"/&gt;
</para>
<spacer length="6"/>
<para style="nospace">
First seq after seqReset for testOne: <seq id="testOne"/>
</para>
<para style="nospace">
second seq after seqReset for testOne: <seq id="testOne"/>
</para>
<spacer length="6"/>
<para style="nospace">
First seq after seqReset for testTwo: <seq id="testTwo"/>
</para>
<para style="nospace">
second seq after seqReset for testTwo: <seq id="testTwo"/>
</para>
<spacer length="15"/>
<para style="nospace">
Notice how resetting testOne doesn't affect testTwo at all.
</para>
</td></tr>
</blockTable>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: The output from EXAMPLE 6
</para>

<para>
One more sophisticated use for using these tags is for multiple page counters.
If you have a document where you need different sections numbered separately
from the main body of a document (perhaps for introductory matter such as the
contents and preface of a book), this can be done with a named <font face="Courier">seq</font>
tag.
</para>
<para>
The page counter as used by the <font face="Courier">pageNumber</font> tag
is a 'unique value' which depends on the actual physical number of pages.
If rather than using a <font face="Courier">pageNumber</font> tag, you
instead use something like <font face="Courier">&lt;seq id="pageCounter"/&gt;</font>
, you have the ability to use <font face="Courier">&lt;seqReset id="pageCounter"/&gt;</font>
in between sections so that each chapter has pages numbered from the start of that chapter
rather than the start of the document. If you use a different template for each chapter, this
can then give you page numbers in the format "1-12" rather than just "12" (where you are on page 12
of the document, which is page 12 of chapter 1).
</para>

<!-- sectionName "Entities" -->
<nextFrame />
<para>
In example 6, we saw our first use of entities.
In RML, you can't use the characters "<font face="Courier">&lt;</font>", "<font face="Courier">&gt;</font>"
or "<font face="Courier">&amp;</font>" inside any display elements such as <font face="Courier">drawString</font> or
<font face="Courier">para</font>.
If you do, rml2pdf will assume that they are tags and attempt to interpret them. Since they won't be valid RML tags,
you will just end-up getting an error message along the lines of "<font face="Courier">Error: Start tag for undeclared element <i>&lt;YourNonValidTag&gt;</i></font>".
</para>

<para>
To get around this, you should use "entities".
</para>

<xpre style="style.normal">

<![CDATA[
When you need to use "<", replace it with "&lt;",
when you need to use ">;", replace it with "&gt;",
and when you need to use "&", replace it with "& amp;".

]]>
</xpre>

<!-- sectionName "Aliases" -->

<para>
Aliases allow you to assign more than one name to a paragraph style.
</para>
<para>
The alias tag has two required attributes - <font face="Courier">id</font> and
<font face="Courier">value</font>.
</para>
<para style="nospace">
Example:
</para>
<para style="programListing">
&lt;alias id="alreadyDefinedStyleName" value="myNewStyleName"/&gt;
</para>

<spacer length="15"/>

<para>
This can be useful in a number of ways.
</para>
<para>
You can give a more descriptive name to a style. So you can define a number of
paragraph styles called things like "<font face="Courier"><i>ItalicBold</i></font>"
or "<font face="Courier"><i>DesignerOneParagraphStyleTwo</i></font>" in the
<font face="Courier">stylesheet</font> for your document. You can then assign aliases to these styles
using names that describe the role they fill in your document such as
"<font face="Courier"><i>pictureCaption</i></font>",
"<font face="Courier"><i>abstract</i></font>",
"<font face="Courier"><i>acknowledgement</i></font>" and so on.
</para>
<para>
If at any point you decide to change the style for that kind of paragraph,
you can then change it in one alias rather than in every individual paragraph
that uses that style.
</para>

<!-- commented out - this currently doesn't work. -->
<!-- awaiting clarification from Aaron about this -->
<!--<para>
Aliases can also save you typing. You can assign a short alias for a long paragraph
name. More usefully, you can use an alias so that your chosen style becomes the default
style for any paragraphs that don't have a style attribute after that point. To do this you would use
something like:
</para>
<para fontName="Courier" fontSize="10">
&lt;alias id="para.default" value="myStyleName"/&gt;
</para>
-->

<!-- sectionName "CDATA -- unparsed character data" -->

<para>
<font face="Courier">CDATA</font> is a standard XML tag which
indicates to the parser (in this case rml2pdf) to ignore anything
inside the <font face="Courier">CDATA</font> section. It
shouldn't parse it or process it in any way - just display it.
</para>

<para>
A <font face="Courier">CDATA</font> section is started with the
characters "<font face="Courier">&lt;![CDATA[</font>" and is
closed off with the characters "<font face="Courier">]]&gt;</font>".
It can appear inside any flowable - though it is most useful inside
a <font face="Courier">&lt;pre&gt;</font> tag.
</para>

<para>
<font face="Courier">CDATA</font> may be useful in places where you
have large quantities of "<font face="Courier">&lt;</font>" and
"<font face="Courier">&gt;</font>" characters that you want to display
in your PDF, and that you would rather not have to convert them all to
"<font face="Courier">&amp;lt;</font>" and
"<font face="Courier">&amp;gt;</font>" entities. Quoting sections
of RML, XML, or HTML code is an example of a good place to use
<font face="Courier">CDATA</font> - if you needed to revise the code
example at a later date, you would have to convert the characters in
every tag into entities. <font face="Courier">CDATA</font> saves you
having to do this.
</para>

<para>
However, you should only use <font face="Courier">CDATA</font> when necessary.
If you are using other XML tools, they will also ignore anything inside a
<font face="Courier">CDATA</font> section.
</para>

<para style="nospace">
Example:
</para>

<condPageBreak height="90"/>
<codesnippet language="xml" style="code">
    <![CDATA[
<xpre>
    <![CDATA[
Anything could go here. <non_existant_tags/>, "&" signs.
Whatever you want. RML ignores it.
]] >
</xpre>
]]>
</codesnippet>

<!-- sectionName "Plug-ins: plugInGraphic and plugInFlowable" -->

<para>Both <font face="Courier">plugInGraphic</font>s and
<font face="Courier">plugInFlowable</font>s allow you to
use objects from outside your RML document.</para>

<para><b>plugInGraphic</b></para>
<para>
A <font face="Courier">plugInGraphic</font> identifies a function (callable) in a module which
takes a canvas and a data string as arguments and presumably draws
something on the canvas using information in the data string.
</para>
<para style="nospace">
Example:
</para>
<codesnippet language="xml" style="code">
<![CDATA[
<plugInGraphic module="mymodule" function="myfunction">data string</plugInGraphic>
]]>
</codesnippet>
<spacer length="15"/>

<para>when executed results in effectively the following execution sequence:</para>

<para style="bulletNospace">
import mymodule
</para>
<para style="bulletList">
mymodule.myfunction(canvas, "data string")
</para>
<para>
using the current canvas object.
</para>
<para>
<font face="Courier">&lt;PlugInGraphic&gt;</font> has two mandatory attributes:
<font face="Courier">module</font> and
<font face="Courier">function</font>.
It is used in the <font face="Courier">&lt;pageGraphics&gt;</font> section of
your document.
</para>

<para><b>plugInFlowable</b></para>
<para>
A <font face="Courier">plugInFlowable</font> identifies a function (callable) in a module which
takes a canvas data string as an argument and returns a flowable
object <!--(in the platypus sense)-->:
</para>
<para style="nospace">Example:</para>

<codesnippet language="xml" style="code">
<![CDATA[
<plugInFlowable module="mymodule" function="myfunction">data string</plugInFlowable>
]]>
</codesnippet>
<spacer length="15"/>

<para>
when executed results in effectively the execution sequence:
</para>
<para style="bulletNospace">
import mymodule
</para>
<para style="bulletNospace">
flowable=mymodule.myfunction("data string")
</para>
<para style="bulletList">
story.append(flowable)
</para>
<para>
using the current canvas object.
</para>
<para>
<font face="Courier">plugInFlowable</font> has two mandatory attributes:
<font face="Courier">module</font> and <font face="Courier">function</font>.
It is also used in the <font face="Courier">&lt;pageGraphics&gt;</font> section
of your document.
</para>

<!-- sectionName "Integrating with PageCatcher: catchForms, doForm and includePdfPages" -->

<para>
You can use our product PageCatcher to capture individual pages from
an external PDF file (e.g. application forms, government forms, annual
reports and so on). Extracting the required pages with PageCatcher will
most often be a one-off design-time step. Once PageCatcher has extracted
a page, it archives it in a data file as formatted form data. (The default
name for this file is "storage.data").</para>

<para>
If you have full production versions of both RML2PDF and PageCatcher you
can use the <font face="Courier">&lt;catchForms&gt;</font> tag to import
all forms from a PageCatcher storage file for use in your RML document.
</para>

<para style="nospace">Example: </para>
<para>
This example takes the form called PF0 (a page "caught" by PageCatcher and
stored in the file storage.data) and draws it into your document as a page
backdrop.
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<pageDrawing>
    <catchForms storageFile="storage.data"/>
    <doForm name="PF0"/>
</pageDrawing>
]]>
</codesnippet>
<spacer length="15"/>

<para>
The <font face="Courier">&lt;catchForms&gt;</font> tag is a drawing operation,
and can occur anywhere in your RML document where a <font face="Courier">&lt;doForm&gt;</font>
tag can occur. (For example, you can use a <font face="Courier">&lt;catchForms&gt;</font> inside
the flow of a story by using it inside an <font face="Courier">&lt;illustration&gt;</font>).
The <font face="Courier">&lt;catchForms&gt;</font> tag has one mandatory argument (storageFile)
which gives the name of the PageCatcher storage file to extract the form from.
</para>

<para>
One small point to remember is that if you are using multiple forms
from the same data file, you only need to use the actual <font
face="Courier">&lt;catchForms&gt;</font> tag <i>once</i>. To actually
put the captured data into your document, you would use multiple
instances of the <font face="Courier">&lt;doForm&gt;</font> tag.
Notice how this works in the example below:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<illustration width="451" height="698">
    <pageGraphics>
        <catchForms storageFile="samples.data"/>
        <doForm name="PF0"/>
    </pageGraphics>
</illustration>

<illustration width="451" height="698">
    <pageGraphics>
        <doForm name="PF1"/>
    </pageGraphics>
</illustration>
]]>
</codesnippet>
<spacer length="15"/>

<para>
If you do use repeated <font face="Courier">&lt;catchForms&gt;</font>
tags to point at the same data file, you will get an error message
similar to the one below.
</para>

<para>
<font face="Courier">ValueError: redefining named object: 'FormXob.PF0'</font>
</para>

<para>
If this is the case, find the places where
you are using the second and subsequent <font
face="Courier">&lt;catchForms&gt;</font> tags and delete them, leaving
only the <font face="Courier">&lt;doForm&gt;</font> tags. (Of course,
this doesn't apply to any <font
face="Courier">doForms</font> which are pointing at other
data files. They would still need their own initial <font
face="Courier">&lt;catchForms&gt;</font> tags).
</para>

<para>
[<b>Note</b>: For the <font face="Courier">&lt;catchForms&gt;</font>
tag to work, you must have PageCatcher installed. In addition, your
PageCatcher must be the full version with a .py or .pyc file. The
*.exe version of PageCatcher will <i>not</i> work with RML2PDF.
If you get the error message "ImportError: catchForms tag requires
the PageCatcher product http://www.reportlab.com", then you either
do not have PageCatcher installed, or have the wrong version].
</para>


<para><b>The includePdfPages tag</b></para>

<para>In some circumstances, you may not know how many pages there
will be in the PDF file you need to pageCatch. This is the case which
<font face="Courier">&lt;includePdfPages&gt;</font> tag was designed for.
</para>

<para>
<font face="Courier">&lt;includePdfPages&gt;</font> is a generic flowable, which
means that it can appear at any point in the story.
</para>

<para>In its simplest form, an includePdfPages tag will look like this:</para>

<codesnippet language="xml" style="code">
<![CDATA[<includePdfPages filename="mypdffile.pdf"/>
]]></codesnippet>
<spacer length="15"/>

<para>This will take the PDF file called "mypdffile.pdf", use
pageCatcher behind the scenes and include every page in the PDF file
in your output. There is also an optional "pages" attribute. This can
have either individual pages or ranges. The following are all valid
(providing the PDF file is long enough).</para>

<codesnippet language="xml" style="code">
<![CDATA[
<includePdfPages filename="mypdffile.pdf"/>
<includePdfPages filename="mypdffile.pdf" pages="1"/>
<includePdfPages filename="mypdffile.pdf" pages="1,2,3"/>
<includePdfPages filename="mypdffile.pdf" pages="2,1,1,2,2"/>
<includePdfPages filename="mypdffile.pdf" pages="1-5"/>
<includePdfPages filename="mypdffile.pdf" pages="1,2,4-5"/>]]></codesnippet>
<spacer length="15"/>

<para>
There are a number of differences between this tag and the other
PageCatcher related tags. Unlike the others, includePdfPages doesn't
require you to pre-pagecatch the file you intend to use (so saving you
an additional step). It also differs in that the imported PDF gets
drawn "over the top" of your exiting document, rather than being used
as a background underneath your existing page. So if you have a
header or footer in your page template, the included PDF page will
overwrite it.
</para>
<para><b>How includePdfPages works with templates</b></para>

<para>
When you have an includePdfPages tag in your RML file, RML outputs a
page break <i>before</i> the first new page, leaving you on the same
page as the last imported one. This allows you to do template switching:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<setNextTemplate>

    <setNextTemplate name="myIncludePagesTemplate"/>
    <includePdfPages filename="mypdffile.pdf" pages="1,2,3"/>
    <setNextTemplate name="myNormalTemplate"/>
    <nextFrame/>

    <para>
        This text appears on the next normal (non-included) page of your
        document)
    </para>
    
    ]]></codesnippet>
<spacer length="15"/>

<para>
This snippet switches to a new page template for use with your
included pages, adds in the first three pages from your PDF file,
switches back to what is presumably the template you have been using
throughout the rest of the document, and outputs a line of text into
the next "normal" page of your document. If you don't want any headers
or footers behind your PDF pages, define a page template called
something like "blank" (in the <font face="Courier">template</font>
section at the head pf your document) with a single frame and no
decoration on it and use that. If you are content for your included
pages to appear over the template you have been using on the previous
pages (if the included pages don't have any headers and footers and
have large enough margins not clash with the ones you are using in
your document, for example), then you can skip both of the <font
face="Courier">setNextTemplate</font> tags completely.
</para>

<para>
The <font face="Courier">nextFrame</font> tag is used because the
<font face="Courier">includedPdfPages</font> places you at the
<i>top</i> of the last included PDF page. This allows you to flow
paragraphs or other flowables down your last page. This may be useful
if you want to place text in a form, or use some other pre-prepared
background for your text. If all you want to do is just drop in a
pre-made page, you need this nextFrame to kick you into the next
normal page and continue with your document normally
</para>

<para>
Look in section 7.6 ("Using multiple frames") for more info on the
<font face="Courier">nextFrame</font> and <font
face="Courier">setNextTemplate</font> tags. Look at the file <font
face="Courier">test\test_016_pagecatcher.rml</font> for an example of
this tag in use.
</para>

<para>These attributes control the
<font face="Courier">&lt;includePdfPages&gt;</font> tag:
</para>
<blockTable style="simpleStyle">
<tr><td>filename</td><td><para>filename to include</para></td></tr>
<tr><td>pages</td><td><para>The page list</para></td></tr>
<tr><td>template</td><td><para>optional page template name</para></td></tr>
<tr><td>outlineText</td><td><para>optional outline text</para></td></tr>
<tr><td>outlineLevel</td><td><para>optional outline level</para></td></tr>
<tr><td>outlineClosed</td><td><para>true for closed outline</para></td></tr>
<tr><td>leadingFrame</td><td><para>(yes | no | 0 | 1 | notAtTop): no if you don't want a page throw before the first page</para></td></tr>
<tr><td>isdata</td><td><para>boolean true if the file is a pageCatcher .data file</para></td></tr>
<tr><td>orientation</td><td><para>(0 | portrait | 90 | landscape | 180 | 270 | auto) auto means use the file implied layout</para></td></tr>
</blockTable>


<!-- sectionName "Outlines" -->

<para>
It can go in either graphics or in a story. (Assigning outline levels to parts of your
document (such as paragraphs) allows you to build up a hierarchical structure for your document).
</para>

<para>
</para>

<para>
The <font face="Courier">level</font> specifies how deep in the outline the
entry appears. The default level is 0.
</para>

<para>
<font face="Courier">closed</font>, if set, hides any children of this outline entry by default.
Closed takes Boolean arguments.
</para>

<para style="nospace">Example: </para>
<codesnippet language="xml" style="code">
<![CDATA[
    <outlineAdd>First outline entry</outlineAdd>
    <outlineAdd level="1">sub entry</outlineAdd>
    <outlineAdd closed="true">Second outline entry 2</outlineAdd>
    <outlineAdd level="1">sub entry 2</outlineAdd>
]]>
</codesnippet>
<spacer length="15"/>
<para>
A note about levels: in order to add a level 3 outline entry, the previous outline
entry must be at least level 2 (2,3,4...).  In other words, you can "move back" any
number of levels, but you can only "move forward" one level at a time.
</para>

<!-- sectionName "Form field tags" -->
<!--

<condPageBreak height="144"/>
<h3>
<getName id="chapterNumber"/>.<seq id="sectionNumber"/>
Form field tags
</h3>
-->

<para>
An important class of reports contains lots of fields to be
traditionally filled in manually by users, like for application
forms and similar cases.
Sometimes though, these fields are already filled in by some
computational process and the user might only need to sign the
entire form before leaving it with a bank clerk or sending it
off to some destination.
RML supports creating both kind of reports by providing a set of
special-purpose tags to create such form elements (or fields,
widgets...) quite easily.
These tags are named <font face="Courier">&lt;checkBox&gt;</font>
<font face="Courier">&lt;textBox&gt;</font> and
<font face="Courier">&lt;letterBoxes&gt;</font> and
are described in the rest of this section.
</para>

<para>
All these form elements share a lot of features when it comes
to what they look like in the document.
They all appear as a rectangular shape with some background and
border colour, plus some width for the border itself.
They also have some sort of text label attached to this rectangle
to describe the field's purpose in the context of the report to
the human reader.
The text inside the field as well as the one in the attached label
also should have the usual properties like fontname and size and
colour.
All form field elements have a <font face="Courier">boxStyle</font>
attribute that can be used to group attribute names and values
and reuse them in many field elements with much less typing
effort.
</para>

<para>
But there are also specific features that distinguish these
form elements from each other.
A <i>checkbox</i> does not contain text, but only a cross (when
checked), and a <i>textbox</i> contains one or more lines of text
with different possible alignments, while <i>letterboxes</i> are
used for single line mono-space text with visible subcompartments
for each letter.
</para>

<para>
<b>Checkboxes</b>
</para>


<para>
By default, checkboxes have a very simple style similar to
UK bank application forms - an outer rectangle and a cross
which exactly fills it when checked.  The attributes control
the appearance.  </para>

<para>It is also possible to supply your own
pair of bitmap images which will be used instead of the default
drawing mechanism - this could be used to provide 3d effects,
tick-and-cross icons or whatever is needed.  To make use of this,
set the two attributes <font face="Courier">graphicOn</font>
and <font face="Courier">graphicOff</font> to point to two
bitmap files on the disk; these will be used in preference to
the default appearance.  Note that they will be stretched to
the boxWidth and boxHeight stated, so it is important to
set the same aspect ratio as the underlying image.  Also,
remember the printing intent - a 24 pixel bitmap drawn to
occupy a 12 point space on a form will be visibly grainy
on a good quality printer, but may be fine on an inkjet.
</para>

<para>
Because checkboxes do not contain text it can be argued that
when they are to be displayed as checked the cross' colour
should be the same as the border colour.
Equally well it can be argued that it should be the same colour
used for text in textboxes.
To provide both options checkboxes have an additional colour
attribute named <font face="Courier">checkStrokeColor</font>
which will be used for the cross instead of the border colour
if the former is provided.
</para>


<para>
Note that the label attached to a checkbox is limited to three
lines of text now and always appears at the right margin of
the box, but this might be generalised in future versions.
The label is expected to be vertically centered with the box
no matter how many lines it is composed of.
</para>

<para>
The following code creates a row of sample checkboxes providing
different values for the most relevant attributes:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<checkBox x="0cm" y="0cm" checked="0"/>

<checkBox x="1.5cm" y="0cm" checked="1"/>

<checkBox x="3cm" y="0cm"
          boxWidth="0.75cm" boxHeight="1cm"
          checked="1"/>

<checkBox x="4.5cm" y="0cm"
          boxWidth="0.75cm" boxHeight="1cm"
          lineWidth="0.1cm"
          checked="1"/>

<checkBox x="6cm" y="0cm"
          lineWidth="0.1cm"
          boxFillColor="yellow" boxStrokeColor="green"
          checked="1"/>

<checkBox x="7.5cm" y="0cm"
          lineWidth="0.1cm"
          boxFillColor="yellow" boxStrokeColor="green"
          checkStrokeColor="red"
          checked="1"/>

<checkBox x="9cm" y="0"
          line1="desc 1"
          line2="desc 2"
          checked="1"/>

<checkBox x="11.5cm" y="0"
          line1="desc 1"
          line2="desc 2"
          line3="desc 3"
          checked="1"/>
]]>
</codesnippet>


<spacer length="15"/>

<illustration width="10cm" height="1cm">
<checkBox x="0cm" y="0cm" checked="0"/>

<checkBox x="1.5cm" y="0cm" checked="1"/>

<checkBox x="3cm" y="0cm"
boxWidth="0.75cm" boxHeight="1cm"
checked="1"/>

<checkBox x="4.5cm" y="0cm"
boxWidth="0.75cm" boxHeight="1cm"
lineWidth="0.1cm"
checked="1"/>

<checkBox x="6cm" y="0cm"
lineWidth="0.1cm"
boxFillColor="yellow" boxStrokeColor="green"
checked="1"/>

<checkBox x="7.5cm" y="0cm"
lineWidth="0.1cm"
boxFillColor="yellow" boxStrokeColor="green"
checkStrokeColor="red"
checked="1"/>

<checkBox x="9cm" y="0"
line1="desc 1"
line2="desc 2"
checked="1"/>

<checkBox x="11.5cm" y="0"
line1="desc 1"
line2="desc 2"
line3="desc 3"
checked="1"/>
</illustration>

<spacer length="0.5cm"/>

<para>
<b>Textboxes</b>
</para>

<para>
A textbox contains one, but often more lines of text, like in an
address field.
(Of course, it can also contain no text at all, like for a
signature field.)
Sometimes it is not clear in advance exactly how much text will
go into one such field.
Therefore, textbox fields in RML provide a means for automatically
resizing the fontsize to shrink the contained text by exactly
what is needed to make it fit into the box.
This is a two-step process that first tries to shrink the fontsize
to make the text fit horizontally.
If that is not enough, it is further shrinked to make it also fit
vertically.
This process is controlled using the attribute
<font face="Courier">shrinkToFit</font>.
</para>

<para>
Because human readers are very sensible to reading text and get
quickly irritated when it does not feel "right", there is a default
amount of space (1 point) left between the text and any of the
borders of the box, which will be respected by the resizing
mechanism.
This is hardcoded now, but might become another attribute in the
future.
</para>

<para>
The following code creates a row of sample textboxes illustrating
different values for the most relevant attributes:
as well as the auto-resizing text feature:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<textBox x="0cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         label="labeled textbox">some text</textBox>

<textBox x="3.5cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         boxFillColor="yellow" boxStrokeColor="blue"
         label="colorful textbox">some text</textBox>

<textBox x="7cm" y="0cm"
         lineWidth="0.1cm"
         boxWidth="3cm" boxHeight="1cm"
         boxFillColor="yellow" boxStrokeColor="blue"
         label="bold textbox">some text</textBox>

<textBox x="10.5cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         lineWidth="0.1cm"
         boxFillColor="yellow" boxStrokeColor="blue"
         fontName="Times-Bold"
         fontSize="14"
         label="textfancy textbox">some text</textBox>
]]>
</codesnippet>

<illustration width="18cm" height="2cm">
<textBox x="0cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
label="labeled textbox">some text</textBox>

<textBox x="3.5cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="colorful textbox">some text</textBox>

<textBox x="7cm" y="0cm"
lineWidth="0.1cm"
boxWidth="3cm" boxHeight="1cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="bold textbox">some text</textBox>

<textBox x="10.5cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
lineWidth="0.1cm"
boxFillColor="yellow" boxStrokeColor="blue"
fontName="Times-Bold"
fontSize="14"
label="textfancy textbox">some text</textBox>
</illustration>

<spacer length="0.5cm"/>

<para>
The following code creates a row of sample textboxes illustrating
the auto-resizing text feature:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<textBox x="0cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         fontSize="14"
         label="no resizing">some text</textBox>

<textBox x="3.5cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         fontSize="14"
         label="horiz. resizing">some more text</textBox>

<textBox x="7cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         shrinkToFit="1"
         fontSize="14"
         label="vert. resizing">some text
    some text
    some text</textBox>

<textBox x="10.5cm" y="0cm"
         boxWidth="3cm" boxHeight="1cm"
         shrinkToFit="1"
         fontSize="14"
         label="horiz./vert. resizing">some more text
    some text
    some text
    some text</textBox>
]]>
</codesnippet>

<illustration width="18cm" height="2cm">
<textBox x="0cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
fontSize="14"
label="no resizing">some text</textBox>

<textBox x="3.5cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
fontSize="14"
label="horiz. resizing">some more text</textBox>

<textBox x="7cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
shrinkToFit="1"
fontSize="14"
label="vert. resizing">some text
some text
some text</textBox>

<textBox x="10.5cm" y="0cm"
boxWidth="3cm" boxHeight="1cm"
shrinkToFit="1"
fontSize="14"
label="horiz./vert. resizing">some more text
some text
some text
some text</textBox>
</illustration>

<spacer length="0.5cm"/>

<condPageBreak height="144"/>
<para>
<b>Letterboxes</b>
</para>

<para>
Letterboxes are intended for single-line text fields where each
letter is contained in a subcell, clearly seperated from
neighbouring cells.
This is often seen on official forms where people are expected
to write letters of a word at predefined positions.
RML provides such letterboxes, too, and they behave mostly
like textboxes, but show some significant differences, too.
</para>

<para>
Usually, the overall width of a form field element is defined by
the mandatory <font face="Courier">boxWidth</font> attribute.
For letterboxes, though, this is an optional attribute and
specifies the width of a <i>subcell</i> containing one letter.
The resulting width of the entire box is defined as a multiple
of that <font face="Courier">boxWidth</font> attribute with another
one named <font face="Courier">count</font>, which is a mandatory
attribute.
</para>

<para>
The following code creates a row of sample letterboxes showing
basic attributes:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<letterBoxes x="0cm" y="7.5cm"
             count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="6cm"
             count="12">more letterboxes</letterBoxes>

<letterBoxes x="0cm" y="4.5cm"
             boxWidth="0.75cm"
             count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="3cm"
             lineWidth="0.1cm"
             boxFillColor="yellow" boxStrokeColor="blue"
             label="some label"
             count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="1.5cm"
             lineWidth="0.1cm"
             boxFillColor="yellow" boxStrokeColor="blue"
             label="some label"
             fontName="Courier-Bold"
             fontSize="14"
             count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="0cm"
             lineWidth="0.1cm"
             boxWidth="0.75cm" boxHeight="0.75cm"
             boxFillColor="yellow" boxStrokeColor="blue"
             label="some label"
             fontName="Times-Bold"
             fontSize="14"
             count="12">letterboxes</letterBoxes>
]]>
</codesnippet>

<spacer length="0.25cm"/>

<illustration width="15cm" height="8.5cm">
<letterBoxes x="0cm" y="7.5cm"
count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="6cm"
count="12">more letterboxes</letterBoxes>

<letterBoxes x="0cm" y="4.5cm"
boxWidth="0.75cm"
count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="3cm"
lineWidth="0.1cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="some label"
count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="1.5cm"
lineWidth="0.1cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="some label"
fontName="Courier-Bold"
fontSize="14"
count="12">letterboxes</letterBoxes>

<letterBoxes x="0cm" y="0cm"
lineWidth="0.1cm"
boxWidth="0.75cm" boxHeight="0.75cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="some label"
fontName="Times-Bold"
fontSize="14"
count="12">letterboxes</letterBoxes>
</illustration>

<spacer length="0.5cm"/>

<para>
There may also be instances where you want obvious dividers between
each subcell, but you don't want entirely separate boxes. Letterboxes
have something that allows for this - the optional <font
face="Courier">combHeight</font> attribute.
</para>

<para>
In a 'standard' letterBoxes element (ie one where the combHeight isn't
specified), the divider between each individual subcell is a line
which fills the whole height of the letterBoxes box. If you specify
the combHeight, you can vary the height of this line. This attribute
must be a number between zero and one, where "0" means no divider at
all and "1" means one that is the whole height of the letterboxes
element (and therefore "0.25" is a quarter of the height and so on).
</para>

<para>
The following code creates a row of sample letterboxes showing the
combHeight attribute in use:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<letterBoxes x="0cm" y="0cm"
             combHeight="0"
             count="4">comb</letterBoxes>

<letterBoxes x="3.75cm" y="0cm"
             combHeight="0.25"
             count="4">comb</letterBoxes>

<letterBoxes x="7.5cm" y="0cm"
             combHeight="1"
             count="4">comb</letterBoxes>


<letterBoxes x="11.25cm" y="0cm"
             lineWidth="0.1cm"
             boxWidth="0.75cm" boxHeight="0.75cm"
             boxFillColor="yellow" boxStrokeColor="blue"
             label="combHeight"
             fontName="Times-Bold"
             fontSize="14"
             combHeight="0.5"
             count="4">comb</letterBoxes>
]]>
</codesnippet>

<spacer length="0.25cm"/>

<illustration width="15cm" height="33.5">

<letterBoxes x="0cm" y="0cm"
combHeight="0"
count="4">comb</letterBoxes>

<letterBoxes x="3.75cm" y="0cm"
combHeight="0.25"
count="4">comb</letterBoxes>

<letterBoxes x="7.5cm" y="0cm"
combHeight="1"
count="4">comb</letterBoxes>

<letterBoxes x="11.25cm" y="0cm"
lineWidth="0.1cm"
boxWidth="0.75cm" boxHeight="0.75cm"
boxFillColor="yellow" boxStrokeColor="blue"
label="combHeight"
fontName="Times-Bold"
fontSize="14"
combHeight="0.5"
count="4">comb</letterBoxes>

</illustration>

<spacer length="0.5cm"/>

<condPageBreak height="144"/>
<para>
<i>Using styles with form field elements</i>
</para>

<para>
As we've already mentioned, <font face="Courier">checkBox</font>,
<font face="Courier">textBox</font> and <font face="Courier">letterBoxes</font> all allow you to
re-use styles in a similar way to the way you can re-use styles with
paragraphs with the <font face="Courier">boxStyle</font> tag. Like the other style
tags (<font face="Courier">paraStyle</font> and <font face="Courier">blockTableStyle</font>),
<font face="Courier">boxStyle</font> lives in the <font face="Courier">stylesheet</font> section,
near the start of your document.
</para>

<para><font face="Courier">boxStyle</font> style can have the following attributes:</para>

<para style="nospace">
<i>name:</i>
</para><para>
This is the required attribute which allows you to refer this style by name.
</para>

<para style="nospace">
<i>alias:</i>
</para><para>
An optional attribute which allows you to refer to your style by another name.
</para>

<para style="nospace">
<i>parent:</i>
</para><para>
If this is supplied, it must refer to the name of another style. This
style with then inherit from the style named.
</para>

<para style="nospace">
<i>fontName:</i>
</para><para>
An optional attribute, this refers to the font to be used for the main contents of
letterboxes or a textbox - it is ignored for checkBoxes.
</para>

<para style="nospace">
<i>fontSize:</i>
</para><para>
This optional attribute sets the size for the main contents of
letterboxes or a textbox - it is ignored for checkBoxes.
</para>

<para style="nospace">
<i>alignment:</i>
</para><para>
For letterboxes or a textbox, this optional attribute sets the
alignment of the contents of the box. It may be either
<font face="Courier">LEFT</font>,
<font face="Courier">RIGHT</font>,
<font face="Courier">CENTER</font> or
<font face="Courier">CENTRE</font>. It is ignored for checkBoxes.
</para>

<para style="nospace">
<i>textColor:</i>
</para><para>An optional attribute that sets the colour for the main contents in the letterboxes or textbox.</para>

<para style="nospace">
<i>labelFontName:</i>
</para><para>The (optional) tag specifying the font to be used for the
label of the letterboxes, textbox or checkBox.</para>

<para style="nospace">
<i>labelFontSize:</i>
</para><para>The (optional) tag specifying the size of the font to be
used for the label of the letterboxes, textbox or checkBox.</para>

<para style="nospace">
<i>labelAlignment:</i>
</para><para>The (optional) specifying the alignment of the label - may be
<font face="Courier">LEFT</font>,
<font face="Courier">RIGHT</font>,
<font face="Courier">CENTER</font> or
<font face="Courier">CENTRE</font></para>

<para style="nospace">
<i>labelTextColor:</i>
</para><para>An optional attribute specifying the colour to be used
for the text of the label of an textBox, letterBox or checkBox.</para>

<para style="nospace">
<i>boxFillColor:</i>
</para><para>An optional tag specifying the colour to be used for the
background for a textBox, letterBox or checkBox.</para>

<para style="nospace">
<i>boxStrokeColor:</i>
</para><para>An optional tag specifying the colour to be used for the
lines making up a textBox, letterBox or checkBox.</para>

<para style="nospace">
<i>cellWidth:</i>
</para><para>An optional tag, specifying the width of a "cell" in a
form element. Must be a measurment, but may '<font face="Courier">in</font>',
'<font face="Courier">cm</font>', '<font face="Courier">mm</font>'or
'<font face="Courier">pt</font>' - see the section on  'Coordinates and measurements'
for more details on measurements.
</para>

<para style="nospace">
<i>cellHeight:</i>
</para><para>An optional tag, specifying the width of a "cell" in a
form element. Must be a measurment, but may '<font face="Courier">in</font>',
'<font face="Courier">cm</font>', '<font face="Courier">mm</font>'or
'<font face="Courier">pt</font>'</para>


<spacer length="15"/>

<para>
<b>Some Examples</b>
</para>

<para>As an example of them in use, let's set up two boxStyles, and see
what effect they have on letterBoxes, textBoxes and a checkBox.
</para>

<para>Firstly, the boxStyles:</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<boxStyle name="special1"
          labelFontName="Helvetica"
          fontSize="10"
          alignment="RIGHT"
          textColor="red"
          fontName="Helvetica"
          labelFontSize="10"
          labelAlignment="RIGHT"
          labelTextColor="blue"
          boxStrokeColor="red"
          boxFillColor="pink"/>

<boxStyle name="special2"
          parent="special1"
          fontName="Courier"
          fontSize="12"
          textColor="green"
          labelFontName="Courier"
          labelFontSize="12"
          labelTextColor="green"
          boxFillColor="yellow"
          boxStrokeColor="red"/>
]]>
</codesnippet>

<spacer length="15"/>

<para>With the style 'special1':</para>

<illustration width="15cm" height="1cm">
<letterBoxes style="special1" x="0" y="0"
count="12" label='style="special1"'>letterBoxes</letterBoxes>

<textBox style="special1" x="200" y="0"
boxWidth="100" boxHeight="18" label='"style="special1"'>textBox</textBox>

<checkBox style="special1" x="338" y="0"
line1='"style="special1"'/>
</illustration>

<spacer length="15"/>

<para>And with the style 'special2':</para>
<illustration width="15cm" height="1cm">
<letterBoxes style="special2" x="0" y="0"
count="12" label='style="special2"'>letterBoxes</letterBoxes>

<textBox style="special2" x="200" y="0"
boxWidth="110" boxHeight="18" label='"style="special2"'>textBox</textBox>

<checkBox style="special2" x="338" y="0"
line1='"style="special2"'/>
</illustration>


<spacer length="30"/>
<condPageBreak height="144"/>
<para>
<i>Barcodes</i>
</para>

<para>
One other tag that may often find use on forms is the <font face="Courier">barCode</font> tag.
As its name implies, this creates a barcode in one of a number of
different symbologies.
</para>

<para>The three attributes you need to supply for this tag are
<font face="Courier">x</font> and <font face="Courier">y</font> to position it on the page and
<font face="Courier">code</font> to inform rml2pdf which form of barcode you require.
</para>

<para>This is a brief example of what a barcode tag looks like in use, and what it actually produces:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<barCode x="1cm" y="0" code="Code11">123456</barCode>
]]>
</codesnippet>

<illustration width="8cm" height="1cm">
<barCode x="7cm" y="0" code="Code11">123456</barCode>
</illustration>

<spacer length="3"/>
<para style="figureCaption">
Figure <seq id="figureNumber"/>: The "Code11" barcode
</para>
<spacer length="12"/>

<para>This table shows you the allowed names for the <font face="Courier">code</font>
attribute, along with an example of the barcode produced.</para>

<blockTable colWidths="3.5cm, 3.5cm, 4.75cm" style="simpleStyle">

<tr>
<td><para>Type</para></td>
<td><para>Code attribute to use</para></td>
<td><para>Example barcode</para></td>
</tr>

<tr>
<td><para>Codabar</para></td>
<td><para><font face="Courier">Codabar</font></para></td>
<td>
<illustration width="10cm" height="0.75cm">
<barCode x="0.25cm" y="0" code="Codabar">123456</barCode>
</illustration>
</td>
</tr>

<tr>
<td><para>Code 11</para></td>
<td><para><font face="Courier">Code11</font></para></td>
<td>
<illustration width="10cm" height="0.75cm">
<barCode x="0.25cm" y="0" code="Code11">123456</barCode>
</illustration>
</td>
</tr>

<tr>
<td><para>Code 128</para></td>
<td><para><font face="Courier">Code128</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="Code128">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>Code 39</para></td>
<td><para><font face="Courier">Standard39</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="Standard39">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>Code93</para></td>
<td><para><font face="Courier">Standard93</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="Standard93">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>I2of5</para></td>
<td><para><font face="Courier">I2of5</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="0.25cm" y="0" code="I2of5">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>Extended Code 39</para></td>
<td><para><font face="Courier">Extended39</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="Extended39">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>Extended Code93</para></td>
<td><para><font face="Courier">Extended93</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="Extended93">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>MSI</para></td>
<td><para><font face="Courier">MSI</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="-0.25cm" y="0" code="MSI">123456</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>USPS FIM</para></td>
<td><para><font face="Courier">FIM</font></para></td>
<td>
<illustration width="10cm" height="2cm">
<barCode x="0" y="0" code="FIM">A</barCode>
</illustration>
</td>
</tr>
<tr>
<td><para>USPS POSTNET</para></td>
<td><para><font face="Courier">POSTNET</font></para></td>
<td>
<illustration width="10cm" height="1cm">
<barCode x="0" y="0" code="POSTNET">123456</barCode>
</illustration>
</td>
</tr>
</blockTable>

<!-- sectionName "Colorspace Checking" -->

<para>
RML v2.5 supports a way to ensure the consistent enforcement of color models within a document.  For more information on this
topic, and examples of when you might want to use different scenarios, please refer to the 'Printing' chapter later
in this document.
</para>
<para>
RGB, CMYK and the use of 'spot colors' such as Pantone can be allowed or disallowed using
the 'colorSpace' parameter to the document tag, which can be set to the following values:
</para>

<para style="bulletList" bulletText="l">MIXED - The default. As in RML versions before 2.5, rgb, cmyk, spot colors and 'named' colors can all be used.</para>
<para style="bulletList" bulletText="l">RGB - Permits only the use of RGB colour values.</para>
<para style="bulletList" bulletText="l">CMYK - Permits only the use of CMYK colour values.</para>
<para style="bulletList" bulletText="l">SEP - 'Spot Colors' only - all colour values must define a 'spotName' value.</para>
<para style="bulletList" bulletText="l">SEP_BLACK - spot colors, plus shades of grey only.</para>
<para style="bulletList" bulletText="l">SEP_CMYK - spot colors plus cmyk values only.</para>

<para>
The use of any color definitions outside the specified type will result in an exception when you try to
compile the document, thereby ensuring that, for instance, a document can be produced for CMYK or spot color
printing without containing any RGB color definitions.
</para>

<para>
Any 'named' colours (see appendix A or 'reportlab/lib/colors.py') for black or shades of grey are automatically
converted to cmyk/rgb as required.  So you can use lowercase 'black' as a color in all models except 'SEP'.  However, any other
RML 'named' colors such as 'aqua' or 'hotpink' will not be converted.
</para>
