Next post Previous post

A little report formatting script

July 22, 2012 at 8:55 AM by Dr. Drang

Late last year, in the last post of a rather drawn-out series on how my text editing habits have evolved over the years, I described my current workflow for writing reports for work. That post has the details, but the gist of it is

  1. Write the report in Markdown.
  2. Filter the Markdown file through a pipeline of processes (MultiMarkdown, xsltproc, and a couple of small scripts of my own) to convert it first to XHTML and then to LaTeX.
  3. Pass the LaTeX file through pdflatex (possibly a few times to resolve all the references) to get a PDF file.
  4. Apply a ColorSync PDF filter to downsample any photographs in the report to bring the file size of the PDF down to something that can be easily emailed.

I’m sure this seems like an onerous process to others, but it works very smoothly for me. The time-consuming part is actually writing the report, which Markdown speeds up by divorcing me from concerns about formatting while I work on the substance. Running the various scripts and filters to convert the Markdown source into a PDF ready to send to the client is just a matter of running two commands at the Terminal and choosing one Service from the contextual menu in the Finder. The savings I gain from writing in Markdown more than make up for the time taken by post-processing.

Sometimes, though, there’s a Step 2½ that slows the process down. This usually happens when I have an extra-wide figure for the report that needs to be placed sideways on a page. Markdown doesn’t have a mechanism for distinguishing these sideways figures from the others, so I have to go in and edit the LaTeX file by hand before processing it.

I explained in an earlier post how I use the LaTeX rotating package to include and caption sideways figures. In a nutshell, I first add the line

tex:
\usepackage{rotating}

to the document’s preamble. Then I find the figure that needs to be rotated and change its LaTeX stanza from something that looks like this

tex:
\begin{figure}[htbp]
\begin{center}
\includegraphics{widefigure.pdf}
\caption{A wide figure.}
\label{widefig}
\end{center}
\end{figure}

to something that looks like this

tex:
\begin{sidewaysfigure}[htbp]
\begin{center}
\includegraphics[width=8.75in]{widefigure.pdf}
\caption{A wide figure.}
\label{widefig}
\end{center}
\end{sidewaysfigure}

I don’t always need the [width=8.75in] option to the \includegraphics command, and sometimes the width value will be different, but this is typical of the type of change I have to make.

Until this past week, this sort of fiddly editing didn’t bother me much because it always came at the end of the report-writing process, and I’d only need to do it a couple of times as I made final edits to the document.1 This week, though, I was collaborating on a report that had a sideways figure and needed to regenerate the PDF several times as I edited the report back-and-forth with my coauthor. Making these mechanical changes again and again got tiresome and was a distraction from working on the substance of the report. So I wrote a little script called sideways to make the changes for me.

python:
 1:  #!/usr/bin/python
 2:  
 3:  from fileinput import input
 4:  
 5:  lines = list(input())
 6:  
 7:  # Add line for rotating package.
 8:  lines.insert(7,"\\usepackage{rotating}\n")
 9:  
10:  # Find the entry for widefigure.pdf and make alterations.
11:  i = lines.index('\\includegraphics{widefigure.pdf}\n')
12:  lines[i-2] = '\\begin{sidewaysfigure}[htbp]\n'
13:  lines[i] = '\\includegraphics[width=8.75in]{widefigure.pdf}\n'
14:  lines[i+4] = '\\end{sidewaysfigure}\n'
15:  
16:  print ''.join(lines)

As you can see, sideways doesn’t edit the file in place, so I ran it this way in the Terminal:

mv report.tex report-orig.tex; ./sideways report-orig.tex > report.tex

This is a long command, but because bash remembers the command history, I only had to enter it once. Every subsequent invocation was done by either up-arrowing back through the history or searching backwards via ⌃r. I suppose I could rewrite sideways to do the renaming and overwriting for me, but doing it through bash seemed just as efficient.

I make no claim that sideways is clever; it’s basically a retelling in Python of what I had been doing in TextMate. Line 5 slurps in the whole file as a list of lines. Line 8 inserts the code that includes the rotating package. Line 11 finds the wide figure that needs to be rotated. Lines 12-14 make the changes to the LaTeX stanza for that figure.

I’ll never be able to reuse sideways as is—there’s too much in there that’s specific to this one report. But it’s easy to alter to work with another report that needs a sideways figure (or any number of sideways figures—Lines 10-14 can be repeated any number of times). And now that it’s in my toolbox I’ll be able to save editing time even when I’m not collaborating.

As is often the case with the scripts I describe here, I don’t expect anyone else to be able to use sideways directly. I post it here for three reasons:

  1. In case you’re wondering why I’d ever need to do this more than once: every time I edit the Markdown source the LaTeX file gets overwritten and my sidewaysfigure edits are wiped out. ↩

Next post Previous post