1 .. -*- mode: rst ; ispell-local-dictionary: "american" -*-
3 ==========================
5 ==========================
7 -----------------------------------------------------------------
8 Join several PDF documents into a single one -- includes droplet
9 -----------------------------------------------------------------
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)
16 :Homepage: http://pdfposter.origo.ethz.ch/
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
21 ``pdfjoin`` has three modes of operation:
23 1) With no output path given: The droplet mode.
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
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.
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.
40 2) With an existing directory name is given as output path
42 This case works exactly like the droplet mode, except that the file
43 is searched for and created in the given directory.
45 3) With any other path given as output path:
47 In this case the given path is the filename searched for and
48 created if not existing yet.
51 Requirements and Installation
52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
61 __ http://www.python.org/download/
62 __ http://pypi.python.org/pypi/setuptools
63 __ http://pybrary.net/pyPdf/
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`_.
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`_.
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
81 After installing Python, install `setuptools`__. You may want to
82 read `More Hints on Installing setuptools`_ first.
84 __ http://pypi.python.org/pypi/setuptools
86 Using setuptools, compiling and installing the remaining
87 requirements is a piece of cake::
89 # if the system has network access
92 # without network access download pyPdf
93 # from http://pybrary.net/pyPdf/ and run
94 easy_install pyPdf-*.zip
98 ---------------------------------
100 When you are reading this you most probably already downloaded and
101 unpacked `pdfjoin`. Thus installing is as easy as running::
103 python ./setup.py install
105 Otherwise you may install directly using setuptools/easy_install. If
106 your system has network access installing `pdfjoin` is a
109 easy_install pdftools.pdfjoin
111 Without network access download `pdftools.pdfjoin` from
112 http://pypi.python.org/pypi/pdfjoin and run::
114 easy_install pdftools.pdfjoin-*.tar.gz
117 More Hints on Installing setuptools
118 ------------------------------------
120 `pdfjoin` uses setuptools for installation. Thus you need
123 * network access, so the install script will automatically download
124 and install setuptools if they are not already installed
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.
133 __ http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
136 Custom Installation Locations
137 ------------------------------
139 If you want to install ``pdfjoin`` to a different place, simply use::
141 # install to /usr/local/bin
142 python ./setup.py install --prefix /usr/local
144 # install to your Home directory (~/bin)
145 python ./setup.py install --home ~
148 Please mind: This effects also the installation of pyPdf (and
149 setuptools) if they are not already installed.
151 For more information about Custom Installation Locations please refer
152 to the `Custom Installation Locations Instructions`__ before
153 installing ``pdfjoin``.
155 __ http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations>