#copyright ReportLab Inc. 2001-2002
#see license.txt for license details
#$Header: /rl_home/xxx/repository/rlextra/rml2pdf/00README.txt,v 1.9 2002/10/29 17:17:07 john Exp $



This is an evaluation copy of Report Markup Language.

Report Markup Language is ReportLab's easy-to-use
enterprise reporting solution.  It consists of:
 - an XML markup language called "Report Markup Language" 
   (RML) which lets you define the precise appearance
   of a printed document
 - a 'black box' program, rml2pdf, which converts
   such documents into Adobe's Portable Document Format.

This does NOT use Adobe's Acrobat tools - it is totally
standalone and directly handles rendering, page layout,
image embedding, and direct construction of PDF files.

We are currently shipping an evaluation version in the form of a 
Windows EXE.  Many other forms of installation are possible;
RML2PDF can run on all common platforms and be accessed via
many protocols and techniques including COM, CORBA, Java and
C bindings and a variety of scripting languages.  This file
is limited to discussing the single-EXE distribution.


Installation
============
The zip file contains
   rml2pdf.exe - the executable program
   rml_1_0.dtd - the Document Type Declaration
   doc\rml_user_guide.rml   - the manual in RML source format,
          plus numbered RML files to accompany the user guide
   demos\  - miscellaneous demos.
   test\ - miscellaneous tests 

Unzip the zip file into any location.  It will create a 
subdirectory called 'rml2pdf', so you can unzip directly
into C:\ or C:\temp if you wish.

There are no registry entries or external dependencies; when you
delete it, it has gone forever.

Generating the Documentation
============================
Our manual is "just another report" so we start by generating
it from the source file!

cd to the doc directory from a DOS prompt and enter the 
following (assuming you unzipped to C:):
 C:\> cd rml2pdf\doc
 C:\rml2pdf\doc>  ..\rml2pdf rml_user_guide.rml 

After a few seconds you will see the message
 Created C:\rml2pdf\doc\RML_UserGuide_1_0.pdf

This is your manual.  Read it next!

Alternatively, type 'runall.bat' to generate
all the examples and PDFs in the distribution.

These documents all assume that you want a page size of 
"A4". If you want to change this to "letter", look for the 
following line in the file rml_user_guide.rml:
<template pageSize="(595, 842)"

and change it to this:
<template pageSize="(8.5in, 11in)" 

If you need more information about the issue of page sizes, 
look in the section "Template and pageTemplate in more detail" 
in the RML User Guide.


File Locations
==============
There are three directory locations of interest:
(a) where the EXE and DTD live
(b) where you run the command from
(c) where the RML document lives

The EXE can be anywhere on your system.  We suggest putting it
in a directory on the system path so you can type 'rml2pdf'
in any directory. The DTD must be in the same directory as the 
EXE. RML documents should not include directory path names in 
the DOCTYPE declaration; only the form

   <!DOCTYPE document SYSTEM "rml_1_0.dtd"> 
is allowed.  This saves you from copying the DTD all over your
hard disk.

Where you run the command from is intended to have no effect.

The output file is specified in the XML as follows:
   <document filename="sample.pdf">
The PDF will be written in the same directory as the document,
not the running process.  If you include a relative directory,
it will be relative to the document.  So you can do:
   <document filename="..\output\sample.pdf">

You can also give an absolute location:
   <document filename="C:\output\sample.pdf">

These choices were made in order to offer the 'least surprise'
to web designers.


Licensing
=========
RML2PDF is an enterprise-level product intended to be used on 
servers as part of an XML workflow.  This is an evaluation
and it prints a warning across the bottom of every page.

Licensed customers will receive a license file causing the
message to disappear, as well as other tools and materials
as part of the package.

For more information go to http://www.reportlab.com/ or
email info@reportlab.com.


