Q. When I try to run the rml file through RML2PDF, I get errors. Help!

A. Most errors should have a reasonably self-explanatory error message. The most common cause of compilation errors is failing to close tags properly; e.g. a <para> without a </para>. Another common mistake is failing to escape certain characters within your <para> tags - e.g. left and right angle brackets (substitute with &lt; and &gt;), ampersands (substitute with &amp;) etc. - refer to Google for how to escape other characters in XML. Also, you will frequently find yourself using the wrong elements in a tag - refer to the DTD for the correct tag syntax, and remember that tags are case sensitive.

Q. I specified a table/ some text / an image in my rml document, but when I compile it to PDF, it's not there.

A. This is a common problem for beginners. If the document complies into PDF without errors, the element is probably not visible because it's hidden behind another element, or the frame containing it is too small. Try changing the x/y co-ordinates of the element, or expanding the size of the frames, or shrinking the size of the fonts/images/text etc, then recompile until the element becomes visible. You can sometimes see if a hidden element is present at all by selecting the whole page with the mouse in Acrobat reader.

Q. My image/frame/table is in the wrong place. Why?

A. Remember that in RML, co-ordinates are specified from the bottom left corner of any element, including the page itself. This is in line with the way PostScript works, but it may be somewhat unfamiliar.

Q. I'm having trouble making sense of the DTD. Can you help?

A. A (partial) sample entry for the image tag is as follows:

<!ELEMENT image EMPTY> <!ATTLIST image file CDATA #REQUIRED x CDATA #REQUIRED y CDATA #REQUIRED width CDATA #IMPLIED height CDATA #IMPLIED showBoundary (yes | no | 0 | 1) #IMPLIED >

From this entry, you can see the following:

• using this tag requires a filename, along with x and y coordinates (these are marked as CDATA #REQUIRED).

• the width and height are optional 'chardata' parameters (marked as CDATA #IMPLIED).

• the showBoundary parameter is optional (#IMPLIED) and shows a list of the permitted values.

So a sample use of this tag would be <image file="pic.jpg" x="0" y="0" showBoundary="yes">, which would place the a picture 'pic.jpg' at the bottom left corner of a document, with a surrounding border.

Q. How do I specify the page size & orientation?

A. The page size defaults to A4, portrait. You can change it for the whole document within the <template> tag, and you can override it for individual pages using the <pageTemplate> tag.

Q. How can I use my own fonts?

A. By default, you can use the 14 standard fonts supplied with Acrobat Reader. However, RML also accepts TrueType and Type1 fonts. Examples of how to use them are in test_005_fonts.rml and test_023_ttfonts.rml in the rml2pdf/tests/ directory.

Q. Sorry, I still don't get it.

A. Try reading the manual in rml2pdf/docs; look at the test cases in rml2pdf/test/ , or have a look at the code snippets on the ReportLab website.

Q. I'm a bit confused about how to use 'feature X'

A. Try reading the manual in rml2pdf/docs; look at the test cases in rml2pdf/test/ , or have a look at the code snippets on the ReportLab website.

Q. I really need to use 'feature Y'. Does RML support it?

A. Try reading the manual in rml2pdf/docs; look at the test cases in rml2pdf/test/ , or have a look at the code snippets on the ReportLab website.

Q. I've discovered how to do something amazing in RML. How can I tell the world?

A. Post a code snippet on the ReportLab website! Go to http://www.reportlab.com/snippets