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