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