Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Tools for writing latex papers

Project Description
########
preprint
########

*Tools for preparing astrophysics papers.* Preprint lets you automatically compile, typeset document differences and package the manuscript for publication.

Installation requires `cliff <https://cliff.readthedocs.org/en/latest/>`_, the `watchdog <https://pypi.python.org/pypi/watchdog>`_ package, the `GitPython >=0.3 <https://pypi.python.org/pypi/GitPython/0.3.2.RC1>`_ package, and a recent version of setuptools.
Preprint also works well with `latexmk <http://users.phys.psu.edu/~collins/software/latexmk-jcc/>`_ for compiling latex, and `vc <http://www.ctan.org/pkg/vc>`_ for adding version control meta data to compiled documents.

To install from PyPI::

pip install preprint

Or to install from source, check the code out and run::

python setup.py install

After installing, try ``preprint --help`` for more info.

Preprint currently supports the following commands (see below for a reference):

- ``preprint make`` to do a one-off compilation of the paper,
- ``preprint watch`` to automatically compile the paper if source is changed,
- ``preprint diff`` to run ``latexdiff`` against a commit in Git,
- ``preprint pack`` to package the document for journals or the arXiv.
- ``preprint init`` to setup your project with ``preprint.json`` configurations.

Check the `GitHub Issues <https://github.com/jonathansick/preprint/issues>`_ to submit additional ideas.

===================
A taste of preprint
===================

Preprint is pretty easy to use.
Here's a few commands to give a flavour of what it can do::

preprint init # this is all the setup you need
preprint make # compiles the doc according to your compile command
preprint watch --diff 8a42f2b # live-updating latex diff against git history
preprint pack my_paper --style arxiv # pack it up for arXiv submission


====================================
Configuration System / preprint.json
====================================

``preprint`` configurations are determined from (in order of increasing precedence): internal defaults, a project-specific JSON file, and command line arguments.

To create a ``preprint.json`` configuration file for your project, from your paper's directory simply run::

preprint init

It will automatically find the root latex file for your paper.
You can open ``preprint.json`` to take a look at its format and modify the configurations further.
Here is an example of its format::

{
"master": "paper.tex",
"exts": ["tex", "pdf", "eps"],
"cmd": "latexmk -f -pdf -bibtex-cond {master}"
}

If set in ``preprint.json``, any command line setting of the same name does not need to repeated.

List of Configurations
----------------------

master
(type: string) Name of latex document to be compiled (or the root latex document containing `\documentclass`).
Defaults to ``'article.tex'``, but ``preprint init`` will set this for you.

exts
(type: list of strings) List of file extensions used by the ``watch`` command.
If any file with this extension in changed in the project, a compile will be triggered by ``preprint watch``.
This setting is also used by ``preprint pack`` to figure out your preferences for figure file types.
For example, ``["tex", "pdf", "eps"]`` will try to include ``pdf`` figures before falling back to ``eps`` files, while ``["tex", "eps", "pdf"]`` will have the opposite behavior.
Defaults to ``["tex", "pdf", "eps"]``.

cmd
(type: string) The command to run when making a document.
This is used by ``preprint make`` and ``preprint watch`` (``preprint diff`` and ``preprint watch --diff`` will always use latexmk).
The command string can include ``{master}`` to interpolate the path of the master tex file.
Defaults to ``"latexmk -f -pdf -bibtex-cond {master}"``.

=================
Command Reference
=================

init
----

``preprint init`` will create a default ``preprint.json`` configuration file for your project.

Usage::

preprint init

After running, take a look at ``preprint.json`` to edit the configurations.
See *'Configuration System / preprint.json'* (above) for more information.

make
----

``preprint make`` will perform a one-off compilation of your paper.

Usage::

preprint [--master MASTER] make [--cmd CMD]

Optional arguments:
--master Name of the root LaTeX file (eg, paper.tex)
--cmd Name of command to run when a change occurs


If ``preprint.json`` is setup, you can just run::

preprint make


watch
-----

``preprint watch`` will automatically compile your paper if a TeX or graphics source file is changed.

Usage::

preprint [--master MASTER] watch [--exts EXT1, ..., EXTN; --cmd CMD; --diff [SHA]]

