Update description in README and pdfjoin.rst.
[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`` 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>