<!-- chapterName "Basic Text Operations" -->

<!-- sectionName "Coordinates and measurements" -->

<para>
In RML, the page origin is in the bottom left hand corner (0,0). Any
point on the page can be specified by a pair of numbers - a pair of
X,Y co-ordinates. The X co-ordinate states how far to the <i>right</i>
the point is and the Y co-ordinate states how far <i>up</i> it is.
</para>

<para>
When an RML element has co-ordinates, the co-ordinate origin is the
lower left corner. In the case of elements in a <font face="Courier">pageGraphic</font>, the
origin of the lower left corner of the page.  For elements within an
<font face="Courier">&lt;illustration&gt;</font>, the origin is the lower left corner of the bounding box
declared by the <font face="Courier">&lt;illustration&gt;</font>.
</para>

<para>
These co-ordinates (and any other measurements in an RML document) can
be given in one of four units. Inches use the term '<font face="Courier">in</font>',
centimetres use the term '<font face="Courier">cm</font>', and millimetres use the
term '<font face="Courier">mm</font>'. If no unit is specified, RML will assume
that you are giving a measurement in points - one point is 1/72 of an inch. You
can also explicitly use points with the term '<font face="Courier">pt</font>'.
</para>

<para>
As an example, the following pairs of co-ordinates all refer to the
same point. Notice that there is no space between the number and any
unit that follows it.
</para>
<para style="bulletNospace" bulletText="">
(4.5in, 1in)
</para>
<para style="bulletNospace" bulletText="">
(11.43cm, 2.54cm)
</para>
<para style="bulletList" bulletText="">
(324, 72)
</para>

<para>
You can mix and match these units within RML, though it generally
isn't a good idea to do so. The co-ordinate pair (3.5in, 3.5cm) is
valid, and won't confuse the RML parser - but it may well confuse you.
</para>



<!-- sectionName "Using Colors" -->

<para>There are three ways to specify colors in RML:
</para>
<para style="bulletList" bulletText="l">by red/green/blue value (e.g. "#ff0000" or "(0.0,0.0,1.0)") </para>
<para style="bulletList" bulletText="l">by cyan/magenta/yellow/black value (e.g. "#ff99001f" or "(1.0,0.6,0.0,0.1)")</para>
<para style="bulletList" bulletText="l">by color name using standard HTML names</para>

<para>
The RGB or additive color specification follows the way a computer
screen adds  different levels of the red, green, or blue light to make
any color. White is formed by turning all three lights on full (1,1,1).
</para>

<para>
The CMYK or subtractive method follows the way a printer mixes three
pigments (cyan, magenta, and yellow) to form colors. Because mixing
chemicals is more  difficult than combining light there is a fourth
parameter for darkness. A chemical combination of the CMY pigments
almost never makes a perfect black - instead producing a muddy brown -
so, to get black printers use a direct black ink rather than use
the CMY pigments.
</para>

<para>
The name CMYK comes from the name of the four colors used: Cyan,
Magenta, Yellow and "Key" - a term sometimes used by printers to refer
to black.
</para>

<para>
Because CMYK maps more directly to the way printer hardware works it
may be the case that colors specified in CMYK will provide better
fidelity and better  control when printed.
</para>

<para>
The color names which RML recognizes are mostly drawn from the HTML
specification. (For a list of these color names recognized by RML,
see Appendix A).
</para>

<para>
[<b>NOTE</b>: Currently, while RML supports specifying colors by CMYK
value, rml2pdf hasn't yet implemented it. If you try, you well get a
ValueError and the error message "cmyk not implemented yet"].
</para>


<!-- sectionName "Using fonts" -->

<para>
Font names are given in the following format:
</para>
<para style="bulletList" bulletText="">
<font face="Courier">Fontname-style</font>
</para>
<para>
where fontname is the name of the font (e.g. Courier), and the style is
its  appearance (eg, Oblique, BoldOblique).
</para>