Optional arguments:
--master Name of the root LaTeX file (eg, paper.tex)
--exts List of file extensions (defaults to `pdf eps tex`)
--cmd Name of command to run when a change occurs
--diff Run a latexdiff compile against the given commit SHA from the git repository (HEAD if blank).

For example, to continuously compile the document whenever ``.tex`` or figures have changed, and assuming you've setup a ``preprint.json`` file with the name of your master document, just run::

preprint watch

To continuously run a latexdiff-based compile, showing all changes you've made against the HEAD of the git repository, run::

preprint watch --diff

The document will be saved to ``build/PAPER_NAME_diff.pdf``.
This is a nice way of keeping track of what you're doing.

Finally, to continuously run a latexdiff-based compile against an arbitrary commit in your git history, just copy the commit SHA fragment (say, ``b91688d``) and run::

preprint watch --diff b91688d


diff
----

``preprint diff`` will typeset the document with revisions highlighted between the currently checked-out version, and a previous git commit.
This command is powered by the `latexdiff <http://latexdiff.berlios.de>`_ (which is probably installed with your tex distribution).
The command also requires `latexmk <http://users.phys.psu.edu/~collins/software/latexmk-jcc/>`_ to compile the difference document.
This command is compatible with documents that use ``\input{}`` to combine text documents; in fact, included documents are inlined recursively.
``preprint diff`` was inspired by `this blog post <http://astrowizici.st/blog/2013/10/04/publishing-with-git/>`_ by Andy Casey.

Usage::

preprint [--master MASTER] diff PREV_SHA [-n NAME]

Arguments:
PREV_SHA A SHA fragment or tag name pointing to the previous revision.

Optional arguments:
--master Name of the root LaTeX file (eg, paper.tex)
-n Output name of the difference document (eg. diff.tex)


pack
----

``preprint pack`` prepares a preprint for submission to a journal.
This pipeline includes:

1. Creating a build directory and copying over just the required manuscript files,
2. Inlining all inputted latex files (either with ``\input{}`` or ``\InputIfFileExists`` syntax),
3. Copying the ``.bbl`` bibliography or inlining it into the manuscript, as necessary.
4. Moving figures to the root directory and updating tex source,
5. Deleting comments; don't be a tweet on @OverheardOnAph,
6. Renaming figures to conform to AASTeX if necessary,
7. Making JPEG versions of figures to to fulfill arXiv file size requirements, if necessary. This requires `imagemagick <http://www.imagemagick.org/script/index.php>`_.

This command is inspired by Erik Tollerud's `Astropysics package <http://pythonhosted.org/Astropysics/coremods/publication.html>`_, but is designed around regular expressions for text transformation.
The implementation should thus be easier.

Usage::

preprint [--master MASTER] pack NAME [--style STYLE; --exts EXT1, ..., EXTN]

Arguments:
NAME Name of the build. Products copied to build/NAME directory.

Optional arguments:
--master Name of the root LaTeX file (eg, paper.tex)
--exts File format priority for figures (e.g., ``eps, pdf``)
--style Style for the build (default is ``aastex``, can also be ``arxiv``).
--maxsize Maximum size of figure in MB before compressing into jpg (for
``arxiv``). Default is 2.5 MB.

Note that the ``--exts`` option can be used to prefer a certain file format for the build if you maintain both EPS and PDF figure sets.
For example, to generate a manuscript for a AAS journal, run::

preprint pack my_aas_build --style aastex --exts eps

And to build for the arxiv, where PDF figures are preferred, run::

preprint pack my_arxiv_build --style arxiv --exts pdf

=====
About
=====

`Preprint is developed on GitHub <https://github.com/jonathansick/preprint>`_.
Contributions and suggestions are welcome;
read `the CONTRIBUTING guidelines <https://github.com/jonathansick/preprint/blob/master/CONTRIBUTING.md>`_ for instructions on how to help.

Copyright 2014 Jonathan Sick, @jonathansick

Licensed BSD.
Release History

Release History

This version
History Node

0.3

History Node

0.2.2

History Node

0.2.1

History Node

0.2

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
preprint-0.3.macosx-10.10-x86_64.tar.gz (20.4 kB) Copy SHA256 Checksum SHA256 Source Jan 12, 2015
preprint-0.3.tar.gz (15.5 kB) Copy SHA256 Checksum SHA256 Source Jan 12, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting