<!-- chapterName "Advanced text" -->

<!-- sectionName "Title" -->

<para>
The <font face="Courier">&lt;title&gt;</font> tag sets the title for a document,
or a section of a document, and displays it on the page. By default, this is set
in a larger typeface than the body text (in a similar way that headers are).
You can change the way a title is set by setting a style called
<font face="Courier">style.Title</font> (in the <font face="Courier">stylesheet</font> section of
your document).
</para>
<para>
[<b>Note:</b> This tag does <i>not</i> affect what is displayed in the "title bar"
at the top of a document.]
</para>
<para>Example:</para>


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

<stylesheet>
    <paraStyle name="style.Title"
               fontName="Courier-Bold"
               fontSize="36"
               leading="44"
               />
</stylesheet>

<story>
    <title>This is the Title</title>
    <para>
        And it should be set in 36 pt Courier Bold.
    </para>
</story>

]]>
</codesnippet>
<spacer length="15"/>

<!-- sectionName "Headings -- h1, h2, h3" -->

<para>
Headings are also handled in the same way as in HTML. The most important heading
level has its text enclosed by <font face="Courier">&lt;h1&gt;</font> and
<font face="Courier">&lt;/h1&gt;</font> tags, and less important sub-headings
use the <font face="Courier">&lt;h2&gt;&lt;/h2&gt;</font> and
<font face="Courier">&lt;h3&gt;&lt;/h3&gt;</font> tags in the same way.
</para>

<!-- sectionName "Paragraphs and paragraph styles" -->

<para>
As well as explicitly placing a piece of text into a certain position on a page
using the <font face="Courier">drawString</font> commands, RML also allows you
to use paragraphs of text. Paragraphs are <i>flowables</i>. This means that you
don't need to tell RML exactly where every line is going to go on the page -
you let rml2pdf worry about that.
</para>

<para>
To do this you place your text inside the <font face="Courier">story</font> section of
an RML document, and use the <font face="Courier">&lt;para&gt;</font> and
<font face="Courier">&lt;/para&gt;</font> tags to tell the parser where each paragraph
starts and ends.
</para>

<para>
As well as delineating where paragraphs begin and end, the <font face="Courier">&lt;para&gt;</font>
tag can also have a number of optional attributes:
</para>

<para style="nospace">
<i>style:</i>
</para><para>
If you have set up a style in the stylesheet section of a document, you can refer
to them by name by using the <font face="Courier">style</font> attribute. For example,
if you have defined a style called <font face="Courier"><i>Normal</i></font>, you can
have your paragraph appear in that style by using
<font face="Courier">&lt;para style="<i>Normal</i>"&gt;</font>.
</para>

<para style="nospace">
<i>alignment:</i>
</para><para>
How the text is aligned within the paragraph. It can be <font face="Courier">LEFT</font>,
<font face="Courier">RIGHT</font>,
<font face="Courier">CENTER</font> (or <font face="Courier">CENTRE</font>) or
<font face="Courier">JUSTIFY</font>.
</para>

<para style="nospace">
<i>fontName, fontSize:</i>
</para><para>
<font face="Courier">fontName</font> and <font face="Courier">fontSize</font> set the name and size
of the font that you want this paragraph displayed in. (This can often be better done using the
<font face="Courier">&lt;paraStyle&gt;</font> tag inside a <font face="Courier">&lt;stylesheet&gt;</font>,
and then using the <font face="Courier">&lt;style&gt;</font> tag to apply it to that paragraph).
Example:
<font face="Courier">&lt;para fontName="Helvetica" fontSize="12"&gt;</font>
</para>

<para style="nospace">
<i>leading:</i>
</para><para>
<font face="Courier">leading</font> is used  is used to alter the space between lines.
In RML, it is expressed as the height of a line <i>PLUS</i> the space between lines. So
if you are using 10 point font, a leading of 15 will give you a space between lines of
5 points. If you use a number that is <i>smaller</i> than the size of font you are
using, the lines will overlap.
</para>

<para style="nospace">
<i>leftIndent, rightIndent:</i>
</para><para>
<font face="Courier">leftIndent</font> and <font face="Courier">rightIndent</font> apply
space to the left or right of a paragraph which is in addition to any margin you have set.
</para>

