poetry_ebook_utils: Scripts to Publish Poetry in PDF, EPUB, and Kindle

A couple of years ago, I self-published my first collection of my poetry in print and on Kindle. In a comment on a project status update about a year and half before its publication, the author of one of the \LaTeX packages I use suggested I post the “integration code” I had developed in the course of the project. I recently, finally, did just that.

This poetry_ebook_utils repository contains a nearly-complete apparatus for publishing a collection of poetry in PDF (and thus print), EPUB, and Kindle formats from source files in \LaTeX and Markdown formats. With two exceptions, everything is licensed under the \LaTeX Project Public License; those exceptions are the sample CSS (for which I have released my claims to the public domain) and a snippet I got from a StackExchange answer that is therefore under the Creative Commons Attribution-ShareAlike license.

The remaining work is divided, for licensing purposes, into two projects distributed together. The first is the “integration code” we had been discussing back in July 2013: a set of commands to allow an author to switch between poetrytex or poemscol, the two readily-available \LaTeX packages for typesetting poetry collections, by changing only a single line in the \LaTeX code. It defines the following \LaTeX commands:

  • First and most importantly, \poemscompat, which takes two arguments and evaluates exactly one of them, depending on whether \POEMSCOL or \POETRYTEX is defined.
  • If poemscol is the selected interface, it provides the same commands to define a dedication page as poetrytex does.
  • The \compattitle defines the author and title of the collection using the preferred commands of whichever package the user chose.
  • It redefines the poem environment, which now takes three arguments (and encloses the text of the poem): the title, the subtitle, and the incipit, any of which may be blank.
  • Since poemscol provides a \verseline command and poetrytex doesn’t, and I also found I needed a variant to prevent page breaks after some lines, the package ensures that \verseline and \verselinenb are defined.
  • In addition to poems, poemscol allows users to break them into stanzas and organize them into sequences, possibly with multiple sections in a sequence, while poetrytex provides a command for the space between poems, organizes poems into “poem groups,” and supports untitled poems identified by their incipit. Depending on which package is selected, my poemscompat code defines the commands (in those areas) supported by the other in terms of the selected package.
  • It also defines a \silentincipit alias for the “starred” variant of the \incipit command provided by poetrytex.
  • Finally, its \includepoem command wraps the contents of a \LaTeX source file in a poem environment; it takes the name of the file to include, the title to index the poem under, the title to print, the subtitle if any, and the incipit or other designation; only the first and either the third or the fifth argument are required. (The command takes an optional different title for indexing because \LaTeX indexing packages treat the # character specially.)

The “second project” in the poetry_ebook_utils repository is the shell and Makefile code to turn \LaTeX and Markdown input into PDF, EPUB, and Kindle ebooks. It consists of three main files:

  • bin/md2tex.sh is a shell script that turns a poem in Markdown format into equivalent \LaTeX ready to be included into a collection using the \includepoem command. It expects the incipit or first line to be marked as beginning with the (non-printing) Unicode “interlinear annotation” control characters, and replaces those characters with a surrounding \incipit{} or \firstline{}, depending on whether the control characters are doubled or not. It also trims off any lines that start with a Markdown header or contain URLs, surrounds each verse paragraph with a stanza environment, replaces the Markdown italics idiom I typically use in poetry (surrounding the text to be italicized with _) with \emph{}, and substitutes the \LaTeX representation of double quotes for the “straight” quotes used in Markdown, and appends \verseline to every line of poetry except the last lines of stanzas.
  • bin/ebook_builder.sh turns Markdown poems and \LaTeX or Markdown “front matter” and “back matter” and assembles them into an HTML or EPUB ebook. It parses the author, title, and dedication from the “front matter,” and translates common \LaTeX idioms (and not-so-common ones that my collection used) to equivalent Markdown ones, which the pandoc tool then converts to HTML for the final output. In the “main matter” it follows \input and \include commands recursively to find poems and images to include; poems are assumed to be present in Markdown format (having been converted from thence to \LaTeX by md2tex.sh, though converting the other way if a Markdown file isn’t present wouldn’t be too hard a feature to add), while it looks for SVG, PNG, and JPEG images.
  • distrib.mk is a Makefile fragment that allows PDF, EPUB, and Kindle format ebooks to be built with a single command (make). It depends on the pdflatex-makefile project for building PDFs, and requires callers to define a variable PDFLATEX_MAKEFILE containing the path to the Makefile fragment provided by that project; users should also define POEMS_DIR and ILLUST_DIR as the directories containing Markdown-format poems and illustrations, respectively, and COVER to be the path to the cover image.

As I mentioned, these are now available on GitHub for other poets to use if they wish. I hope they prove helpful to you as they were for me.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s