workflow

run getcontents on your article PDFs to get a basic contents file.

Generate a front matter PDF (e.g. with a cover and a mostly-blank contents page). This will be the first section of the document.

Add more information to the contents file.

Assemble the PDF with assemble.

Iterate contents placement and layout and reassemble as needed.

getcontents

Examines a set of PDFs for title and author information, and produces a basic contents JSON file on stdout.

./getcontents A.pdf B.pdf C.pdf >contents.json

If your contributors don't set title and author correctly, edit that contents file to fix it.

If you put an existing contents.json on the command line, new PDFs will be added to the end of the article list.

./getcontents contents1.json D.pdf E.pdf F.pdf >contents2.json

the contents file

output is the output filename.

title and author will set PDF metadata.

frontmatter is the filename of the front matter file (cover and contents page), if any.

articles is an array of dicts each describing an individual article.

contents is a complex dict for styling the contents page.

a dict in the articles array

It must contain "file", "author" and "title" keys (generated by getcontents). It may also usefully contain.

top - number of pages to drop from the start of this PDF (default 0).

tail - number of pages from drop from the end of this PDF (default 0).

start - "recto" (start on right-hand, i.e. odd-numbered, page) or "verso" (start on left-hand, i.e. even-numbered, page). This will insert a blank page if needed. If unset, no blank page will be added.

the contents dict

page - the page number within frontmatter to receive the table of contents.

y - the Y-offset of the first line of the contents. Negative is offset from top of page. In PDF points, 1/72 inch.

font and size - the default font and size for contents items. This will be used if you don't specify an individual font under "columns", and for the separator characters. font is either a TrueType/OpenType filename (which will be embedded as needed), or one of the built-in font names (see below).

leading - the line spacing. Typically equal to or slightly more than size.

separator - the character(s) used to separate content fields and give a visual lead to the next field.

columns - column definitions. An array of dicts.

column definition dict

x - x offset from left of page, negative from right of page. In PDF points, 1/72 inch.

text - the text for that field. A word @WORD@ will be replaced by the corresponding item from the article list, most usefully "title" or "author"; "page" is also available.

Optionally a column definition may also include font and size, which work as above in "the contents dict".

built-in PDF font names

These fonts are defined in the PDF standard and are guaranteed to be available on every reader.

Courier, Courier-Oblique, Courier-Bold, Courier-BoldOblique, Helvetica, Helvetica-Oblique, Helvetica-Bold, Helvetica-BoldOblique, Symbol, Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic, ZapfDingbats

assemble

Given a contents file, assembles the composite PDF.

./assemble contents.json