<para style="nospace">
<i>firstLineIndent:</i>
</para><para>
<font face="Courier">firstLineIndent</font> is used when you want your paragraph to have an
additional indent on the first line - on top of anything set with
<font face="Courier">leftIndent</font>.
</para>

<para style="nospace">
<i>spaceBefore, spaceAfter:</i>
</para><para>
<font face="Courier">spaceBefore</font> and <font face="Courier">spaceAfter</font>, as you would
expect, set the spacing before a paragraph or after it.
</para>

<para style="nospace">
<i>textColor:</i>
</para><para>
This sets the color to be used in displaying a paragraph.
</para>

<para style="nospace">
<i>bulletText, bulletColor, bulletFontName, bulletFontSize, bulletIndent:</i>
</para><para>
These are all used to set the characteristics for any bullets to be used in the
paragraph.
</para>

<para>
Inside the story, you can also do a number of things that you can't do with the
<font face="Courier">drawString</font> commands. For a start, you can use bold,
italics and underlining. If you are familiar with HTML, you will recognize these tags -
<font face="Courier">&lt;i&gt;</font> and <font face="Courier">&lt;/i&gt;</font>
start and stop italics,
<font face="Courier">&lt;b&gt;</font> and <font face="Courier">&lt;/b&gt;</font> start and stop the text being set as bold, and
<font face="Courier">&lt;u&gt;</font> and <font face="Courier">&lt;/u&gt;</font> start and stop underlining.
</para>

<!-- sectionName "The font tag" -->

<para>
You can also explicitly set the font using the <font face="Courier">&lt;font&gt;</font>
tag. This has the optional attributes of <font face="Courier">face</font>,
<font face="Courier">color</font>, and <font face="Courier">size</font> which are all
pretty self-explanatory. You need to use a <font face="Courier">&lt;/font&gt;</font>
tag to close this before the end of the paragraph.
Example:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<font face="Courier" color="crimson">This is courier in crimson!</font>
]]>
</codesnippet>
<spacer length="15"/>

<para style="nospace">That example produces this line of text: </para>
<para><font face="Courier" color="crimson">This is courier in crimson!</font></para>

<!-- sectionName "Superscripts and subscripts" -->

<para>
Another thing you can do inside the story is using superscripts and subscripts. You
do this with the <font face="Courier">&lt;super&gt;&lt;/super&gt;</font> and
<font face="Courier">&lt;sub&gt;&lt;/sub&gt;</font> tags.
(Superscript is where the text is raised up on the line such as in the mathematical symbol
for squared or cubed, and subscript is where it is lowered relative to the rest of the line
in the same way). The &lt;super&gt; tag can also be called &lt;sup&gt;. Thses tags have optional
attributes <i>rise</i> to set the baseline shift (negatively for &lt;sub&gt;) and <i>size</i> which
sets the font size to use in the tag. The default <i>rise</i> is 50% of the font size and the default size is 
the existing font size - min(2,20% of existing font size).
Example:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<para>
    <sub>This is subscript.</sub>
    This is normal text.
    <super>This is superscript.</super>
</para>
]]>
</codesnippet>
<spacer length="15"/>

<para>That example produces this:</para>
<para>
<sub>This is subscript.</sub>
This is normal text.
<super>This is superscript.</super>
<br/>whereas this example:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<para>
    <sub size="6" rise="5">This is subscript.</sub>
    This is normal text.
    <super size="6" rise="5">This is superscript.</super>
</para>
]]>
</codesnippet>
<spacer length="15"/>

<para>produces this:</para>
<para>
    <sub size="6" rise="5">This is subscript.</sub>
    This is normal text.
    <super size="6" rise="5">This is superscript.</super>
</para>

<!-- sectionName "Lists" -->

<para>RML supports ordered and unordered lists, using the tags &lt;ol&gt; &lt;ul&gt; and &lt;li&gt;.  They work in a similar way to their HTML equivalents.  A list item can be any normal flowable element but there can be only one such item within a pair of list item tags.  Lists can be nested.</para>

<para>WARNING:  The contents of a list are flowable objects, and the list itself does not know what font sizes or spacing you will use in the enclosed paragraphs.  Therefore, if you want to get normal typography, it's very important to define a &lt;listStyle&gt; with font names, size and spacing matching that of the &lt;paraStyle&gt; you use for the enclosed text.</para>

