Commit 48690679 authored by Hartmut Goebel's avatar Hartmut Goebel
Browse files

Add preliminary docs.

Based on the new docs fro pdftools.pdfposter.
parent acbee50e
Changes
=================
.. include:: ../CHANGES
Development
===============================
The source of |pdfbook| and its siblings is maintained at
a decentralized `GitLab` instance. Patches and pull-requests
are hearty welcome.
* Please submit bugs and enhancements to the `Issue Tracker
<https://gitlab.digitalcourage.de/pdftools/pdfbook/issues>`_.
* You may browse the code at the
`Repository Browser
<https://gitlab.digitalcourage.de/pdftools/pdfbook>`_.
Or you may check out the current version by running ::
git clone https://gitlab.digitalcourage.de/pdftools/pdfbook.git
*Historical Note:*
|pdfbook| was hosted at origo.ethz.ch, which closed in May 2012.
Then |pdfbook| was hosted on gitorious.org,
which was closed in May 2015 and merged into gitlab.
In 2018 the repository moved to a decentralized GitLab instance.
.. include:: _common_definitions.txt
Donations
==============
.. container:: admonition topic
**If you like pdfbook, please consider supporting me in some way.**
.. container:: box1
.. centered:: Bank transfers
While PayPal_ donations are still very much appreciated PayPal takes a
large cut and has rather questionable business practices.
If you have the ability to make SEPA bank transfers at a low cost (for
example if you live within the EU) please contact `Hartmut
<mailto:htgoebel@crazy-compilers.com>`_ to ask for his bank details.
.. container:: box2
I trust in the power of free and open source software and thus made the
entire source code publicly available for every one to use. However, it
takes a lot of time to develop the software and manage the community. And I
still need to make my living.
So, if you like the software, please consider donating, especially if your
organization benefits from this project.
Thank you!
.. figure:: _images/bitcoin-pdfposter.png
:align: right
:alt: QR-Code for Bitcoin address
Bitcoin address
* **Bitcoin:** `13qryeeJR5Hc7vR5AmQMWDuLzDEgSDNJi2
<bitcoin:13qryeeJR5Hc7vR5AmQMWDuLzDEgSDNJi2>`_
* **Bank-Transfer (prefered):**
If you have the ability to make SEPA bank transfers at a low cost
please `contact me <mailto:htgoebel@crazy-compilers.com>`_
and I'll send you the account details.
If you want a bill, please state so and also leave your name and address.
* **PayPal:** |PayPalDonate|_ -
if you want a bill, please state so and leave your name, address and
email-address.
* Please `contact me <mailto:htgoebel@crazy-compilers.com>`_
to arrange some other kind of project grant, e.g. consulting or support.
.. |PayPalDonate| replace:: Donate
.. _PayPalDonate: PayPal_
.. _PayPal: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M6LW5EZANT9ZA
.. include:: _common_definitions.txt
Examples
===============================
Examples are still to be done.
.. include:: _common_definitions.txt
Frequently Asked Questions
===============================
* Are there other Python tools for manipulating PDF?
Yes, there are:
* `pdfposter <https://pypi.org/project/pdftools.pdfposter/>`_
* `pdfnup <https://pypi.org/project/pdfnup/>`_
* `pdfsplit <https://pypi.org/project/pdfsplit/>`_
* `pdfgrid <https://pypi.org/project/pdfgrid/>`_
.. include:: _common_definitions.txt
Download & Installation
=========================
Instructions for Windows Users
-----------------------------------
1. |pdfbook| requires Python. If you don't have Python installed already,
download and install Python 3.6 from https://python.org/download/3.6/
During installation, make sure to check "Include into PATH".
2. If you already have Python installed, please check that your Python
directory (normally :file:`C:\\Python36` for python 3.6) and the Python
Scripts directory (normally :file:`C:\\Python36\\Scripts`) are in the system
path. If not, just add them in :menuselection:`My Computer --> Properties
--> Advanced --> Environment Variables` to the :envvar:`Path` system
variable.
3. Install |pdfbook| by running ::
pip install pdftools.pdfbook
Then run the console command ``pdfbook --help`` to get detailed help.
If the command ``pip`` is unknown to you system, please refer to the
`pip homepage <https://pip.pypa.io/en/stable/installing/>`_ for help.
Instructions for GNU/Linux and other Operating Systems
--------------------------------------------------------
Most current GNU/Linux distributions provide packages for |pdfbook|.
Simply search your distribution's software catalog.
Also many vendors provide Python, and some even provide |pdfbook|.
Please check your vendor's software repository.
If your distribution or vendor does not provide a current version of
|pdfbook| please read on.
If your vendor does not provide :command:`python`
please download Python 3.6 from https://www.python.org/download/ and
follow the installation instructions there.
If you distribution or vendor missed providing :command:`pip`,
alongside :command:`python`,
please check your vendor's or distribution's software repository
for a package called `pip` or `python-pip`.
If this is not provided, please refer to the
`pip homepage <https://pip.pypa.io/en/stable/installing/>`_ for help.
Optionally you might want to install `PyPDF2`
- which is a requirement for |pdfbook| -
provided by your distribution or vendor
so at least this package will be maintained by your distribution.
Check for a package named ``python-pypdf2`` or that like.
Then continue with :ref:`installing pdfbook` below.
.. _installing pdfbook:
Installing |pdfbook| using :command:`pip`
---------------------------------------------
After installing `Python` (and optionally `PyPDF2`), just run::
sudo pip install pdftools.pdfbook
to install |pdfbook| for all users.
For installing |pdfbook| for yourself only, run::
pip install --user pdftools.pdfbook
If your system does not have network access
- download |pdfbook| from https://pypi.org/project/pdftools.pdfbook/,
- downlaod `PyPDF2` from https://pypi.org/project/PyPDF2/, and
- run ::
sudo pip install pdftools.pdfbook-*.tar.gz PyPDF2-*.tar.gz
respective ::
pip install --user pdftools.pdfbook-*.tar.gz PyPDF2-*.tar.gz
.. include:: _common_definitions.txt
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python3 -msphinx
SPHINXPROJ = pdfposter
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
==============
Usage
==============
.. include:: _description.txt
Options
========
.. include:: _options.txt
.. |pdfbook| replace:: `pdfbook`
``Pdfbook`` can be used to create a large book by building it from
multple pages and/or printing it on large media. It expects as input a
PDF file, normally printing on a single page. The output is again a
PDF file, maybe containing multiple pages together building the
book.
``pdfbook`` rearranges pages from a PDF document into "signatures"
for printing books or booklets, creating a new PDF file.
A signature is a group of pages in a document corresponding to sheets
of paper folded and bound; these pages are normally not in sequential
order in a document. For example, in a document with eight-page
signatures, page 8 and page 1 might both be printed on the same sheet
of paper.
* To rearrange the pages of file ``newsletter.pdf`` into a signature
and write it to the file ``newsletter.bound.pdf``, type::
pdfbook newsletter.pdf newsletter.bound.pdf
By default, pdfbook uses one signature for the entire file. If the file
doesn't contain a multiple of four pages, it adds blank pages to the
end.
To specify the size of the signature to use - in other words, the
number of pages that will appear on a single piece of paper - give
the number as an argument to the ``-s`` option. Signature size is
always a multiple of four.
* To rearrange the pages of file ``newsletter.pdf`` into an
eight-sided signature and write it to ``newsletter.bound.pdf``,
type::
pdfbook -s8 newsletter.pdf newsletter.bound.pdf
.. Emacs config:
Local Variables:
mode: rst
End:
General Options
--------------------
-h, --help Show help message and exit
--version Show program's version number and exit
-v, --verbose Be verbose. Can be used more than once to increase the
verbosity.
-n, --dry-run Show what would have been done, but do not generate files.
-s NUMBER, --signature NUMBER
Specify the size of the signature (number
of sides which will be folded and bound together). Default: 4.
.. Emacs config:
Local Variables:
mode: rst
End:
div#examples.section table.docutils.field-list .field-body {
padding-top: 0.25em;
padding-bottom: 1em;
padding-left: 2em;
}
div#examples.section #id1.figure { float: left }
div#examples.section #id2.figure { float: right }
div#examples.section #id2.figure img { padding: 66pt 0; }
div#examples.section #id2.figure + * { clear: left }
div.sphinxsidebar li.toctree-l1 ~ li.toctree-l1 {
border-top: dotted thin #AAA;
margin-top: 0.3em;
padding-top: 0.3em;
}
div.sphinxsidebar a {
text-decortation: none;
border-bottom: none;
}
/* make refs, which are links, visible as being links */
a.reference.internal code span.pre {
border-bottom: dotted 1px #004B6B; /* same as for "a.reference" */
}
div#donations.section > .box1 {
width: 50%;
border: solid thin lightseagreen;
border-radius: 1em;
float: right;
margin-left: 0.5em;
padding-left: 0.5em;
}
div#donations.section > .box1 > .centered {
color: seagreen;
}
div#donations.section > .box2 + * {
clear: both;
}
div#donations.section >ul li {
margin-bottom: 0.5em
}
div#donations.section .figure.align-center {
float: left;
padding: 0 3em;
}
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# pdftools.pdfbook documentation build configuration file, created by
# sphinx-quickstart on Tue May 21 16:21:39 2013.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'pdfbook'
copyright = '2010-2018, Hartmut Goebel'
author = 'Hartmut Goebel'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.1.dev0'
# The full version, including alpha/beta/rc tags.
release = '0.1.0.dev0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%Y-%m-%d'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'logo_name': True,
'logo_text_align': 'center',
'description': 'Scale and Tile PDF Pages',
'github_button': False,
'fixed_sidebar': True,
'show_related': False,
}
html_sidebars = {
'**': [
'about.html',
#'globaltoc.html',
'navigation.html',
'searchbox.html',
'donate.html',
]
}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "pdfbook"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = '../projectlogo.svg'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'pdfbookdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
(master_doc, 'pdfbook.tex', 'pdfbook Documentation',
'Hartmut Goebel', 'manual'),
]
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'pdftoolspdfbook', 'pdfbook Documentation',
['Hartmut Goebel'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'pdfbook', 'pdfbook Documentation',
'Hartmut Goebel', 'pdfbook', 'One line description of project.',
'Miscellaneous'),
]
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
==============================================
pdftools.pdfbook
==============================================
.. container:: admonition topic
**Rearrange pages in PDF file into signatures for printing books.**
|pdfbook| rearranges pages from a PDF document into "signatures"
for printing books or booklets, creating a new PDF file.
This is much like the tool `psbook` does for Postscript files, but
working with PDF. Indeed |pdfbook| was inspired by `psbook`.
.. toctree::
:maxdepth: 1
Installation
Usage
Examples
Donate <Donate>
Frequently Asked Questions
Changes
Development
.. include:: _common_definitions.txt
==========================
pdfbook
==========================
----------------------------------------------------------------
Rearrange pages in PDF file into signatures for printing books.
----------------------------------------------------------------
:Author: Hartmut Goebel <h.goebel@crazy-compilers.com>
:Version: Version 0.1.0
:Copyright: GNU Public Licence v3 (GPLv3)
:Manual section: 1
.. raw:: manpage
.\" disable justification (adjust text to left margin only)
.ad l
SYNOPSIS
==========
``pdfbook`` <options> infile outfile
DESCRIPTION
============
.. include:: docs/_description.txt
OPTIONS
========
.. include:: docs/_options.txt
EXAMPLES
============
.. include:: docs/_examples.txt
More examples including sample pictures can be found at
https://pdfbook.readthedocs.io/en/latest/Examples.html
SEE ALSO
=============
``psbook``\(1),
``pdfnup``\(1) http://pypi.python.org/pypi/pdfnup/,
``pdfsplit``\(1) http://pypi.python.org/pypi/pdfsplit/,
``pdfgrid``\(1) http://pypi.python.org/pypi/pdfgrid/,
``pdfposter``\(1) http://pypi.python.org/pypi/pdftools.pdfposter/
Project Homepage http://pdfbook.readthedocs.io/