Add author roles to JATS #10153

cthoyt · 2024-09-04T21:49:02Z

This PR adds support for annotating author roles using the Contribution Role Taxonomy (CRediT).

I'm motivated to add this to Pandoc since I want the Journal of Open Source Software (JOSS), which is built on top of Pandoc, to be able to create compliant JATS. We're already adding support for encoding this information in article metadata in parallel in openjournals/inara#75.

Example input markdown / output JATS XML

Example input markdown file:

---
title: CRediT Test
author:
  - name: John Batman
    roles:
      - type: software
        degree: lead
      - type: methodology
        degree: lead
  - name: Jim Batman
    roles:
      - type: software
        degree: supporting
---

# Body

This file tests CRediT annotations.

Example output JATS file:

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.2 20190208//EN"
        "JATS-publishing1.dtd">
<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2"
         article-type="other">
    <front>
        <article-meta>
            <title-group>
                <article-title>
                    CRediT Test
                </article-title>
            </title-group>
            <contrib-group>
                <contrib contrib-type="author">
                    <name>
                        <surname>Batman</surname>
                        <given-names>John</given-names>
                    </name>
                    <role vocab="credit"
                          vocab-identifier="https://credit.niso.org/"
                          vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
                          vocab-term="Software"
                          degree-contribution="Lead"
                    >
                        Software
                    </role>
                    <role vocab="credit"
                          vocab-identifier="https://credit.niso.org/"
                          vocab-term-identifier="https://credit.niso.org/contributor-roles/methodology/"
                          vocab-term="Methodology"
                          degree-contribution="Lead"
                    >
                        Methodology
                    </role>
                </contrib>
                <contrib contrib-type="author">
                    <name>
                        <surname>Batman</surname>
                        <given-names>Jim</given-names>
                    </name>
                    <role vocab="credit"
                          vocab-identifier="https://credit.niso.org/"
                          vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
                          vocab-term="Software"
                          degree-contribution="Supporting"
                    >
                        Software
                    </role>
                </contrib>
            </contrib-group>
        </article-meta>
    </front>
    <body>
        <sec id="body">
            <title>Body</title>
            <p>This file tests CRediT annotations.</p>
        </sec>
    </body>
</article>

jgm · 2024-09-05T16:15:14Z

You should add a "command test" to test the proposed feature, and to illustrate how it works.