<para>You should also be aware that RML's &lt;para&gt; tag already has a flexible feature named the `bullet` which can provide bulleted, numbered and definition lists which match the corresponding text.  In general lists should only be used when you are transforming in a mapping from HTML, or when you need to place arbitrary flowables such as tables or images in the body of a list.</para>


<para>Lists and list items can be styled using tag attributes or with &lt;listStyle&gt; tags in the stylesheet section.  See the rml.dtd for the full list of attributes on the &lt;ul&gt; &lt;ol&gt; and &lt;li&gt; tags using LIST_MAIN_ATTRS.</para>

<para>In ordered lists, you can use the following types of enumeration in the bulletType or start attributes:</para>
<para style="bulletNospace" bulletText="">'I': Roman numerals (capitals)</para>
<para style="bulletNospace" bulletText="">'i': Roman numerals (lower case)</para>
<para style="bulletNospace" bulletText="">'1': Arabic numerals</para>
<para style="bulletNospace" bulletText="">'A': Capital letters</para>
<para style="bulletNospace" bulletText="">'a': Lowercase letters</para>

<para spaceBefore="10">For unordered lists, bulletType must be set to 'bullet'</para>

<para>Unordered lists can use bullet types of the following shapes by setting the 'start' attribute in &lt;ul&gt; or the 'value' attribute in &lt;li&gt; tags:</para>
<para style="bulletNospace" bulletText="">bulletchar</para>
<para style="bulletNospace" bulletText="">square</para>
<para style="bulletNospace" bulletText="">disc</para>
<para style="bulletNospace" bulletText="">diamond</para>
<para style="bulletNospace" bulletText="">diamondwx</para>
<para style="bulletNospace" bulletText="">circle</para>
<para style="bulletNospace" bulletText="">blackstar</para>
<para style="bulletNospace" bulletText="">squarers</para>
<para style="bulletNospace" bulletText="">arrowhead</para>


<para spaceBefore="10">Alternatively any non-whitespace character can be used as a bullet.</para>
<para>As a final possibility blank separated strings of the possible starts can be used to indicated that automatic depth changes should be attempted.</para>
<para spaceBefore="10">The size, colour and position (indenting, space before/after etc.) of bullets and enumerations can be adjusted with the relevant tag attributes.  List item attributes override the attributes on &lt;ol&gt; or &lt;ul&gt; tags.</para>

<para>Definition lists are not yet implemented.</para>

<para>A simple example of nested ordered/unordered lists:</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<story>
    <ol bulletColor="red" bulletFontName="Times-Roman">
        <li bulletColor="blue" bulletFontName="Helvetica">
            <para>
                 Welcome to RML 1
            </para>
        </li>
        <li>
            <ul bulletColor="red" bulletFontName="Times-Roman" bulletFontSize="5" rightIndent="10">
                <li bulletColor="blue" bulletFontName="Helvetica">
                    <para>
                         unordered 1
                    </para>
                </li>
                <li>
                    <para>
                         unordered 2
                    </para>
                </li>
            </ul>
        </li>
    </ol>
</story>
]]>
</codesnippet>
<spacer length="15"/>

<para>For more examples of how to use lists see 'test_046_lists.rml' in '/rlextra/rml2pdf/test/'.</para>



<!-- sectionName "Using multiple frames" -->

<para>
If you have split your page into more than one frame, you can flow text between
frames. To do this you use the
<font face="Courier">&lt;nextFrame/&gt;</font> tag.
This is an "empty" or "singleton" tag - it  doesn't take any
content.
Put in <font face="Courier">&lt;nextFrame/&gt;</font> and
your text will continue into the next frame.
It should appear <i>outside</i> your
paragraphs - between one <font face="Courier">&lt;/para&gt;</font> and the next
<font face="Courier">&lt;para&gt;</font> tag.
An optional
<font face="Courier">name</font> attribute can be used to specify the name or index of the frame which you wish to switch to.
</para>
<para>You can control the automatic switch of frames by using the
<font face="Courier">&lt;setNextFrame/&gt;</font> tag.
The required
<font face="Courier">name</font> attribute can be used to specify the name or index of the frame which you wish to switch to.
The
<font face="Courier">&lt;setNextFrame/&gt;</font> tag
is an "empty" or "singleton" tag - it  doesn't take any
content.
Put in <font face="Courier">&lt;setNextFrame name="F5"/&gt;</font> and
your text will flow into the frame specified.
It should appear <i>outside</i> your
paragraphs - between one <font face="Courier">&lt;/para&gt;</font> and the next
<font face="Courier">&lt;para&gt;</font> tag.
</para>

