Fix minor error in README.
[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.
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>