25 November 2018

TL;DR: If you want to include additional material after the closing of a newlfm letter, forget the builtin \restletter commands. Add \newcommand\closelfm{\closlfm\let\closlfm\relax} to your letrinfo.tex file, put \closelfm where you want to end the letter (optionally followed by a \newpage), then write the additional material using standard L^aT_eXmarkup.

I use the newlfm L^aT_eXpackage for all letters I write, personal and professional. It has some nice advantages over the standard letter document class: you can have a database of different sender and recipient addresses, signatures and letterheads; it's easy to create custom letterheads that include images; you can have the correct letterhead and signature selected automatically based on sender or recipient. And many other features I don't make use of.

I have a love-hate relationship with this package, though. It has some quirks/bugs, especially to do with page layout and spacing. And whilst the documentation is extensive, it's not always the clearest. Whenever I need to do anything slightly different to what I've done before with newlfm, getting it to do what I want typically involves hours of effort and frustration the first time around, and I often ending up resorting to ugly kludges to get the letter written without wasting too much time. (This probably says more about my limitations, than those of the package.) Nonetheless, once you have a letter layout configured just the way you want, writing new letters with the same layout with newlfm is a breeze.

I was recently writing a cover letter to accompany the revisions I was submitting to one of my research papers. I wanted to attach the detailed response to the referees' comments after the letter (which contained a lot of maths^{11 1}This is one of my papers after all! so was best written in L^aT_eXtoo). The easy thing would have been to write the cover letter using newlfm, write the review response as a separate L^aT_eXdocument using some other document class, and stitch the two PDFs together using the pdftk command-line tool (or similar). But having to write these as two separate documents bugged me. I was already writing the cover letter in L^aT_eX. Why not just write the detailed referee response in the same L^aT_eXdocument?

In newlfm, the entire letter content has to be wrapped in a \begin{newlfm} … \end{newlfm} environment. Why wrap everything in an extra environment? Aha, you think! This is in case you want to include additional content after the letter. By wrapping just the letter part inside the newlfm environment, you can put additional content after \end{newlfm} but before \end{document}. Problem solved!

Wrong. If you do that, the formatting of the content outside the newlfm environment is messed up: it has the wrong margins, the page header overlaps the content, the page footer isn't even on the page, and all kinds of other breakage. As far as I can tell, you have to surround the entire document contents (i.e. everything between \begin{document} … \end{document}) inside a newlfm environment. An extra layer of wrapping you have to add to every letter your write. From my armchair seat,^{22 2}I.e. without having read the newlfm source code, let alone tried to do anything to improve this myself! I sweepingly claim this could have been implemented more cleanly and elegantly by having the package insert the necessary code at \begin{document} and \end{document} instead. But there you go.

So you go to the newlfm package documentation, and notice a section entitled "Printing information on additional pages". This looks promising! It goes on to say:

In many letters, the letterhead page is to be followed by additional information on additional, non-letterhead pages. This may be done using the \restletter{text}, \restlettera{text}, \restletterb{text}, \restletterc{text}, \restletterd{text}, and \restlettere{text} commands.

But read a bit further; there's a stinger at the end:

These blocks must not have spaces. If paragraphs are to be used, use \paragraph to force the new paragraph without an actual blank line. In addition, extra material in each section is limited to a single page.

Hmmm. So if you want to write more than one paragraph, you have to resort to ugly kludges;^{33 3}Which, as far as I can tell, don't work anyway. Inserting a \paragraph command just gives compilation errors, at least for me. if you want to write more than one page, you have to manually split the content into separate pages and put each page in a different \restletter<x> command; and if you want to write more than five pages^{44 4}It turns out the \restletter command is an alias for \restlettera – not that this is documented anywhere – so you only have five \restletter's at your disposal, not six. you're out of luck! My referee response ran to more than five pages, contained many paragraphs, as well as quote environments and other things \restletter chokes on. The documented newlfm commands weren't going to help here.

The danger of authoring a handful of L^aT_eXpackages is you're no longer as scared of delving into other packages' code. At this point, curious where the restrictions on \restletter content came from (and whether perhaps I could improve this), I started looking through the newlfm.cls code. Here's how (the relevant part of) \restletter is implemented:

