Skip to content

Latest commit

 

History

History
118 lines (66 loc) · 6.28 KB

README.md

File metadata and controls

118 lines (66 loc) · 6.28 KB
Raw

⚠️ This is a work in progress. If you're still interested, get in touch and I'll tell you about the state of the project. ⚠️

papermill.

write once, publish everywhere

p

papermill is a toolchain for cross-publishing long form text to different media. The text can be something like an academic paper, an essay like static websites, an Ebook or a printable PDF.

It aims to provide the best possible output, with minimal manual labor and configuration. Just 'drop in' your Markdown formatted text file and you'll instantly get a static website and a printable PDF (via LaTeX).

Instead of a framework, papermill rather tries to be an opinionated collection of the best tools, standards and practices currently in use, combined with simple scripting to glue it together.

Workflow

⚠️ For now you have to figure out most of the stuff yourself. I will write this as I go along. ⚠️

  1. Get the Makefile.
    curl foo/Makefile (not implemented)

  2. Check dependencies (see under Tools)

  3. Setup your Document
    make plain (not implemented)

  4. Drop in your Markdown-formatted text. open paper.markdown

  5. make html

  6. make pdf

Goals

  • modularity -- use all the scripts and get stuff done or implement part of the chain by using different tools.

  • distinguish between client and server, but work local anyway

  • no dependencies other than core tools and POSIX: a project like this has a shitload of dependencies anyway. I don't want to make it worse by adding even more -- what comes with any UNIX and Linux is plentifull.

Tools

high-level overview

Text Input

  • Git -- version control voodoo software. Takes care of your files and their history -- it's a neverending palimpset! Plus it provides ways to collaborate with editors and sync with remote servers. It also has hooks which we can use for automation.
  • Markdown -- plain text formating that goes out of your way, by John Gruber.
  • pandoc -- Markdown is for web writers, but papermill is for everyone. pandoc provides extensions we need with a consistent syntax: Citations, Footnotes and Bibliography.
  • mustache -- logic-less templates for (almost) everything. Also its successor handlebars.
  • BibTex -- commonly used with LaTeX, stores your bibliography info in a (plain text) database.

Output Generation

  • make -- a good old friend from *NIX which, according to it's manpage "shall update files that are derived from other files", which is precisely what we are doing here.

  • punch -- your friendly neighbourhood static website generator. Actually, it can be used for any kind of text files (just like mustache). This can be used to even generate your Mardown if you are working with data collections. Right now papermill can generate an picture catalogue from a JSON file.

Website Output

Print Output

Is taken care of by pandoc by converting the text to LaTeX, providing a PDF output suitable for print and the ability to use costum LaTeX templates.

Literal LaTeX code can be used in the text and will only affect print output. This can be used to insert a \pagebreak[4] where a page break is wanted in the print output.

The downside is that (right now) there is no way to add certain other codes like the LaTex logo itself (i.g. \LaTeX) while providing a fallback for the web output. This is one of the problems this projec wants to solve. Still, it should not be an huge issue in an academic context (where a lot of literal LaTex might be needed). Here the PDF output is needed as a final version and the web output serves as a preview since most papers can't be published online before they are turned in, graded, etc.

E-Book Output

Is also taken care of by pandoc, which has support for a wide range of output formats in general.

Right now, the status is alpha quality: It produces output for simple texts, but some stuff breaks which shouldn't. Output to ePub is usable at least for proof reading on eBook devices.

Roadmap

  1. better web output -- think "book as web application". This is currently done in pandoc-bootstrap.
  2. better workflow (also as web app)
  3. better collaboration by integrating even more with git

Alpha Testers

Alpha Testers (authors, writers) are needed to not loose touch with reality. If you found this by accident, chances are you are a valuable candidate -- please get in touch.

Alpha Testers so far:

List of considered names for this project:
papermill. paperfront. paperboy. papermache. papermachine. papeterie. Passepartout. tangeable.
Impact -- Impackd -- Imprint.
formatters -- form&matter -- form matters.
Publish or perish -- P.O.P. -- PopUp.
Samizdat.

List of possibly further inspiring Words or Wikipedia Articles:
Vanity.