<para>
If you have defined more than one kind of template (by using
<font face="Courier">&lt;pageTemplate&gt;</font>
in the template section at the head of the RML document), you can also force RML into
using a new template for the next page. You do this by using the
<font face="Courier">&lt;setNextTemplate&gt;</font> tag. This tag has only one
attribute - the mandatory one of <font face="Courier">name</font>, which tells
RML which template it should use.
</para>

<para>
In practice, you would usually set the next template and then use a
<font face="Courier">nextFrame</font>:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<setNextTemplate name="yetAnotherTemplate"/>
<nextFrame/>
]]>
</codesnippet>
<spacer length="15"/>

<!-- sectionName "Preformated text -- pre and xpre" -->

<para>
One tag that is also a flowable, but that can't be used inside the
<font face="Courier">&lt;para&gt;&lt;/para&gt;</font> tags is
<font face="Courier">&lt;pre&gt;</font>. Just as in HTML, the
<font face="Courier">&lt;pre&gt;</font> tag denotes pre-formatted text. It displays text
exactly as you typed it, with the line breaks exactly where you put them and no line-wrapping.
If you want to keep any formatting in your text (such as tabs and extra whitespace), enclose it
in <font face="Courier">&lt;pre&gt;</font> tags rather than <font face="Courier">&lt;para&gt;</font> tags.
</para>

<para>
You can also pass a style to the <font face="Courier">&lt;pre&gt;</font> tag. If you don't use the optional style
attribute, anything between the <font face="Courier">&lt;pre&gt;</font> tag and the
<font face="Courier">&lt;/pre&gt;</font> tag will appear in the default style for pre-formatted
text. This uses a fixed width "typewriter" font (such as courier), and is useful for things such as program
listings, but may not be what you want for your quotation or whatever. If you have already defined a style
(in the <font face="Courier">stylesheet</font> section of your RML document), then you can make the
<font face="Courier">&lt;pre&gt;</font> tag use this for your pre-formatted text.
</para>

<para >
Example:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<xpre style="myStyle">
    this is pre-formatted text.
</xpre>
]]>
</codesnippet>
<spacer length="15"/>

<para>
The {{code}}xpre{{endcode}} is similar to the {{code}}pre{{endcode}} tag in that it preserves line breaks
where they are placed in the text, but {{code}}xpre{{endcode}} also permits paragraph annotations such as
bold face and italics and font changes.  For example, the following mark-up
</para>
<xpre>
<![CDATA[
<xpre>
this is an <i>xpre</i> <b>example</b>
<font color="red">including red text!</font>
</xpre>
]]>
</xpre>
<para>
generates the following text
</para>
<xpre>
this is an <i>xpre</i> <b>example</b>
<font color="red">including red text!</font>
</xpre>


<!-- sectionName "Greek letters" -->

<para>
The <font face="Courier">&lt;greek&gt;</font> tag is used for producing Greek letters in RML.
This is of most use for equations and formulae.
</para>

<para>
Example:
</para>

<para>
In physics, Planck's formula for black body radiation can be expressed as:
</para>

<para alignment="CENTER">
R&lambda;=(c/4) (8&pi;/&lambda;<super>4</super>)
[ (hc/&lambda;) 1/e<super>hc/&lambda;kT</super>-1 ]
</para>

<para>
In RML, this is expressed as:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
R<greek>l</greek>=(c/4) (8<greek>p</greek>/<greek>l</greek><super>4</super>)
[ (hc/<greek>l</greek>) 1/e<super>hc/<greek>l</greek>kT</super>-1 ]
]]>
</codesnippet>
<spacer length="15"/>

<para>
For a table of the Greek letters used by the <font face="Courier">&lt;greek&gt;</font>
tag and their representations in RML, look in Appendix C at the end of this manual.
</para>

<para>
This next example show features from several of the commands describes in the
previous sections; such as the use of <font face="Courier">frame</font>s, the options
to the <font face="Courier">template</font> tag, <font face="Courier">stylesheets</font>,
and so on. See the next section for information on using
the <font face="Courier">&lt;name&gt;</font> and
<font face="Courier">&lt;getName&gt;</font> tags.
</para>