See test/command/*.md for examples.

cthoyt · 2024-09-24T13:13:12Z

Hi @jgm , I think I figured out making a test file. I have a few questions I bet you could answer very quickly but would take me a long time to figure out:

Is there a specific naming convention I should use for my test command file?
I created a Credit.hs that contains a dictionary that I want to inject into the JATS output process. Where should I look to do that? you can see in the diff what I am currently trying in the JATS writer

jgm · 2024-09-24T15:44:11Z

Is there a specific naming convention I should use for my test command file?

Usually we try to name them after the associated issue. So, if there's an open issue that this fixes you could use that number; otherwise you could use the PR's number, 10153.md. That makes it easy to figure out later why the test was added.

I created a Credit.hs that contains a dictionary that I want to inject into the JATS output process. Where should I look to do that? you can see in the diff what I am currently trying in the JATS writer

Instead of creating a separate module, I'd prefer if you just included this map in the JATS writer module itself.

cthoyt · 2024-09-24T16:57:01Z

@jgm thanks for that feedback, I addressed both of your points. Now, the only thing left is how to make this dictionary (renamed to creditNames) available inside the template article.jats_publishing.

My first try was $ defField "creditNames" creditNames because this group is also where some other things that appear in the template are referenced, but I am unfortunately not familiar with Haskell and this is a very complex codebase! Any help appreciated :)

https://github.com/cthoyt/pandoc/blob/71d53c6e2635ab23929287a94087bb50ee56b79b/src/Text/Pandoc/Writers/JATS.hs#L183

jgm · 2024-09-24T17:57:38Z

My first try was $ defField "creditNames" creditNames

what happens when you try that?

By the way, our usual convention for variable names would favor credit-names.

cthoyt · 2024-09-24T19:06:10Z

It seems the issue was the definition of creditNames :: M.Map String String - it didn't seem to have a way to handle strings and gave this error:

src/Text/Pandoc/Writers/JATS.hs:182:17: error: [GHC-39999]
    • Could not deduce ‘Text.DocTemplates.Internal.ToContext
                          Text (M.Map String String)’
        arising from a use of ‘defField’
      from the context: PandocMonad m
        bound by the type signature for:
                   docToJATS :: forall (m :: * -> *).
                                PandocMonad m =>
                                WriterOptions -> Pandoc -> JATS m Text
        at src/Text/Pandoc/Writers/JATS.hs:124:1-68

Switching the signature to use Text instead of String in creditNames :: M.Map Text Text and finally got it to compile, but it seems like the Text values in the dictionary don't get displayed in the template and instead only evaluate to true. Is there either:

A way to add handling for regular dictionaries
Unpack the Pandoc Text to be a regular string inside the template?

jgm · 2024-09-24T19:28:48Z

I don't understand why you'd be getting this behavior. Nested Maps seem to work fine in ToContext: here I explore using cabal repl in jgm/doctemplates:

ghci> toContext $ fromList [("a"::Text, fromList [("b"::Text, fromList [("c"::Text,"d"::Text)])])] :: Context Text
Context {unContext = fromList [("a",MapVal (Context {unContext = fromList [("b",MapVal (Context {unContext = fromList [("c",SimpleVal (Text 1 "d"))]}))]}))]}
ghci> Right (tpl :: Template Text) <- compileTemplate "." "$a.b.c$" 
ghci> renderTemplate tpl context
Text 1 "d"

cthoyt added 4 commits September 4, 2024 23:43

Add author roles to JATS

c41713f

Add documentation

021c6d2

Update jats.md

94bb5bd

Update article.jats_publishing

7f1a2a9

This was referenced Sep 17, 2024

Add contributor roles openjournals/inara#87

Open

Enable annotating contributor roles openjournals/inara#75

Closed

cthoyt added 2 commits September 24, 2024 14:44

Create cth-jats.md

f47d447

Create Credit.hs

66fb3fa

cthoyt added 2 commits September 24, 2024 15:25

Update JATS.hs

5494433

Define creditRoles in JATS writer

fb1f8e1

cthoyt added 7 commits September 24, 2024 18:00

Simplify

6719cf9

Update 10153.md

8a9f20f

Update 10152.md

6343e0d

Update jats.md

a079567

Update JATS.hs

c8406da

Update JATS.hs

8189c43

Update 10152.md

71d53c6

Update JATS.hs

7f73043

cthoyt added 2 commits September 24, 2024 20:45

Update JATS.hs

859c683

Rename variable to fit convention

7b604c7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add author roles to JATS #10153

Add author roles to JATS #10153

cthoyt commented Sep 4, 2024 •

edited

Loading

jgm commented Sep 5, 2024

cthoyt commented Sep 24, 2024 •

edited

Loading

jgm commented Sep 24, 2024

cthoyt commented Sep 24, 2024 •

edited

Loading

jgm commented Sep 24, 2024

cthoyt commented Sep 24, 2024

jgm commented Sep 24, 2024

Add author roles to JATS #10153

Are you sure you want to change the base?

Add author roles to JATS #10153

Conversation

cthoyt commented Sep 4, 2024 • edited Loading

jgm commented Sep 5, 2024

cthoyt commented Sep 24, 2024 • edited Loading

jgm commented Sep 24, 2024

cthoyt commented Sep 24, 2024 • edited Loading

jgm commented Sep 24, 2024

cthoyt commented Sep 24, 2024

jgm commented Sep 24, 2024

cthoyt commented Sep 4, 2024 •

edited

Loading

cthoyt commented Sep 24, 2024 •

edited

Loading

cthoyt commented Sep 24, 2024 •

edited

Loading