Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Document pandoc's handling of metadata in JATS output (#6794)

Browse source
This commit is contained in:
Albert Krewinkel 2020-11-03 20:39:59 +01:00 • committed by GitHub
parent e7a9d88a0e
commit 6463901fac
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 299 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

299
doc/jats.md Normal file
View file

@ -0,0 +1,299 @@
---
title: JATS
author: Albert Krewinkel
---
This document describes pandoc's handling of JATS.
Metadata Values
===============
`abstract`
: Article summary. Added via the document's front matter via the
[`<abstract>`][elem:abstract] element.
`author`
: list of article contributors. Each author should have a surname
and a given name listed in the entry; if the author has no
`surname` value, then the item will be used as the contributors
[`string-name`][elem:string-name].
`orcid`
: the contributor's ORCID identifier.
`surname`
: surname of the contributor. Usually the family name in
western names.
See [`<surname>`][elem:surname].
`given-names`
: personal names of the contributor; this includes middle
names (if any) in western-style names.
See [`<given-names>`][elem:given-names].
`email`
: the contributor's email address.
Used as the contents of the [`<email>`][elem:given-names]
element.
`cor-id`
: identifier linking to the contributor's correspondence
information. The info itself must be stored in as an item in
`article.author-notes.corresp`. If the `cor-id` value is
then, an [`<xref>`][elem:xref] link of
[`ref-type`][attr:ref-type] `corresp` is added. The
[`rid`][attr:rid] attribute is set to `cor-<ID>`, where
`<ID>` is the stringified value of this attribute.
`copyright`
: Licensing and copyright information. This information is
rendered via the [`<permissions>`][elem:permissions] element.
The variables `type`, `link`, and `text` should always be used
together.
`statement`
: the year of copyright; used as content of the
[`<copyright-statement>`][elem:copyright-statement]
`year`
: the year of copyright; used as content of the
[`<copyright-year>`][elem:copyright-year]
`holder`
: the copyright holder; included via the
[`<copyright-holder>`][elem:copyright-holder] element.
`text`
: inline text setting the license under which the text is
published; included via the
[`<license-p>`][elem:copyright-holder] element.
`type`
: type of the license; used as value of the
[`license-type`][attr:license-type] attribute.
`link`
: external link describing the license; used as value of a
`xlink:href` attribute in the `<license>` element.
`date`
: publication date. This value should usually be a string
representation of a date. Pandoc will parse and deconstruct the
date into the components given below. It is also possible to
pass these components directly.
The publication date is recorded in the document via the
[`<pub-date>`][elem:pub-date] element and its sub-elements. The
[`pub-type`][attr:pub-type] attribute is always set to `epub`.
`iso-8601`
: ISO-8601 representation of the publication date. Used as the
value of the [`pub-date`][elem:pub-date] element's
[`iso-8601-date`][attr:iso-8601-date] attribute.
This value is set automatically if pandoc can parse the
`date` value as a date.
`day`, `month`, `year`
: Day, month, and year of the publication date. Only the
publication year is required. The values are used as the
contents of the elements with the respective names.
The values are set automatically if pandoc can parse the
`date` value as a date.
`article`
: information concerning the article that identifies or describes
it. The key-value pairs within this map are typically used
within the [`<article-meta>`][elem:article-meta] element.
`publisher-id`
: external article identifier assigned by the publisher. Used
as the content of the [`<article-id>`][elem:article-id]
element with attribute [`pub-id-type`][attr:pub-id-type] set
to `publisher-id`.
`doi`
: Digital Object Identifier (DOI) assigned to the article.
Used as the content of the [`<article-id>`][elem:article-id]
element with attribute [`pub-id-type`][attr:pub-id-type] set
to `doi`.
`pmid`
: PubMed Identifier (PubMed ID) assigned to the article. Used
as the content of the [`<article-id>`][elem:article-id]
element with attribute [`pub-id-type`][attr:pub-id-type] set
to `pmid`.
`pmcid`
: PubMed Central Identifier assigned to the article. Used as
the content of the [`<article-id>`][elem:article-id] element
with attribute [`pub-id-type`][attr:pub-id-type] set to
`pmcid`.
`art-access-id`
: generic article accession identifier. Used as the content of
the [`<article-id>`][elem:article-id] element with attribute
[`pub-id-type`][attr:pub-id-type] set to `art-access-id`.
`heading`
: name of a subject or topic describing the article. Used as
the content of the [`<subject>`][elem:subject] element,
nested in a [`<subj-group>`][elem:subj-group] element which
has `heading` as its
[`subj-group-type`][attr:subj-group-type] attribute.
`categories`
: list a subject or topic describing the article. Items are
each used as the content a the [`<subject>`][elem:subject]
element, grouped in a single
[`<subj-group>`][elem:subj-group] element with its
[`subj-group-type`][attr:subj-group-type] attribute set to
`categories`.
`author-notes`
: Additional information about authors, like conflict of
interest statements and corresponding author contact info.
Wrapped in an [`<author-notes>`][elem:author-notes] element.
`conflict`
: Conflict of interest statement. Rendered as a footnote
([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type)
`conflict`.
`con`
: Contributed-by information. Rendered as a footnote
([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type) `con`.
`corresp`
: Correspondence information. This must be a list of
contributor correspondence items, where each item must
have the properties `id` and `email`. The info is then
rendered via a [`<corresp>`][elem:corresp] element.
`funding-statement`
: Prose describing the funding. Added to the article's
frontmatter via the
[`funding-statement`][elem:funding-statement] element.
`journal`
: information on the journal in which the article is published.
This must be a map; the following key/value pairs are
recognized.
`publisher-id`
: journal identifier assigned by the publisher. Used as
content of element [`<journal-id>`][elem:journal-id] with
attribute [`journal-id-type`][attr:journal-id-type] set to
`publisher-id`.
`nlm-ta`
: journal identifier assigned by PubMed. Used as content of
element [`<journal-id>`][elem:journal-id] with attribute
[`journal-id-type`][attr:journal-id-type] set to `nlm-ta`.
`pmc`
: journal identifier assigned by PubMed Central. Used as
content of element [`<journal-id>`][elem:journal-id] with
attribute [`journal-id-type`][attr:journal-id-type] set to
`pmc`.
`title`
: full title of the journal in which the article is published.
Used as content of the
[`<journal-title>`][elem:journal-title] element.
`abbrev-title`
: short form of the journal title. Used as content of the
[`<abbrev-journal-title>`][elem:abbrev-journal-title]
element.
`pissn`
: ISSN identifier of the publication's print version. Used as
content of the [`<issn>`][elem:issn] element with the
[`pub-type`][attr:pub-type] attribute set to `ppub`.
`eissn`
: ISSN identifier of the publication's electronic version.
Used as content of the [`<issn>`][elem:issn] element with
the [`pub-type`][attr:pub-type] attribute set to `epub`.
`publisher-name`
: name of the publishing entity (person, company, or other).
Used as the content of the
[`<publisher-name>`][elem:publisher-name] element.
`publisher-loc`
: place of publication. Used as the content of the
[`<publisher-loc>`][elem:publisher-loc] element.
`notes`
: Additional notes concerning the whole article. Added to the
article's frontmatter via the [`<notes>`][elem:notes] element.
`tags`
: list of keywords. Items are used as contents of the
[`<kwd>`][elem:kwd] element; the elements are grouped in a
[`<kwd-group>`][elem:kwd-group] with the
[`kwd-group-type`][attr:kwd-group-type] value `author`.
Required Metadata
-----------------
Pandoc will try to generate a valid JATS document even when
information is missing, filling in placeholders or using empty
values. This circumvents the intend to ensure a minimum set of
information being present in documents of a certain tag set. It is
hence recommended to always provide the information listed below.
### Publishing Tag Set
Required metadata values:
- One or more of `journal.publisher-id`, `journal.nlm-ta`,
`journal.pmc`.
- One or more of `journal.pissn`, `journal.eissn`.
[attr:fn-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/fn-type.html
[attr:iso-8601-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/iso-8601-date.html
[attr:journal-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/journal-id-type.html
[attr:kwd-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/kwd-group-type.html
[attr:license-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/license-type.html
[attr:pub-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-id-type.html
[attr:pub-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-type.html
[attr:ref-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/ref-type.html
[attr:rid]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/rid.html
[attr:subj-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/subj-group-type.html
[elem:abbrev-journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abbrev-journal-title.html
[elem:abstract]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abstract.html
[elem:article-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-id.html
[elem:article-meta]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-meta.html
[elem:copyright-holder]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-holder.html
[elem:copyright-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-statement.html
[elem:copyright-year]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-year.html
[elem:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/corresp.html
[elem:email]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/email.html
[elem:fn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html
[elem:funding-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/funding-statement.html
[elem:given-names]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/given-names.html
[elem:issn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/issn.html
[elem:journal-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-id.html
[elem:journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-title.html
[elem:kwd-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd-group.html
[elem:kwd]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd.html
[elem:license-p]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license-p.html
[elem:license]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license.html
[elem:notes]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/notes.html
[elem:permissions]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/permissions.html
[elem:pub-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html
[elem:publisher-loc]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-loc.html
[elem:publisher-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-name.html
[elem:string-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/string-name.html
[elem:subj-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subj-group.html
[elem:subject]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subject.html
[elem:surname]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/surname.html
[elem:xref]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/xref.html