<para style="figureCaption">EXAMPLE 5</para>
<para style="figureCaption">EXAMPLE 4</para>
<codesnippet language="xml" style="code-small"><![CDATA[
{{safeTopInclude('example_5.rml')}}
]]></codesnippet>

<spacer length="15"/>

<illustration width="228" height="333">
<image file="images/Example_5a.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Output from EXAMPLE 5
</para>

<!-- sectionName "Asian Fonts" -->
<para>
RML supports all of Adobe's Asian Font Packs. You can display text in Japanese,
Traditional and Simplified Chinese and Korean using two different techniques.
</para>

<para>The most robust technique is to include the standard Asian fonts
Adobe specifies for use with Acrobat Reader.  These will already be installed
on the end user's machine if they have a localized copy of Acrobat Reader,
or may be downloaded in the free "Asian Font Packs" from Adobe's site.  In
these cases there is no need to embed any fonts or to have any special
software on the server. The first stage is to declare the fonts you need in
the optional 'docinit' tag at the beginning of the document as follows:</para>
<codesnippet language="xml" style="code">
<![CDATA[
<document filename="test_015_japanese.pdf">
<docinit>
<registerCidFont faceName="HeiseiMin-W3"/>
</docinit>

<template ...>
etc.
]]>
</codesnippet>
<spacer length="15"/>

<para><b>Note:</b> The <font face="Courier">encName</font> attribute of
<font face="Courier">registerCidFont</font> is deprecated: you should not use it with new
documents.</para>

<para>You may then declare paragraph styles, use string-drawing operations
or blockTable fonts referring to the font you have defined:</para>
<codesnippet language="xml" style="code">
    <![CDATA[
<paraStyle name="jtext"
           fontName="HeiseiMin"
           fontSize="12"
           leading="14"
           spaceBefore="12" />
]]></codesnippet>
<spacer length="15"/>
<para>The test directory includes a file <b>test_015_japanese.rml</b> containing
a working simplified example in Japanese.</para>

<para><b>Warning:</b> You will need to have a number of CMap files available
on your system.  These are files provided by Adobe which contain information on
the encodings of all the glyphs in the font. RML2PDF looks for these in locations
defined in the {{code}}CMapSearchPath{{endcode}} variable in the file
{{code}}reportlab/rl_config.py{{endcode}}, which knows where to find Acrobat Reader
on most Windows and Unix systems.  If you wish to use Asian fonts on another
system, you can copy these files (which may be redistributed freely) from a machine
with Acrobat Reader on to your server.</para>

<para><i>Editor's note at 28/12/2002 - there is a great deal of information on fonts
which needs adding to this manual including embedded Type 1 fonts and encodings
and use of embedded subsetted TrueType fonts</i></para>
<!-- sectionName "Paragraph Hyphenation" -->

<para>Hyphenation functionality (requires Pyphen package installed) - Pyphen is a pure Python module to hyphenate text using included or external Hunspell hyphenation dictionaries.</para>
<para><b><i>Usage</i></b> - Set the hyphenationLang attribute in the paraStyle and the content will be slplit according to the language used.</para>
<para>You can also exclude any word or part of a sentence from hyphenation by opening and closing a <b><i>nobr</i></b> tag around the content.</para>
<para>If the pyphen python module is installed attribute hyphenationLang controls which language will be
used to hyphenate words without explicit embedded hyphens.</para>
<para>If embeddedHyphenation is set then attempts will be made to split words with embedded hyphens.
Attribute uriWasteReduce controls how we attempt to split long uri's. It is the fraction of a line that we
regard as too much waste. The default in module reportlab.rl_settings is 0.5 which means that we
will try and split a word that looks like a uri if we would waste at least half of the line.</para>
<para>Currently the hyphenation and uri splitting are turned off by default. You need to modify the default settings
by using the file ~/.rl_settings or adding a module reportlab_settings.py to the python path.<br/>
Suitable values are</para>
<para leftIndent="10">hyphenationLanguage='en_GB'<br/>
embeddedHyphenation=1<br/>
uriWasteReduce=0.3</para>

<para textColor="blue"><span color="black">More examples here</span><a href="https://www.reportlab.com/examples/rml/test/test_001_hello.rml">test_001_hello.rml</a>  <a href="https://www.reportlab.com/examples/rml/test/test_001_hello.pdf">test_001_hello.pdf</a></para>


