Overview
--------

PrintToLRF is a Common Unix Printing System (CUPS) backend, which can be used
to create LRF files from within any application that can print to the CUPS
system. Basically, this provides the same functionality that is available to
Windows users via the Sony LIBRIe printer software.


Requirements
------------

  * A UNIX/Linux machine running the CUPS printer system:
    http://www.cups.org/

  * Python 2.3:
    http://www.python.org

  * makelrf 0.3:
    http://groups.yahoo.com/group/librie/

  * NETPBM
    http://netpbm.sourceforge.net/

  * GhostScript
    http://www.cs.wisc.edu/~ghost/

Although it's not required to generate the LRF files, to transfer the books to
the memory stick under Linux, BookListGen (http://booklistgen.peterknowles.com)
will also be needed.


Installation
------------

  * Firstly, all of the software listed in the requirements section needs to
    be installed. Most Linux machines should already have the required software
    installed. On a Debian box, something similar to the following command 
    should install everything necessary:

    apt-get install cupsys netpbm-nonfree python2.3 gs-gpl

    If you're not using Debian, you may need to source these components in the
    usual way.

  * Once the requirements are fulfilled, just untar the printtolrf file and
    copy it into the CUPS backend directory (usually /usr/lib/cups/backend).
    Make sure that the permissions/ownership are correct.

    cp printtolrf /usr/lib/cups/backend
    chown root.root /usr/lib/cups/backend/printtolrf
    chmod 755 /usr/lib/cups/backend/printtolrf

  * Restart the CUPS server to ensure that it picks up the new backend:

    /etc/init.d/cupsys restart

  * Ensure that the backend is correctly installed, by running lpinfo:

    lpinfo -v

    In the output returned from lpinfo, there should be a line listing the
    printtolrf backend:

    direct printtolrf

    If you get a line like the above, your installation should be working.


PrintToLRF Configuration
------------------------

Edit the printtolrf file, and modify the following settings if necessary:

Setting Name: MAKELRF
Description: The full path to the makelrf program.
Default: /opt/makelrf/bin/makelrf

Setting Name: XMLINFO
Description: The full path to the xml info file used by makelrf for the lrf
meta information. This file is part of the makelrf distribution.
Default: /opt/makelrf/share/info.xml

Setting Name: GS
Description: The full path to the GhostScript executable.
Default: /usr/bin/gs

Setting Name: PSSELECT
Description: The full path to the psselect utility.
Default: /usr/bin/psselect

Setting Name: OUTPUTDIR
Description: The directory where the generated LRF files should be stored.
Default: /tmp

Setting Name: TWOPAGE
Description: Enable or disable splitting the page over two pages. The LIBRIe
will need to he held sideways when using this option, but the output should 
be more readable.
Default: 1

Setting Name: DEFAUTHOR
Description: The author of the LRF file (as listed in the booklist).
Default: PrintToLRF

Setting Name: DEFDESCRIPTION
Description: The description of the LRF file.
Default: Generated by PrintToLRF v0.1

Setting Name: NETPBMDIR
Description: The base directory where the NETPBM utilities are located.
Default: /usr/bin


Configuring CUPS
----------------

A new printer must be configured via CUPS and the printtolrf backend should be
associated with this printer. There are many ways to do this. One of the
easiest is to use the web based GUI:

* Open a browser, and connect to the CUPS server on port 631.
  (e.g. http://localhost:631)
* Click 'Manage Printers'
* Click 'Add Printer'
* Enter the root username and password.
* Enter the following for the printer details:

  Name: LRFPrinter
  Location: Local
  Description: Create LRF File

  Click 'Continue'

* Select 'LRF File Creator' in the Device list, and click 'Continue'.
* Enter 'printtolrf://' in the Device URI entry box, and click 'Continue'.
* Select 'Generic' for the Make, and click 'Continue'.
* Select 'Generic PostScript Printer Foomatic/Postscript (recommended)(en)' for
  the printer model, and click 'Continue'.

The LRF printer should now be configured. If for some reason, the generic
postscript printer listed above is not available, just select another model of
postscript printer. Any one should be acceptable.


Using PrintToLRF
----------------

Load up your favourite application, and click print. Select the LRFPrinter that
you configured above, adjust any margins and print preferences, and print.

After a short while, you will find the LRF file generated in the output 
directory which you configured. The file will be named in the following way:

<uniquename>.<CUPS Job ID>.<Username>.lrf

You can then copy this file to your LIBRIe (using BookListGen or the Sony 
supplied software) and read it as normal.