\def\restletter#1{%
  \begin{lrbox}{\@resta@ltr}%
    \begin{minipage}{\textwidth}%
      #1%
    \end{minipage}%
  \end{lrbox}}

In other words, \restletter wraps its contents up in a full-width minipage environment, then squirrels this away in an \lrbox (which is much the same as a \savebox) for later use. The minipage is what prevents you from having content that goes over 1 page.^{55 5}Or rather, you can, but L^aT_eXwon't break it across pages, so any material longer than that will run off the bottom of the page. The \lrbox is what prevents you from using blank lines and various other L^aT_eXenvironments in the content.

I couldn't see any easy way to improve the \restletter command, short of reimplementing it from scratch using a completely different mechanism.

But now I was delving into the newlfm.cls code, what about simply fixing up the layout issues with document content coming after \end{newlfm}? Should be easy, you think! Just a matter of ensuring the L^aT_eXpage layout parameters are set the same way for the entire document as they are within the newlfm environment.

Wrong. The newlfm package defines it's own set of page layout parameters. It then calculates and sets the standard L^aT_eXpage layout parameters from its own versions in the \begin{newlfm} code.^{66 6}For good measure, newlfm also deliberately cripples the geometry package if you try to load it. I started trying to trace through this page-layout-setting code…and gave up. Like most T_eXcode it's somewhat convoluted, mostly uncommented (even in the newlfm.dtx literate source), and in this case sprinkled throughout with what looks like debugging code.^{77 7}If you're reading along in the source, have a look at the \txa macro and \ifta flag. There are also \txb and \iftb versions, for kicks. This debugging code is disabled in the released package, but makes it hard to tell what's relevant and what's not when reading through the source code. What about at least turning this debugging code to good use, by re-enabling it? Nope. I'm not sure why, but instead of being enabled by a global flag, it's enabled by a global flag…that gets unset again every few lines of newlfm code.

By this time, I'd already spent far too long trying to figure out how to put the letter and addtional content in the same L^aT_eXdocument. Far too long to give up, that is! But everything seemed to lead towards delving in and making significant changes to the newlfm implementation – a major undertaking I really didn't have time for just then.

Time to take a step back, and think about what I was trying to achieve. What exactly defines the "letter" part and the "additional content" part, when this is all bundled up in one PDF document? Easy. The letter starts with some standard preamble (from- and to-addresses, date, greeting, etc.) and ends with a signature. Anything after the signature is "additional content" (which should probably start on a separate page). So from the perspective of the final PDF, all I was trying to do was to place the signature somewhere in the middle of the document, and then continue with more document content.

newlfm automatically inserts the signature at \end{newlfm}. Remember that everything needs to be wrapped in a newlfm environment. So this idea didn't seem too promising. Without much hope, I delved into the newlfm code once more to see how it actually generates the signature. Here's the relevant line from the \end{newlfm} part of the \newenvironment definition:

\ifthenelse{\boolean{@pr@p}}{\closlfm}{}

Bingo! A single \closlfm macro takes care of generating both the letter closing and the signature at the end of the letter. A quick test revealed that this macro also works fine if used in the middle of a letter. But then you get two signatures: one where you inserted a \closlfm, one generated by the above line in \end{newlfm}.

However, a simple T_eXtrick lets us suppress the second signature without having to make any changes to the newlfm code: after using \closlfm in the middle of a letter, just issue a \let\closlfm\relax. This redefines the \closlfm macro to do nothing, so when \end{newlfm} calls the macro again, it doesn't produce a signature any more.

We can conveniently turn this into a single command that inserts the letter closing and signature at the point it's issued, and then disables any further signature generation:

\newcommand\closelfm{\closlfm\let\closlfm\relax}

We could include a \newpage at the end of this command, to force content after the signature to appear on a new page. But I prefer to leave the \newpage up to the letter author, just in case we ever want additional content on the same page as the letter.

As a final nicety, we can make this new feature available in all our newlfm letters, by exploiting newlfm's letter database feature. From- and to-addresses, letterhead definitions, signatures etc. go in a file called letrinfo.tex. The newlfm package loads the letter database by just \input'ing this file. So if we add the above \newcommand definition to letrinfo.tex, the command will always be available if we need it.

The effort-per-line-of-code ratio might have been rather high. But in the end I was very surprised and happy to have found an elegant one-liner that fixed my newlfm problem, without needing to hack the newlfm code at all!