Update description in README and pdfjoin.rst.
[pdftools:pdfjoin.git] / pdfjoin.rst
1 .. -*- mode: rst ; ispell-local-dictionary: "american" -*-
2
3 ==========================
4 pdfjoin
5 ==========================
6
7 -------------------------------------------------------------
8 Join several PDF documents into a single one
9 -------------------------------------------------------------
10
11 :Author:    Hartmut Goebel <h.goebel@goebel-consult.de>
12 :Version:   Version |VERSION|
13 :Copyright: 2008-2011 by Hartmut Goebel
14 :Licence:   GNU Public Licence v3 (GPLv3)
15 :Manual section: 1
16
17 .. raw:: manpage
18
19    .\" disable justification (adjust text to left margin only)
20    .ad l
21
22
23 SYNOPSIS
24 ==========
25
26 ``pdfjoin`` <options> infile ...
27
28 DESCRIPTION
29 ============
30
31 ``pdfjoin`` is a command line tool, a droplet and a Python library to
32 join several PDF documents into a single one. It will join all files
33 passed as argument into a new file. As a special feature it can
34 operate as a "droplet".
35
36 ``pdfjoin`` has three modes of operation:
37
38 1) With no output path given: The droplet mode.
39
40    If no output path is passed to ``pdfjoin``, will look for a file
41    matching ``pdfjoin-*.pdf`` in the current directory, which has been
42    modified within the last 60 minutes. (More precise, the filename
43    must match the scheme as described in the next paragraph.)q If such
44    a file exists, all documents passed as arguments will be joined to
45    this one.
46
47    If such a file does not exist, it will be created first. The
48    filename will be ``pdfjoin-yyyddmm-hhmm.pdf`` with ``yyyddmm``
49    being the current date and ``hhmm`` being the current time.
50
51    This allows dropping one file after each other onto the droplet and
52    join them into the same output file -- assuming you are not waiting
53    more then 60 Minutes between each drop.
54
55 2) With an existing directory name is given as output path
56
57    This case works exactly like the droplet mode, except that the file
58    is searched for and created in the given directory.
59
60 3) With any other path given as output path:
61
62    In this case the given path is the filename searched for and
63    created if not existing yet.
64
65
66 OPTIONS
67 ========
68
69 General Options
70 --------------------
71
72 --version        Show program's version number and exit
73 -h, --help       Show help message and exit
74 -v, --verbose    Be verbose. Tell about scaling, rotation and number of
75                  pages. Can be used more than once to increase the
76                  verbosity.
77 -n, --dry-run    Show what would have been done, but do not generate files.
78
79 Defining Output
80 -----------------
81
82 -o OUTPUT, --output=OUTPUT
83                  Specify filename or directory to write file to
84                  (default: current directory)
85
86
87 EXAMPLES
88 ============
89
90 :pdfjoin infile1.pdf infile2.pdf infile3.pdf:
91        Creates a file named like ``pdfjoin-20120102-1415.pdf`` in the
92        current directory.
93
94 :pdfjoin infile1.pdf ; pdfjoin infile2.pdf ; pdfjoin infile3.pdf:
95        Same as above -- assuming the deplay between issuing each of
96        the commands is less than 60 minutes.
97
98 :pdfjoin infile1.pdf infile2.pdf infile3.pdf --output /tmp/foo:
99        Creates a file named like
100        ``/tmp/foo/pdfjoin-20120102-1415.pdf`` in the current
101        directory. But only if /tmp/foo already exisits!
102
103 :pdfjoin infile1.pdf --output /tmp/foo; pdfjoin infile3.pdf --output /tmp/foo:
104        Same as above -- again assuming the deplay between issuing each
105        of the commands is less than 60 minutes.
106
107 :pdfjoin infile1.pdf infile2.pdf infile3.pdf --output /tmp/foo.pdf:
108        Creates a file named like ``/tmp/foo.pdf`` in the current
109        directory. But only if /tmp/foo.pdf is no exiting directory!
110
111
112 SEE ALSO
113 =============
114
115 ``pdfposter``\(1) http://pypi.python.org/pypi/pdftools.pdfposter/,
116 ``pdfnup``\(1) http://pypi.python.org/pypi/pdfnup/,
117 ``pdfsplit``\(1) http://pypi.python.org/pypi/pdfsplit/,
118 ``pdfgrid``\(1) http://pypi.python.org/pypi/pdfgrid/
119
120 Project Homepage http://pdfposter.origo.ethz.ch/