Author and affiliation tangle in pandoc templates

[baptiste]

I naively started a template for APS (American Physical Society) journals, which relies on Revtex-4-2..
I thought I'd take inspiration from the ACS extension (what is Chemistry for, after all). It all seems reasonably straight-forward, with one glaring exception: the formatting of author-affiliation lines.
Every journal seems to reinvent the wheel here, and some strategies are easier than others to implement. I was wondering if we could share some of those strategies in one place, to help development of such templates (maybe I've missed such a resource already?).

In the case of APS (revtex, really), the expected format is:

% repeat the \author .. \affiliation  etc. as needed
% \email, \thanks, \homepage, \altaffiliation all apply to the current
% author. Explanatory text should go in the []'s, actual e-mail
% address or url should go in the {}'s for \email and \homepage.
% Please use the appropriate macro foreach each type of information

% \affiliation command applies to all authors since the last
% \affiliation command. The \affiliation command should follow the
% other information
% \affiliation can be followed by \email, \homepage, \thanks as well.
\author{}
%\email[]{Your e-mail address}
%\homepage[]{Your web page}
%\thanks{}
%\altaffiliation{}
\affiliation{}

%Collaboration name if desired (requires use of superscriptaddress
%option in \documentclass). \noaffiliation is required (may also be
%used with the \author command).
%\collaboration can be followed by \email, \homepage, \thanks as well.
%\collaboration{}
%\noaffiliation

The mention of

\affiliation command applies to all authors since the last \affiliation command.

fills me with dread when I think of how to code this in pandoc's template mini-language.

I'm not new to the author-affiliation problem, in fact years ago I created a helper Shiny app that took Yaml-formatted metadata and produced the journal-specific header lines (title, author-affiliation, etc.) as a LaTeX file. This was easy to code because I had the expressive power of R to wrangle the data and produce the desired strings. Here, in contrast, we're dealing with pandoc's template syntax, which is not super convenient or easy to grasp.

Maybe we can add a few examples in a thread below and comment on how it works? I'll start with what I understand/don't understand about the Elsevier template, which seems easiest:

Desired output:

%% \author[label1,label2]{<author name>}
%% \address[label1]{<address>}
%% \address[label2]{<address>}

%% use the tnoteref command within \title for footnotes;
%% use the tnotetext command for the associated footnote;
%% use the fnref command within \author or \address for footnotes;
%% use the fntext command for the associated footnote;
%% use the corref command within \author for corresponding author footnotes;
%% use the cortext command for the associated footnote;
%% use the ead command for the email address,
%% and the form \ead[url] for the home page:

The nice thing is that addresses and authors are decoupled, the mapping between the two being done by the label references.

Pandoc template:

$for(by-author)$\author[$for(by-author.affiliations)$$it.number$$sep$,$endfor$]{$by-author.name.literal$%
$if(by-author.attributes.corresponding)$\corref{cor1}$endif$%
$if(by-author.note.text)$\fnref{fn$by-author.note.number$}$endif$}
$if(by-author.email)$ \ead{$by-author.email$} $endif$
$endfor$
$for(by-affiliation)$
\affiliation[$it.number$]{organization={$it.name$$if(it.department)$, $it.department$$endif$},$if(it.address)$addressline={$it.address$}$endif$$if(it.city)$$if(it.address)$,$endif$city={$it.city$}$endif$$if(it.country)$$if(it.city)$,$elseif(it.address)$,$endif$country={$it.country$},countrysep={,}$endif$$if(it.postal-code)$$if(it.country)$,$elseif(it.city)$,$elseif(it.address)$,$endif$postcode={$it.postal-code$}$endif$,postcodesep={}}
$endfor$

\cortext[cor1]{Corresponding author}
$for(by-author)$
$if(by-author.note.text)$\fntext[fn$by-author.note.number$]{$by-author.note.text$}$endif$
$endfor$

[baptiste]

Now, ACS's case is already more involved:

\author{Author Person} 
\author{Second Bloke} 
\email{[email protected]}
\affiliation[University of Sometown]{University of Somewhere, Sometown, USA} 
\altaffiliation{Previous address: Minute University, Nowhereville, USA} 
\author{Indus Trialguy}
\email{[email protected]}
\affiliation[SponsoCo]{Research Department, SponsorCo, BigCity, USA} 
\alsoaffiliation{University of Somewhere, Sometown, USA}

Relevant instructions include:

Each author should be given as a separate \author command. These should be followed by an \affiliation, which applies to the preceding authors.
Repeated entries for \affiliation and \alsoaffiliation will result in only one address being printed in the address list and footnotes. Repeated \altaffiliation entries only produce a single footnote

In the ACS extension this is implemented via

• title.tex partial
• _affiliation.tex sub-partial

with

$for(by-author)$ 

  \author{$by-author.name.literal$}
   $if(by-author.affiliations)$
     $if(by-author.affiliations/first)$
        $for(by-author.affiliations/first)$
        \affiliation{$_affiliation.tex()$}
        $endfor$
        $if(by-author.affiliations/rest/first)$
          $for(by-author.affiliations/rest/first)$
           \affiliation{$_affiliation.tex()$}
          $endfor$
        $endif$ % affiliations/rest/first
      $endif$ % affiliations/first
    $endif$ % affiliations
  
  $if(by-author.note.text)$
  \altaffiliation{$by-author.note.text$}
  $endif$
  
  $if(by-author.email)$
  \email{$by-author.email$}
  $endif$
  $if(by-author.phone)$
  \phone{$by-author.phone$}
  $endif$
  $if(by-author.fax)$
  \fax{$by-author.fax$}
  $endif$

$endfor$ % by-author

(indentation added in an effort to clarify the nested levels)

and the affiliation partial being injected,

$if(it.department)$$it.department$,$endif$ $if(it.name)$$it.name$,$endif$ $if(it.city)$$it.city$,$endif$ $if(it.country)$$it.country$$endif$

Now, this appears to be very similar to what APS requires, but I have to admit I don't fully understand what's going on in there! The pandoc partials and pipes are kind of new to me, and their use not entirely obvious...

If I try to translate what I read,

1. loop over authors $for(by-author)$
2. add \author{} with \author{$by-author.name.literal$}
3. if this author has affiliations $if(by-author.affiliations)$
4. if this author has a first affiliation (?) $if(by-author.affiliations/first)$
5. loop over the fields of this first affiliation $for(by-author.affiliations/first)$
6. inject the properly-formatted affiliation from the partial \affiliation{$_affiliation.tex()$} (discussed below)
7. is there one more affiliation? $if(by-author.affiliations/rest/first)$
8. loop over this other affiliation $for(by-author.affiliations/rest/first)$
9. inject this other affiliation \affiliation{$_affiliation.tex()$}

and the partial affiliation being injected:

$if(it.department)$$it.department$,$endif$ $if(it.name)$$it.name$,$endif$ $if(it.city)$$it.city$,$endif$ $if(it.country)$$it.country$$endif$

where I'm inferring that it refers to the current item being treated

the anaphoric keyword it must be used when iterating over partials

[baptiste]

(side-discussion)

It also strikes me that the ever-more complex mini-language in pandoc templates is not an ideal solution – is there an alternative? In fact, might pandoc eventually move away from it? It would be so much nicer to use Lua for these convoluted programming steps (for loops, if/else, string formatting, etc.)

Could one bypass the pandoc template altogether here, and have just a generic $metadata$ which is populated by a an arbitrarily-complex string produced in Lua?

One option of course is to inject in this $metadata$ the hard-coded values for the specific document. But what if one wanted a more generic approach, where the logic of the author-affiliation formatting is captured in a custom Lua writer function, called when pandoc renders the corresponding elements of the AST? Anyway, I guess this is more a question for the pandoc folks, but I'm really curious why this mini-language is still the chosen approach, when it's become so complex.

[cderv]

Could one bypass the pandoc template altogether here, and have just a generic $metadata$ which is populated by a an arbitrarily-complex string produced in Lua?

Just to answer about Lua processing , all the work done about the author and affiliation schemas with the normalization are also aiming to simplify the possible processing in Lua.
We have one example (for JSS) where we do tweak some information in Lua so that it can be used in pandoc's template. See the metadata.label-prefix variable computed in Lua.

So I believe you can completely do some processing in Lua put your result in a variable, and then modify the title.tex partail to use your authors insertion.

Hope it helps see what can be done. Did not have other example for now.

[dragonstyle]

Just to add one more note - in our usage, we found that the templating was still useful for simple rendering if the data was of a structure that was suitable (e.g. simple loops and conditional outputting of elements). That was part of what led to normalizing author data into by-author and by-affiliation which typically should result in relatively straightforward templates.

If you find cases where this isn't true, @cderv is correct that you can actually do some additional parsing or work in LUA to augment the author data or even restructure it (for example, in the extreme as you suggest you could provide a title partial with a simple $my-title-block$ in it and just populate that value using LUA by filtering on Meta and adding that fully computed value to the document metadata).

If you do find cases where you need to reshape the author / affiliation data extensively to make things work, we'd be happy to hear about it as it may make sense for the author/affiliation normalization to provide this automatically if it will be frequently used...

[baptiste]

Thank you both, I'll be mulling this over while experimenting with the APS format (though it looks basically the same as ACS, so I could just copy that).

Some useful information also from John MacFarlane on the pandoc mailing list – basically it boils down to:

• backward compatibility: the template variables $if()$ etc. have been in pandoc for around 16 years
• security: the injection of content can't do anything really harmful, whereas a full programming language might
• bypassing it and using a custom filter or a custom writer to massage and format the content before inserting it in the output document is a valid alternative

Nice to get this info, I might try the Lua filter approach to see if it's any easier.

[cderv]

Thanks for sharing the discussion ! Please to keep us updated on your progress ! This will be a great example !