Enable annotating contributor roles

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ## UNRELEASED
 
+- Support for annotating author roles with the Contribution Role Taxonomy (CRediT) (Charles Tapley Hoyt) (https://github.com/openjournals/inara/pull/75)
 - Fix bug in application of `prepare-affiliations.lua` filter (Charles Tapley Hoyt)
 - Fix a bug in the injection of `SOURCE_DATE_EPOCH` (https://github.com/openjournals/inara/pull/86) in tests
 - Fix test files (https://github.com/openjournals/inara/pull/86, https://github.com/openjournals/inara/pull/85)

README.md

@@ -14,13 +14,15 @@ must be mounted on path `/data`. The path to the paper, relative to
 the mounted folder, is expected as the only argument.
 
 - The Docker image will generate PDF and JATS files by default. To
-select specific output formats to be generated use the `-o` flag.
-Supported options are: `pdf`, `jats`, `html`, `crossref`, `cff`, and `preprint`. To get multiple outputs
-use a comma separated list.
+  select specific output formats to be generated use the `-o` flag.
+  Supported options are: `pdf`, `jats`, `html`, `crossref`, `cff`, and `preprint`. To get multiple outputs
+  use a comma separated list.
 - By default PDF files will be compiled in _draft mode_ to include a draft
-watermark and linenumbers. To create a _production_ PDF add the `-p` flag.
-- There is a special flag `-r` meant for retraction notices that don't need to show Software/Editor/Reviewes/Submission-date information.
-- The target journal can be set using the `JOURNAL` ENV VAR. Currently the valid values are: `joss`, `jose` or `resciencec`
+  watermark and linenumbers. To create a _production_ PDF add the `-p` flag.
+- There is a special flag `-r` meant for retraction notices that don't need to show
+  Software/Editor/Reviewes/Submission-date information.
+- The target journal can be set using the `JOURNAL` ENV VAR. Currently the valid values are: `joss`, `jose`
+  or `resciencec`
 
 **Example:**
 
@@ -54,6 +56,19 @@ E.g., to generate only a PDF file, the command would be
 The generated output will be written to folder
 `publishing-artifacts`.
 
+### Local development
+
+Since the make command is set up to use docker, this isn't appropriate for doing development
+on the internals. You can build documents locally with:
+
+    JOURNAL=joss OPENJOURNALS_PATH=/Users/cthoyt/dev/inara sh ./scripts/entrypoint.sh -v ./example/paper.md
+
+You can test locally using:
+
+    make INARA_TEST_CMD="SOURCE_DATE_EPOCH=1234567890 JOURNAL=joss OPENJOURNALS_PATH=/Users/cthoyt/dev/inara ./scripts/entrypoint.sh -v" test
+
+Where you replace the `OPENJOURNALS_PATH` with the absolute path to where you cloned the Inara git repo.
+
 ### Dependencies
 
 Inara is built on pandoc, and requires a recent pandoc version.

build.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+JOURNAL=joss OPENJOURNALS_PATH=/Users/cthoyt/dev/inara sh ./scripts/entrypoint.sh -v ./example/paper.md

data/defaults/pdf.yaml

@@ -11,6 +11,8 @@ filters:
     path: self-citation.lua
   - type: lua
     path: fix-bibentry-spacing.lua
+  - type: lua
+    path: prepare-credit.lua
 variables:
   # styling options
   colorlinks: true

data/defaults/preprint.yaml

@@ -1,6 +1,9 @@
 to: latex
 output-file: paper.preprint.tex
 template: preprint.latex
+filters:
+  - type: lua
+    path: prepare-credit.lua
 variables:
   # styling options
   colorlinks: true

data/filters/prepare-credit.lua

@@ -0,0 +1,86 @@
+-- Checks if any contributor information is available
+
+roles = pandoc.List {
+    "conceptualization",
+    "data-curation",
+    "formal-analysis",
+    "funding-acquisition",
+    "investigation",
+    "methodology",
+    "project-administration",
+    "resources",
+    "software",
+    "supervision",
+    "validation",
+    "visualization",
+    "writing-original-draft",
+    "writing-review-editing"
+}
+
+degrees = pandoc.List {
+    "Lead",
+    "Supporting",
+    "Equal"
+}
+
+function invalidRole(str)
+    return not roles:includes(str)
+end
+
+function invalidDegree(str)
+    return not degrees:includes(str)
+end
+
+function join_with_commas_and(list)
+    local len = #list
+    if len == 0 then
+        return ""
+    elseif len == 1 then
+        return list[1]
+    elseif len == 2 then
+        return list[1] .. " and " .. list[2]
+    else
+        local result = table.concat(list, ", ", 1, len - 1)
+        return result .. ", and " .. list[len]
+    end
+end
+
+function capitalize_first_letter(str)
+    return str:sub(1, 1):upper() .. str:sub(2)
+end
+
+function clean_role_dict(d)
+  if d.type then
+    return d
+  else
+    return {["type"] = pandoc.utils.stringify(d)}
+  end
+end
+
+function Meta (meta)
+  meta.hasRoles = false
+  for _, author in ipairs(meta.authors or {}) do
+    if author.roles then
+      meta.hasRoles = true
+      roleList = {}
+      for _, roleDict in ipairs(author.roles) do
+        roleDict = clean_role_dict(roleDict)
+        role = pandoc.utils.stringify(roleDict.type)
+        if invalidRole(role) then
+          error("invalid role for author " .. author.name .. ": " .. role)
+        end
+        if roleDict.degree then
+          degree = capitalize_first_letter(pandoc.utils.stringify(roleDict.degree))
+          if invalidDegree(degree) then
+            error("invalid degree for author " .. author.name .. ": " .. degree)
+          end
+          table.insert(roleList, role .. " (" .. degree .. ")")
+        else
+          table.insert(roleList, role)
+        end
+      end
+      author.rolesString = join_with_commas_and(roleList)
+    end
+  end
+  return meta
+end

data/templates/default.latex

@@ -557,6 +557,15 @@ $if(lof)$
 $endif$
 $body$
 
+$if(hasRoles)$
+\section{Author Contributions}\label{author-contributions}
+\begin{enumerate}
+$for(authors)$
+\item $it.name$ - $it.rolesString$
+$endfor$
+\end{enumerate}
+$endif$
+
 $if(natbib)$
 $if(bibliography)$
 $if(biblio-title)$

data/templates/preprint.latex

@@ -438,6 +438,15 @@ $if(has-frontmatter)$
 $endif$
 $body$
 
+$if(hasRoles)$
+\section{Author Contributions}\label{author-contributions}
+\begin{enumerate}
+$for(authors)$
+\item $it.name$ - $it.rolesString$
+$endfor$
+\end{enumerate}
+$endif$
+
 $if(has-frontmatter)$
 \backmatter
 $endif$

example/paper.md

@@ -7,14 +7,27 @@ authors:
     affiliation: "1, 2, 4"
     orcid: 0000-0002-9455-0796
     corresponding: true
+    roles:
+      - type: software
+        degree: equal
+      - 'methodology'
   - name: Juanjo Bazán
     orcid: 0000-0001-7699-3983
     affiliation: [1]
     equal-contrib: true
+    roles:
+      - type: software
+        degree: equal
   - name: Arfon M. Smith
     orcid: 0000-0002-3957-2474
     affiliation: [1, 3]
     equal-contrib: true
+    roles:
+      - type: software
+        degree: equal
+      - type: supervision
+        degree: lead
+
 affiliations:
   - index: 1
     name: Open Journals
@@ -365,6 +378,72 @@ authors:
   <!--     given-names: 瀧 -->
   <!--     surname: 立花 -->
 
+## Contributor Roles
+
+The [Contribution Role Taxonomy (CRediT)](https://credit.niso.org/contributor-roles) defines
+fourteen standard roles of authors. Each author can be annotated with one or more contribution
+roles.
+
+1. [conceptualization](https://credit.niso.org/contributor-roles/conceptualization)
+2. [data-curation](https://credit.niso.org/contributor-roles/data-curation)
+3. [formal-analysis](https://credit.niso.org/contributor-roles/formal-analysis)
+4. [funding-acquisition](https://credit.niso.org/contributor-roles/funding-acquisition)
+5. [investigation](https://credit.niso.org/contributor-roles/investigation)
+6. [methodology](https://credit.niso.org/contributor-roles/methodology)
+7. [project-administration](https://credit.niso.org/contributor-roles/project-administration)
+8. [resources](https://credit.niso.org/contributor-roles/resources)
+9. [software](https://credit.niso.org/contributor-roles/software)
+10. [supervision](https://credit.niso.org/contributor-roles/supervision)
+11. [validation](https://credit.niso.org/contributor-roles/validation)
+12. [visualization](https://credit.niso.org/contributor-roles/visualization)
+13. [writing-original-draft](https://credit.niso.org/contributor-roles/writing-original-draft)
+14. [writing-review-editing](https://credit.niso.org/contributor-roles/writing-review-editing)
+
+JATS also specifies three degrees which can be used to quantify the impact of a contribution:
+
+1. `Lead`
+2. `Supporting`
+3. `Equal` - for use if multiple equivalent leads
+
+Together, these can be used to identify which authors materially contributed to the paper,
+such as through `formal-analysis` or `data-curation` and which authors contributed immaterially,
+such as through `supervision`. It also allows for saying if multiple people made the same
+kind of contribution, who took the lead.
+
+```yaml
+authors:
+  - name: John Doe
+    affiliation: [ 1 ]
+    roles:
+      - type: 'formal-analysis'
+        degree: 'lead'
+
+  - name: John Boss
+    affiliation: [ 1 ]
+    roles:
+      - type: 'funding-acquisition'
+        degree: 'lead'
+      - type: 'supervision'
+        degree: 'lead'
+```
+
+Roles are optional, and within roles, degrees are optional. It's possible to shorthand
+roles by using strings directly:
+
+```yaml
+authors:
+  - name: John Doe
+    affiliation: [ 1 ]
+    roles:
+      - 'formal-analysis'
+
+  - name: John Boss
+    affiliation: [ 1 ]
+    roles:
+      - 'funding-acquisition'
+      - 'supervision'
+```
+
 ## Affiliations
 
 Each affiliation requires an `index` and `name`.

test/expected-draft/paper.crossref

@@ -6,8 +6,8 @@
            version="5.3.1"
            xsi:schemaLocation="http://www.crossref.org/schema/5.3.1 http://www.crossref.org/schemas/crossref5.3.1.xsd">
   <head>
-    <doi_batch_id>20090213233130-7df7772968726f2a3c347b21a6d3257f38f7c870</doi_batch_id>
-    <timestamp>20090213233130</timestamp>
+    <doi_batch_id>20090213223130-7df7772968726f2a3c347b21a6d3257f38f7c870</doi_batch_id>
+    <timestamp>20090213223130</timestamp>
     <depositor>
       <depositor_name>JOSS Admin</depositor_name>
       <email_address>admin@theoj.org</email_address>