<para>
The only fonts supplied with Adobe's Acrobat Reader are the "14
standard fonts". These 14 standard fonts are:
</para>
<para style="bulletNospace" bulletText="">Courier</para>
<para style="bulletNospace" bulletText="">Courier-Bold</para>
<para style="bulletNospace" bulletText="">Courier-BoldOblique</para>
<para style="bulletNospace" bulletText="">Courier-Oblique</para>
<para style="bulletNospace" bulletText="">Helvetica</para>
<para style="bulletNospace" bulletText="">Helvetica-Bold</para>
<para style="bulletNospace" bulletText="">Helvetica-BoldOblique</para>
<para style="bulletNospace" bulletText="">Helvetica-Oblique</para>
<para style="bulletNospace" bulletText="">Symbol</para>
<para style="bulletNospace" bulletText="">Times-Bold</para>
<para style="bulletNospace" bulletText="">Times-BoldItalic</para>
<para style="bulletNospace" bulletText="">Times-Italic</para>
<para style="bulletNospace" bulletText="">Times-Roman</para>
<para style="bulletNospace" bulletText="">ZapfDingbats</para>
<para style="bulletNospace" bulletText=""></para>
<para></para>
<para>
Custom fonts can also be used in your document.  RML supports TrueType and Type 1 fonts.  In order
to use them, make sure they are on the appropriate path and then register them in the
<font face="Courier">&lt;docinit&gt;</font> section at the top of the RML file.
</para>
<para>
Use the <font face="Courier">&lt;registerTTFont&gt;</font> and
<font face="Courier">&lt;registerFont&gt;</font> tags to register them.
To use a common set of fonts together as bold, italic etc., you need to put them
into a common grouping using the <font face="Courier">&lt;registerFontFamily&gt;</font> tag.
</para>
<para>
An example of how to use these tags with different font types and styles can be found in the file rml2pdf/test/test_005_fonts.rml
</para>

<!--
<para>
There is no need to use fonts whose names end with "-Bold", "-Oblique", "-Italic",
"-BoldOblique", or "-BoldItalic". You should use &lt;i&gt;...&lt;/i&gt; to get
the Oblique/Italic form of a font, and use&lt;b&gt;..&lt;/b&gt; to get Bold form.
</para>
-->
<!--XXX -->
<!--This is being commented out until I get an explanation from Aaron about why this
should be so -->


<!-- sectionName "Basic text operations - setFont and drawString" -->

<para>
The simplest way to put text on a page is using the <font face="Courier">&lt;drawString&gt;</font>
tag. This places the "string" of text on the page at the
co-ordinates you give it. The only attributes you can give it are a
pair of X and Y co-ordinates. After the tag itself comes the string of
text you want put on the page, and then you need the closing
<font face="Courier">&lt;/drawString&gt;</font> tag.
</para>

<para>
<font face="Courier">DrawString</font> has a pair of companions. <font face="Courier">DrawRightString</font>
and <font face="Courier">drawCentredString</font> both work in the same way, but right justify the
string and center it, respectively.
</para>

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

<codesnippet language="xml" style="code">
    <![CDATA[
<drawString x="523" y="800">
    This is a drawString example
</drawString>

<drawRightString x="523" y="800">
    This is a drawRightString example
</drawRightString>

<drawCentredString x="523" y="800">
    This is a drawCentredString example
</drawCentredString>
]]>
</codesnippet>
<spacer length="15"/>

<para>
To set the font that you want a piece of text to be, you need to use the
<font face="Courier">&lt;setFont&gt;</font> tag. This has two arguments which are required - you need to
give it the <font face="Courier">name</font> of the font, and the <font face="Courier">size</font> you want it displayed at.
</para>

<para>
A setFont tag looks like this:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<setFont name="Helvetica-Bold" size="17"/>
]]>
</codesnippet>
<spacer length="15"/>

<para>
To use all the <font face="Courier">drawString</font> commands, you need to use a tag called
<font face="Courier">&lt;pageGraphics&gt;</font>. This tag appears at
the start of a RML document, in the <font face="Courier">pageTemplate</font> section.
<font face="Courier">pageGraphics</font> are the graphics that have
to do with a whole page (rather than just individual illustrations, as
we will see later). <font face="Courier">pageGraphics</font> can be used
to provide a background to a page, to place captions or other textual
information on a page, or to provide logos or other colorful elements.
Whatever you use them for, they are always anchored to a spot on the
page - they do not wrap or flow with any text you might put into paragraphs.
</para>


