Add ROR affiliation links

[cthoyt]

Closes #71

This PR does the following:

• [x] Adds the ability to specify ror in each affiliation in a paper's frontmatter
• [x] Adds a ROR logo with a link when ror is available in PDF exports
  • [x] default.tex
  • [x] preprint.tex
• [x] Adds affiliation outputs to default.crossref so structured affiliations appear in Crossref metadata (with gracious help from Albert!)
• [x] Adds structured affiliation outputs to JATS export by virtue of it being based on the crossref output

Note: there was a future PR after this one that fixed the ROR SVG typography in https://github.com/openjournals/inara/pull/90

Demos

Here's what the example PDF looks like now, with a clickable ROR logo that goes to the relevant page:

Here's an example of what the CrossRef XML looks like after running make ARTICLE=example/paper.md crossref:

<contributors>
  <person_name sequence="first" contributor_role="author">
    <given_name>Albert</given_name>
    <surname>Krewinkel</surname>
    <ORCID>https://orcid.org/0000-0002-9455-0796</ORCID>
    <affiliations>
      <institution><institution_name>Open Journals</institution_name></institution>
      <institution><institution_name>Pandoc Development Team</institution_name></institution>
      <institution><institution_name>Technische Universitaet Hamburg</institution_name><institution_id type="ror">https://ror.org/04bs1pb34</institution_id></institution>
    </affiliations>
  </person_name>
   ...
</contributors>

Here's what the JATS XML looks like:

...
<aff id="aff-4">
<institution-wrap>
<institution>Technische Universitaet Hamburg</institution>
<institution-id institution-id-type="ROR">04bs1pb34</institution-id>
</institution-wrap>
</aff>

It's in the README already, but here are the commands I ran after installing the hack font, pandoc, and some other stuff that already was on my computer:

make ARTICLE=example/paper.md crossref

Notes

1. I converted the official ror-icon-rgb.svg to TikZ code using svg2tikz.
2. I weirdly needed to use \protect on both \href and the TikZ commands to get them working in the default.tex and preprint.tex templates
3. I used the Crossref guide to reverse-engineer the way the XML should be
4. I ~am assuming~ incorrectly that the JATS files are created from the output XML since there are no templates related to JATS in the Inara repo. This actually needs to be handled upstream in Pandoc itself - see https://github.com/jgm/pandoc/issues/10138.

Future Work

A few nice-to-have's (for future PRs):

1. Externalize the code that generates the TikZ picture for ROR into either 1) an external latex file or 2) a package like orcidlink
2. Add logos int the default.context. From what I understand, this is an experiment for Inara to adopt ConTeXt as a typesetting system instead of LaTeX since it has nicer features for PDF export. Since this hasn't been fully adopted by Inara/OJ, I won't make any changes here in this PR but will leave for later.)
3. Crossref/JATS also support Wikidata identifiers and ISNI for organizations. This is especially useful for organizations that don't fall under ROR's scope

[cthoyt]

@tarleb I am a novice in latex and lua, maybe you can very quickly give me a pointer on why the combination of my lua filter and minor changes in default.crossref aren't working properly

[tarleb]

Very cool, thanks for this!

The "secret" for default.crossref is that the raw strings in the metadata will not be written as-is, but will get escaped. To get the raw string, one must wrap the xml with pandoc.RawInline('html', xml) in Lua. The CrossRef format basically uses HTML syntax for inline markup, so we use pandoc's HTML writer to produce the output.

If it doesn't work, then we could schedule a short call later this week. Just send me a mail in that case.

[cthoyt]

@tarleb I think this is done. It also appears that the JATS seems to be correctly sucking up the crossref metadata.

However, I have run make test and am not sure what the protocol for updating the testing data is. I was able to manually check the JATS output is updated and correct, but it's not clear about the other test reference files. There appear to be non-related changes in the newly generated artifacts. Note - it appears make test fails on the base repo, so maybe passing this isn't required.

[cthoyt]

@arfon your feedback would also be appreciated!

[arfon]

Super cool, thanks @cthoyt. If @tarleb is happy, I'm happy 😸

One cheeky request, once this lands, it would be excellent if you could open a PR for the example JOSS paper too 🙏 https://joss.readthedocs.io/en/latest/example_paper.html

[amandafrench]

Hey all, Amanda from ROR here. This is cool! I've added Open Journals to our list of ROR integrators at https://bit.ly/ror-integrations -- take a look and let me know if you'd like changes. cc @cthoyt

[cthoyt]

@tarleb did you see this one also?

[tarleb]

We'll need to do a new release before it's fully live. Working on it.

[tarleb]

Release v1.1.0 is out. I believe that @xuanxu may have to do some updates before it's used in production.

[cthoyt]

thanks @tarleb and everyone for taking a look at this and the nice feedback! looking forward to using this in my upcoming JOSS submission <4

[arfon]

Hi folks. I have a feeling that this change might have just broken the production pipeline for JOSS. See this error: https://github.com/openjournals/joss-papers/actions/runs/10718073016/job/29719156977#step:3:808

Error running filter /usr/local/share/***nals/data/filters/prepare-affiliations.lua:
...share/***nals/data/filters/prepare-affiliations.lua:11: attempt to index a nil value (field 'integer index')
stack traceback:

[cthoyt]

could this be because of a disconnect in the way affiliation indexes are written out? It seemed to me like Inara had thrown out the concept of using stringified lists for indexes

[cthoyt]

See potential fix in https://github.com/openjournals/inara/pull/77

[tarleb]

I've pushed a temporary fix that ignores all errors in the new filter. Now we can do a proper fix (and add some appropriate tests).