latex letter support

[jasonpearcy]

Are there any objections to modifying the default latex template to add letter support?

Other templates already exist, such as https://github.com/aaronwolen/pandoc-letter. Rather than keep using a custom template,
I'm wondering if others would find it a useful addition.

[jgm]

It's hard to say without seeing what changes would be entailed.

[jpcirrus]

Using which letter class or package: letter, scrlttr2, isodoc, scrletter...?

An issue with using the letter class is that it is limited in comparison to the scrletter package included with KOMA-Script, which can be used with the standard classes as well as the KOMA classes (memoir?), and is arguably more flexible and complete, incorporating the features of the scrlttr2 KOMA letter class.

Previously @tarleb had contributed the scrlttr2 Lua filter, now deprecated in favor of the pandoc-scrlttr2 template.

Because there are so many letter options, if the default template was modified there would likely need to be something like a letteroptions variable to allow individual customization.

For my purposes, I have modified the default latex template to use template partials when a letter variable is set. This has required 9 ${if/elseif(letter)} conditionals, and the command line arguments: --defaults=letter --metadata-file=letter-SENDER.yaml

[jgm]

With the default template we prefer the document classes that don't require special packages.

[twsh]

I don't know whether it should be part of Pandoc, but an updated and maintained version of the pandoc-scrlttr2 template would be nice. I raised an issue about it being out of date here: JensErat/pandoc-scrlttr2#23

I also thought a bit about some improvements to the template, like using the scrletter.sty package and partials, although it works fine how it is. I was a bit reluctant to take it on, but it wouldn't be that much work if a few people helped.

[jpcirrus]

I would be happy to work on this from around 20 December, which is when I'm going to have time, as I intend to amend my customized default template to use the scrletter package anyway. It would therefore take little effort to incorporate those changes with the default template to create a new letter template. In that case there would be no need for partials, but would need to make it as flexible as possible to meet the needs of others.

[twsh]

@jpcirrus If it would be helpful, I can look at/test the template.

[jpcirrus]

Thanks. I'll ping you when done for your feedback. Will probably be early in the new year.

[jgm]

I think my view is that this is a job for a separate custom template, and that trying to handle it with conditionals in the default template will lead to confusing complexity.
We could think about including a separate letter.latex template in the default distribution, though; then you'd just need --template=letter.

[jasonpearcy]

Thanks for the comments! So to consider adding letter support in the default distribution:

1. Create a new template rather than modifying the default.latex template.
2. Add support for multiple document classes such as letter, scrletter, and scrlttr2.

[jpcirrus]

I started off with a custom letter template, using a stripped down copy of the default template, but found over time that more and more default template features were required (e.g., headings, tables, figures), and when working in Europe that certain countries had standards for business letters that needed to be met (e.g., DIN 5008 in Germany and NEN 1026 in the Netherlands). I know too that some Asian countries have letter standards. Also, because I was already using a customised default template that having to keep two templates synced with the upstream changes to the default template became a chore. And, I suspect why the separate beamer template got included in the default latex template. Hence, as soon as pandoc supported template partials, I converted to the method described above.

If a separate letter template is included, I would suggest that instead of using a letter class, to rather use the scrletter package, which as part of the KOMA-Script bundle is included as part of the TeX Live latex-recommended collection, installed as part of the minimal BasicTeX download. Then all the standard classes and KOMA classes are supported (not sure about memoir). This way users can choose their own document class and a number of the letter standards can be met out of the box using the included "letter class files", as I'm certain requests for standards support will come quickly. Comprehensive documentation is provided in scrguide-en.

BTW I didn't do this. Initially using the letter class and later, when requiring German correspondence and invoices, the isodoc class. This was because I was new to pandoc, latex, and at that time the KOMA english documentation hadn't been translated by a native english speaker so was difficult to understand, and I needed to generate correspondence quickly. I now regret it, and when time allows intend to convert to scrletter.

[jgm]

One thing I'm tempted to try doing is splitting off much of the existing latex template into partials.

We could then have separate templates for beamer and for letter, and they could just import these partials to avoid code duplication.

The existing combined latex/beamer template is quite cumbersome, with all those conditionals, so I think this would make things a bit clearer and easier to maintain.

[jgm]

I am working on this approach in the latex-partials branch.

[jasonpearcy]

I've created a PR for proposed changes: #10280

[twsh]

That's great. I will make some comments on the PR.

[jgm]

I had come up with a letter template in the latex-partials branch, but reverted it before merging. Here it is, for comparison:

\documentclass[
$if(fontsize)$
  fontsize=$fontsize$,
$endif$
$if(papersize)$
  $papersize$paper,
$endif$
  ]{scrlttr2}
\usepackage{graphicx}
\usepackage[absolute]{textpos}
$fonts.latex()$
$common.latex()$
$for(header-includes)$
$header-includes$
$endfor$
$after-header-includes.latex()$
$hypersetup.latex()$

\date{\today}

\renewcommand*{\raggedsignature}{\raggedright}

\setkomavar{fromname}{$fromname$}
\setkomavar{fromaddress}{$fromaddress$}
\setkomavar{fromphone}{$fromphone$}
\setkomavar{fromemail}{$fromemail$}
\setkomavar{signature}{%
$if(sigfile)$
  \includegraphics[width=$if(sigwidth)$$sigwidth$$else$5cm$endif$]{$sigfile$}\\
$endif$
$if(signame)$
  $signame$
$else$
  $fromname$
$endif$
}
\setkomavar{backaddress}{$backaddress$}
\setkomavar{location}{\raggedright
  $location$
}

\KOMAoptions{
  foldmarks=off,
  fromrule=true,
  fromalign=center,
  firsthead=true,
  firstfoot=false,
  parskip=half,
  addrfield=$if(toaddress)$true$else$false$endif$,
  DIV=12
}

$if(firstheadvpos)$
\setplength{firstheadvpos}{$firstheadvpos$}
$endif$
%-- \maxdimen = letterhead is centered
\setplength{firstheadhpos}{$if(firstheadhpos)$$firstheadhpos$$else$\maxdimen$endif$}
$if(letterheadwidth)$
\setplength{firstheadwidth}{$letterheadwidth$}
$endif$
$if(toaddress)$
$else$
$-- avoid extra vertical space where toaddress would go
\setplength{refvpos}{2in}
$endif$
$if(letterhead)$
\firsthead{$letterhead$}
$endif$

\begin{document}\raggedright

%\areaset{$if(textwidth)$$textwidth$$else$6in$endif$}{$if(textheight)$$textheight$$else$8.5in$endif$}

\begin{letter}{$toaddress$}

\opening{$opening$}

$body$

\closing{$closing$}
$if(ps)$
\ps $ps$
$endif$
$if(enclosures)$
encl{$for(enclosures)$$enclosures$$sep$\\
$endfor$}
$endif$
$if(cc)$
\cc{$for(cc)$$cc$$sep$\\
$endfor$}
$endif$

\end{letter}

\end{document}

I'm still not sure whether it makes sense to have a letter template in the default pandoc distribution. Usually these things need to be customized to fit specific organization requirements (exact placement of letterhead, for example), so I'm not sure how valuable a default template would be. But, open to discussion.