README.txt

   1 .. -*- mode: rst ; ispell-local-dictionary: "american" -*-
   2
   3 ==========================
   4 pdfjoin
   5 ==========================
   6
   7 -----------------------------------------------------------------
   8 Join several PDF documents into a single one -- includes droplet
   9 -----------------------------------------------------------------
  10
  11 :Author:    Hartmut Goebel <h.goebel@goebel-consult.de>
  12 :Version:   Version 0.1dev
  13 :Copyright: 2012 by Hartmut Goebel
  14 :Licence:   GNU Public Licence v3 (GPLv3)
  15 ...
  16   :Homepage:  http://pdfposter.origo.ethz.ch/
  17
  18 ``pdfjoin`` can be used to join several PDF documents into a single
  19 one. it will join all files passed as argument into a
  20
  21 ``pdfjoin`` has three modes of operation:
  22
  23 1) With no output path given: The droplet mode.
  24
  25    If no output path is passed to ``pdfjoin``, will look for a file
  26    matching ``pdfjoin-*.pdf`` in the current directory, which has been
  27    modified within the last 60 minutes. (More precise, the filename
  28    must match the scheme as described in the next paragraph.)q If such
  29    a file exists, all documents passed as arguments will be joined to
  30    this one.
  31
  32    If such a file does not exist, it will be created first. The
  33    filename will be ``pdfjoin-yyyddmm-hhmm.pdf`` with ``yyyddmm``
  34    being the current date and ``hhmm`` being the current time.
  35
  36    This allows dropping one file after each other onto the droplet and
  37    join them into the same output file -- assuming you are not waiting
  38    more then 60 Minutes between each drop.
  39
  40 2) With an existing directory name is given as output path
  41
  42    This case works exactly like the droplet mode, except that the file
  43    is searched for and created in the given directory.
  44
  45 3) With any other path given as output path:
  46
  47    In this case the given path is the filename searched for and
  48    created if not existing yet.
  49
  50
  51 Requirements and Installation
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 ``pdfjoin`` requires
  55
  56 * `Python 2.x`__ or higher (tested with 2.7, but other versions should
  57   work, too, Python 3.x is *not* supported),
  58 * `setuptools`__ for installation (see below), and
  59 * `pyPdf`__ >= 1.11.
  60
  61 __ http://www.python.org/download/
  62 __ http://pypi.python.org/pypi/setuptools
  63 __ http://pybrary.net/pyPdf/
  64
  65
  66 :Hints for installing on Windows: Following the links above you will
  67    find .msi and .exe-installers. Simply install them and continue
  68    with `installing pdfjoin`_.
  69
  70 :Hints for installing on GNU/Linux: Most current GNU/Linux distributions
  71    provide packages for the requirements. Look for packages names like
  72    `python-setuptools` and `python-pypdf`. Simply install them and
  73    continue with `installing pdfjoin`_.
  74
  75 :Hint for installing on other platforms: Many vendors provide Python.
  76    Please check your vendors software repository. Otherwise please
  77    download Python 2.6 (or any higer version from the 2.x series) from
  78    http://www.python.org/download/ and follow the installation
  79    instructions there.
  80
  81    After installing Python, install `setuptools`__. You may want to
  82    read `More Hints on Installing setuptools`_ first.
  83
  84 __ http://pypi.python.org/pypi/setuptools
  85
  86    Using setuptools, compiling and installing the remaining
  87    requirements is a piece of cake::
  88
  89      # if the system has network access
  90      easy_install pyPdf
  91
  92      # without network access download pyPdf
  93      # from http://pybrary.net/pyPdf/ and run
  94      easy_install pyPdf-*.zip
  95
  96
  97 Installing pdfjoin
  98 ---------------------------------
  99
 100 When you are reading this you most probably already downloaded and
 101 unpacked `pdfjoin`. Thus installing is as easy as running::
 102
 103    python ./setup.py install
 104
 105 Otherwise you may install directly using setuptools/easy_install. If
 106 your system has network access installing `pdfjoin` is a
 107 breeze::
 108
 109      easy_install pdftools.pdfjoin
 110
 111 Without network access download `pdftools.pdfjoin` from
 112 http://pypi.python.org/pypi/pdfjoin and run::
 113
 114      easy_install pdftools.pdfjoin-*.tar.gz
 115
 116
 117 More Hints on Installing setuptools
 118 ------------------------------------
 119
 120 `pdfjoin` uses setuptools for installation. Thus you need
 121 either
 122
 123   * network access, so the install script will automatically download
 124     and install setuptools if they are not already installed
 125
 126 or
 127
 128   * the correct version of setuptools preinstalled using the
 129     `EasyInstall installation instructions`__. Those instructions also
 130     have tips for dealing with firewalls as well as how to manually
 131     download and install setuptools.
 132
 133 __ http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
 134
 135
 136 Custom Installation Locations
 137 ------------------------------
 138
 139 If you want to install ``pdfjoin`` to a different place, simply use::
 140
 141    # install to /usr/local/bin
 142    python ./setup.py install --prefix /usr/local
 143
 144    # install to your Home directory (~/bin)
 145    python ./setup.py install --home ~
 146
 147
 148 Please mind: This effects also the installation of pyPdf (and
 149 setuptools) if they are not already installed.
 150
 151 For more information about Custom Installation Locations please refer
 152 to the `Custom Installation Locations Instructions`__ before
 153 installing ``pdfjoin``.
 154
 155 __ http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations>