In each Supreme Court brief that SFLC has filed over the years we have included a little note on the first page declaring that the brief was made using only free software. This point was particularly important in our most recent brief, for a case named Alice Corporation v. CLS Bank, which was argued in front of the court last week. Our use of free software was particularly important this time because we argue in our brief that free software has been responsible for the major software innovations of the modern era. In partial support of that claim I want to show you our document creation process and tell you about the free software we use to take text from an email and turn it into a camera-ready Supreme Court brief, then a website, then an eBook.

1: Markdown – the drafting tool

The first tool we use, markdown, is a standard way to use keyboard characters like *, #, and [ ] to indicate what parts of a text should be italicized or in bold and which parts are things like headers or footnotes. Using standard characters to indicate these formatting options helps keep the focus on the text and makes it possible to use a variety of collaboration tools during drafting like etherpad, wikis, and version control systems.

While we have all of those tools running at our office, and used many of them to share drafts of the brief, the initial versions of the CLS brief began as simple email messages. Markdown is a great tool for sharing documents via email because you can include the text of the message directly in the body of the message making it easy to make edits or add comments just by replying. Keeping the text of a document inside the email message also keeps every version track-able and search-able with your normal email tools. Contrast that to the common practice of sending documents around as attachments and how hard it is to identify which of the dozen files you may have is the first time a particular piece of text was introduced or a particular change was made.

2: Pandoc – the swiss army knife

Our second tool, pandoc, helps us translate the simple formatting and structure marks from our draft into whatever type of more formal document we need. When it comes to conversion, Pandoc is a swiss army knife that can turn our Markdown document into a webpage, word processor document, Wikipedia article, eBook, or many other formats. The format we want is LaTeX, which is a system for laying out complex documents that require precise formatting. It is commonly used for books, résumés, journal articles, dissertations, and, in our case, Supreme Court briefs.

To convert our “draft.mkdn” document to LaTeX we simply run “pandoc draft.mkdn -o draft.tex” which tells pandoc to look at the markdown file and output a LaTeX version of it. Since “.mkdn” and “.tex” are standard extensions for Markdown and LaTeX formatted documents, Pandoc understands the conversion we want it to do without any other instructions. For now that one command is all we want from pandoc but we will come back to it when building our eBook later on.

3: LaTeX, a personal print shop

Our third tool, LaTeX, is the software version of a professional print shop. It has everything you need to format and lay out documents down to the smallest printing measurement. This is different from a word processor in two important ways. The first is that LaTeX has a professional quality typesetting engine that calculates optimal spacing and line breaks. The result is simply beautiful documents. Take a look at this sample text printed as either a LibreOffice word processor document (pdf) or using the default LaTeX settings (pdf). Try printing that text with whatever tools you normally use and see which one you think is more attractive and pleasant to read.

The second important difference between LaTeX and a word processor is that LaTeX keeps the layout and document formatting information separate from the document contents. Importantly for us, this means we can do the complicated work of specifying all the Supreme Court’s detailed document requirements for briefs just once and then reuse that for each brief we file. We can even share that formatting file with you (brief.cls) so you can study how it works or use it for your own Supreme Court brief.

Once our draft text is in LaTeX format, which we get from pandoc, the final rounds of editing and polishing begin. This is the stage where we make sure that all the citations are correctly formatted and everything looks good on paper. For the CLS brief we made a couple tweaks, adding a page break before the last section so the last page would have more than two lines on it and deciding to indent the subheadings in the table of contents by adding a new option to the formatting “class” file.

When everything looks good, LaTeX creates a PDF that we can send directly to the printer for binding and delivery. Because all of the formatting work is done by LaTeX our document is “camera ready” which means we never have to worry about problems like using a different word processor version from the printer. As soon as the document leaves our hands we have complete confidence about how the document will look when printed. If there were any question about pdf compatibility LaTeX could even output a version in printer-native postscript format. As far as the court is concerned, our work is done once we send the file to be printed but we feel it is important to make the work we do as widely available as possible. To that end we try and share our publications in as many formats as possible that people might want. Our next two steps will take the same LaTeX file and turn it into a webpage and then an eBook.

4: Tex4ht

Turning a LaTeX file into a webpage is greatly helped by a tool called tex4ht which is an entire webpage layout engine built for LaTeX. The resulting website code can be a bit unorthodox when preserving some of the print features not used online, for instance small caps are created by formatting each letter separately and matching up the sizes, but it is very effective at transforming even complicated print documents into websites. It is the natural choice for something like a Supreme Court brief. You can see the results of running tex4ht on our final LaTeX brief at our site, which is basically unchanged from the default output of running “tex4ht alice-cls-amicus.tex” except for adding our standard website header and removing some extra dashes on the cover page.

5: Calibre

Transforming our LaTeX brief into an eBook begins with pandoc, the same tool we used to create our first LaTeX draft out of markdown. In addition to working with markdown, pandoc is able to convert to and from a number of other formats, including translating LaTeX into the “epub” eBook format. This is an important feature for us since, however careful our drafting efforts, some changes always creep in once our brief has moved out of markdown and into the review and proof reading passes. Pandoc’s ability to read as well as create LaTeX documents lets us focus on editing the document rather than worry about which format it is in during a particular editing step.

To get a rough version of the ebook we want we just run “pandoc alice-cls-amicus.tex -o Initial-eBook.epub” and pandoc will figure out what format we want from the file extensions. Because pandoc lacks some of the creative formatting tricks that tex4ht uses, like creating a word in small caps by formatting each letter separately, this initial eBook version is missing some of the elaborately formatted parts of the brief like the cover page.

Once we have this initial eBook we can polish up the rough edges using a free eBook library program called Calibre. Adding our draft to the Calibre library gives us access to a whole editing toolkit. Just select the book and hit the big “edit” button in the main toolbar. Since eBooks are basically websites, this final stage of processing is actually simple HTML editing. Conveniently, this means that we can replace the missing cover page by copying and pasting that portion from our website version. Since pandoc preserved all of the in-text formatting like italics and long dashes, all that is left to do is make sure that the sections and subsections all have appropriate HTML heading numbers, add in the spacing dots on the table of authorities, and tell Calibre to generate a table of contents.

This was actually my first time editing an eBook so that whole process tool me about an hour.

Conclusions

If you have only ever produced documents using commercial word processing software, many of the tools I have described here may seem strange to you. Like so much of Free and Open Source Software, the tools we use for making documents come from a variety of different authors who each produce documents their in own ways. The particular tools we use at SFLC have been chosen over the years as our practice grows and evolves. Whether you are looking to replace your document tools entirely, try out a new way to turn emailed text into word processor documents, or just see what it looks like to take free tools and put them together into a system that fits your office, I hope this has been an informative look at some innovative free software.

(Originally posted 2014-04-11 on the Software Freedom Law Center’s Blog)