A couple of weeks ago, I sent the latest copy of the FLOSS UK newsletter (my last as editor) to the office for printing and distribution.
When I became editor I inherited a build system from Roger Whittaker, which took a collection of XML files and transformed them through a series of steps into LaTeX and then produced a PDF. The process worked well, and I used it for several issues, but there were a few niggles:
- Short articles (around three paragraphs or less, though the cut-off varied) would sometimes fail, requiring the manual insertion of empty paragraphs.
- Python 2.x was required – not a problem when the build script was written but some Linux distributions are moving to Python 3 by default now.
- Every article had to be specified manually in a list of contents, and it was easy to miss something out.
- Every article had to be marked up in XML, including all the paragraphs.
- I couldn’t work out a way of including images and colour.
None of these issues were mission critical, but they did increase the amount of time required to produce the newsletter. Since the newsletter is produced on a voluntary basis, I had a strong incentive to reduce the amount of time required, so I looked into a variety of ways to simplify the process.
In the end, the solution I chose was to make each article in the newsletter a separate file, using Markdown for formatting. These files are then combined using a small Bash script and then Pandoc is used to produce the final PDF. I created a custom LaTeX template based on the Pandoc default to change the fonts and add the FLOSS UK logo to the top of the first page.
The new process achieved several goals:
- Adding a new article involves dropping a file into the relevant directory following a file naming convention. No need to edit a list of contents.
- Nearly all markup has been removed from the articles, making them easier to edit.
- The build process is now contained in a single file, which is only 39 lines long (including blank lines and comments) and doesn’t rely on any specific version of Bash.
- All the build dependencies are available as pre-built packages in the majority of Linux distributions (and OS X, though GNU sed is required).
- Images can be included easily and colours are available.
There are still a few outstanding issues which I hope to fix over the coming months, but overall I’m pleased with how much time the new process saves. If you’d like to use a similar process for your newsletter, the code is available on GitHub under the MIT licence.