

                            pdf2email README
                            ----------------

pdf2email is a CUPS backend that uses GhostScript to print a document to PDF
and sends the final file to the user that requested the print via email.
It is written in Python.



REQUIREMENTS
------------

  - Python (http://www.python.org/)
  - CUPS server (http://www.cups.org/)
  - Ghostscript (http://www.cs.wisc.edu/~ghost/)
  - a postscript printer's PPD file. (see INSTALLATION section)
  - Email server, on which usernames from the LAN workstations either match the
    users on the email server or proper mappings (aliases) have been set.



INSTALLATION
------------

- Put the "pdf2email" file in /usr/lib/cups/backend/ and set the executable bit:

chmod +x /usr/lib/cups/backend/pdf2email



CONFIGURATION
-------------

- Open the script in a text editor and set a couple of settings:

1. Set the email server's hostname:

SMTP_Server = "mail.example.org"

2. Set the email address of the sender as it will appear in the email:

print_admin = "admin@example.org"

3. (OPTIONAL) Set the path to a text file that contains PDFmarks. If you don't
know what PDFmarks are, you SHOULD leave this variable empty. (see some more
info in the PDFmarks section):

pdfmarks_file = ""



CONFIGURE A CUPS PRINTER
------------------------

This section describes in brief all the required actions in order to add a
printer that uses this backend to CUPS.

1. Decide the printer's name, eg "TestPDFprinter"

2. Decide the directory, where the PDF files are saved temporarily. This
   directory must be writable by the users. Usually, /tmp is perfect for this.
   Note, that no PDF files are left in this directory.
   This piece of information is used in the device URI of your CUPS printer. For
   example, provided that the /tmp directory will be used, the Device URI would
   be:
       pdf2email:/tmp

3. Get a postscript printer's PPD file. You can find such files at:
   - Your printer manufacturer's web site
   - "Linux Printing" (http://www.linuxprinting.org/show_driver.cgi?driver=Postscript)
   - Adobe's download center (http://www.adobe.com/support/downloads/)
   
   WARNING
   =======
   It is your exclusive responsibility to examine the printer driver's license
   prior to using the PPD file.
   NO PPD FILES ARE SHIPPED WITH THE pdf2email BACKEND.

Finally, add a new printer that uses this backend, either by using lpadmin from
the command line or by using the web-based administration interface of CUPS.

a) Using lpadmin from the shell:

As root issue the following command:

lpadmin -p TestPDFprinter -E -v pdf2email:/tmp -P /path/to/myprinter.ppd

b) Using CUPS web-based administration interface:

Use the "Add Printer" hyperlink. Some notes:
     i) In the device dropdown box, select the following:
        Direct PDF Printing/Delivery to user email
    ii) In the device URI box use the writable directory, eg:
        pdf2email:/tmp
   iii) If asked about the type of the print queue, use "RAW".



USAGE
-----

Make this printer available to the LAN through the IPP or SAMBA or
whatever other protocol and add it to your printer list in your client machines.
Whatever you send to that printer will be converted to a PDF document and will
be emailed to your user's email address.



TROUBLE?
--------
If any error occurs during the PDF creation process, there will be a failure
notice in your inbox and a message in syslog (/var/log/messages).

In case you receive no email after requesting a print, check syslog for any
error messages. If there aren't any, the check CUPS error log.

Finally, note that if you use a security layer like SELinux, then you might
need to further adjust it so it lets 3rd party CUPS backends to function.
This is beyond the scope of this document.



PDFmarks
--------

If you do not know what pdfmarks are, please do a web search about them.
This backend can include PDFmarks in the final PDF document. Do not expect
anything spectacular, as this script cannot process the document for bookmarks,
links etc. What it can do is to add pre-defined pdfmarks to all PDF documents.

For example, if, for example,  you want to fill some of the document properties,
save the following in a file:

[/Title ()
/Author ()
/Subject (blah blah)
/Keywords (keyword1, keyword2, blah)
/DOCINFO pdfmark

By default the author's property is filled with the username that requested the
print.

Finally, add the path to the pdfmarks file in the configuration section of 
the backend, as described in the configuration section:

pdfmarks_file = "/path/to/pdfmarks.file"

This feature has not been tested.



SUPPORT
-------

Although this software worked on a test environment, it should be considered
alpha.

This script exists for testing purposes only and is completely unsupported. If
it does not work for you or if it does not do what you expected, please try to
fix it yourself.



- LICENSE INFO

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the:

Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston,
MA 02111-1307  USA


