Skip to content

Commit

Permalink
Added support for new citation formats, fields, and inline citations.
Browse files Browse the repository at this point in the history 
These include a new ability to use Bibtex citation format both within
the `citation` element, and within a new `bibtex` element, to create
lists of refs using these in a literatureCited element (#300), as well
as in usageCitation (#259), and referencePublication (#277) elements.
All of this helps support data papers (#269), for which pandoc-style
citation keys can be used to cite these references in the text of
Markdown blocks in the EML document.  Added these features as
demonstrations in the eml-data-paper.xml sample document.
  • Loading branch information
@mbjones
mbjones committed Apr 25, 2018
1 parent 7d0ae42 commit 3beb10b
Show file tree
Hide file tree
Showing 4 changed files with 192 additions and 16 deletions.
125 changes: 111 additions & 14 deletions src/test/resources/eml-data-paper.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@
<userId directory="https://orcid.org">https://orcid.org/0000-0000-0000-0000</userId>
<role>coPrincipalInvestigator</role>
</associatedParty>
<pubDate>2018-03-19</pubDate>
<pubDate>2018</pubDate>
<abstract>
<markdown>This project is integrating scientific research in the Arctic with education and outreach, with a strong central focus on engaging undergraduate students and visiting faculty from groups that have had little involvement in Arctic science to date. The central element of the project is a month-long research expedition to the Yukon River Delta in Alaska. The expedition provides a deep intellectual and cultural immersion in the context of an authentic research experience that is paramount for "hooking" students and keeping them moving along the pipeline to careers as Arctic scientists. The overarching scientific issue that drives the research is the vulnerability and fate of ancient carbon stored in Arctic permafrost (permanently frozen ground). Widespread permafrost thaw is expected to occur this century, but large uncertainties remain in estimating the timing, magnitude, and form of carbon that will be released when thawed. Project participants are working in collaborative research groups to make fundamental scientific discoveries related to the vulnerability of permafrost carbon in the Yukon River Delta and the potential implications of permafrost thaw in this region for the global climate system. This data set includes permafrost cores, with ammonium, nitrate, volumetric ice content, N mineralization rates, %C, and %N results from the 2017 expedition.
</markdown>
Expand Down Expand Up @@ -168,7 +168,13 @@

It can include multiple paragraphs. And these paragraphs should have enough text to wrap in a wide browser. So, repeat that last thought. And these paragraphs should have enough text to wrap in a wide browser. So, repeat that last thought.

And bulleted lists:
Text can also cite other works, such as [@jones_2001], in which case the associated key must be present
as either the citation identifier in a `bibtex` element in the EML document, or as the `id` attribute on
one of the `citation` elements in the EML document. These identifiers must be unique across the document. Tools
such as Pandoc will readily convert these citations and citation entries into various formats, including HTML, PDF,
and others.

And bulleted lists are also supported:

- Science
- Engineering
Expand Down Expand Up @@ -721,20 +727,111 @@
</attribute>
</attributeList>
</dataTable>
<referencePublication>
<bibtex>
@article{ludwig_2018,
title = {Permafrost carbon and nitrogen, Yukon-Kuskokwim Delta, Alaska},
url = {http://ecosphere.esa.org/article/yyyy.zzzzzzz},
doi = {10.xxxx/yyyy.zzzzzz},
journal = {EcoSphere},
author = {Ludwig, Sarah},
year = {2018}
}
</bibtex>
</referencePublication>
<usageCitation>
<title>Title for a paper that used this dataset.</title>
<creator>
<individualName>
<givenName>Mark</givenName>
<surName>Jarkady</surName>
</individualName>
</creator>
<pubDate>2017</pubDate>
<article>
<journal>EcoSphere</journal>
<publicationPlace>https://doi.org/10.1002/ecs2.2166</publicationPlace>
</article>
<bibtex>
@article{jones_2001,
title = {Managing scientific metadata},
volume = {5},
issn = {10897801},
url = {http://ieeexplore.ieee.org/lpdocs/epic03/wrapper.htm?arnumber=957896},
doi = {10.1109/4236.957896},
number = {5},
journal = {IEEE Internet Computing},
author = {Jones, Matthew B. and Berkley, Chad and Bojilova, Jivka and Schildhauer, Mark},
year = {2001},
pages = {59--68}
}
</bibtex>
</usageCitation>
<literatureCited>
<citation>
<bibtex>
@article{fegraus_2005,
title = {Maximizing the {Value} of {Ecological} {Data} with {Structured} {Metadata}: {An} {Introduction} to {Ecological} {Metadata} {Language} ({EML}) and {Principles} for {Metadata} {Creation}},
journal = {Bulletin of the Ecological Society of America},
author = {Fegraus, Eric H. and Andelman, Sandy and Jones, Matthew B. and Schildhauer, Mark},
year = {2005},
pages = {158--168}
}
</bibtex>
</citation>
<citation>
<title>Title for a paper that used this dataset.</title>
<creator>
<individualName>
<givenName>Mark</givenName>
<surName>Jarkady</surName>
</individualName>
</creator>
<pubDate>2017</pubDate>
<article>
<journal>EcoSphere</journal>
<publicationPlace>https://doi.org/10.1002/ecs2.2166</publicationPlace>
</article>
</citation>
<bibtex>
@article{hampton_2017,
title = {Skills and {Knowledge} for {Data}-{Intensive} {Environmental} {Research}},
volume = {67},
copyright = {All rights reserved},
issn = {0006-3568, 1525-3244},
url = {https://academic.oup.com/bioscience/article-lookup/doi/10.1093/biosci/bix025},
doi = {10.1093/biosci/bix025},
language = {en},
number = {6},
urldate = {2018-02-15},
journal = {BioScience},
author = {Hampton, Stephanie E. and Jones, Matthew B. and Wasser, Leah A. and Schildhauer, Mark P. and Supp, Sarah R. and Brun, Julien and Hernandez, Rebecca R. and Boettiger, Carl and Collins, Scott L. and Gross, Louis J. and Fernández, Denny S. and Budden, Amber and White, Ethan P. and Teal, Tracy K. and Labou, Stephanie G. and Aukema, Juliann E.},
month = jun,
year = {2017},
pages = {546--557}
}

@article{brinckman_2018,
title = {Computing environments for reproducibility: {Capturing} the “{Whole} {Tale}”},
copyright = {All rights reserved},
issn = {0167739X},
shorttitle = {Computing environments for reproducibility},
url = {http://linkinghub.elsevier.com/retrieve/pii/S0167739X17310695},
doi = {10.1016/j.future.2017.12.029},
language = {en},
urldate = {2018-04-16},
journal = {Future Generation Computer Systems},
author = {Brinckman, Adam and Chard, Kyle and Gaffney, Niall and Hategan, Mihael and Jones, Matthew B. and Kowalik, Kacper and Kulasekaran, Sivakumar and Ludäscher, Bertram and Mecum, Bryce D. and Nabrzyski, Jarek and Stodden, Victoria and Taylor, Ian J. and Turk, Matthew J. and Turner, Kandace},
month = feb,
year = {2018}
}

@article{collins_2018,
title = {Temporal heterogeneity increases with spatial heterogeneity in ecological communities},
volume = {99},
copyright = {All rights reserved},
issn = {00129658},
url = {http://doi.wiley.com/10.1002/ecy.2154},
doi = {10.1002/ecy.2154},
language = {en},
number = {4},
urldate = {2018-04-16},
journal = {Ecology},
author = {Collins, Scott L. and Avolio, Meghan L. and Gries, Corinna and Hallett, Lauren M. and Koerner, Sally E. and La Pierre, Kimberly J. and Rypel, Andrew L. and Sokol, Eric R. and Fey, Samuel B. and Flynn, Dan F. B. and Jones, Sydney K. and Ladwig, Laura M. and Ripplinger, Julie and Jones, Matt B.},
month = apr,
year = {2018},
pages = {858--865}
}
</bibtex>
</literatureCited>
</dataset>
<additionalMetadata>
<metadata>
Expand Down
24 changes: 24 additions & 0 deletions xsd/eml-dataset.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,16 @@
</xs:annotation>
</xs:element>
</xs:choice>
<xs:element name="referencePublication" type="cit:CitationType" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:appinfo>
<doc:tooltip>Reference Publication</doc:tooltip>
<doc:summary>A citation to an additional publication that serves as an important reference for a dataset.</doc:summary>
<doc:description>A citation to an additional publication that serves as an important reference for a dataset. People using this dataset should generally cite the dataset itself (using the creator, pubDate, title, publisher, and packageId fields), and consider providing an additional citation to the Reference Publication. Common cases where a Reference Publication may be useful include when a data paper is published that describes the dataset, or when a paper is intended to be the canonical or examplar reference to the dataset.
</doc:description>
</xs:appinfo>
</xs:annotation>
</xs:element>
<xs:element name="usageCitation" type="cit:CitationType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
Expand All @@ -385,6 +395,20 @@
</xs:appinfo>
</xs:annotation>
</xs:element>
<xs:element name="literatureCited" type="cit:CitationListType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<doc:tooltip>Literature Cited</doc:tooltip>
<doc:summary>A citation to articles or products which were referenced
in the dataset or its associated metadata.</doc:summary>
<doc:description>A citation to articles or products which were referenced
in the dataset or its associated metadata. The list represents the bibliography
of works related to the dataset, whether for reference, comparison, or others
purposes.
</doc:description>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:group ref="res:ReferencesGroup"/>
</xs:choice>
Expand Down
36 changes: 35 additions & 1 deletion xsd/eml-literature.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@
<xs:appinfo>
<doc:tooltip>Contact</doc:tooltip>
<doc:summary>An optional contact individual for this citation</doc:summary>
<doc:description>The contact field contains information about an alternate person to be contacted
<doc:description>The contact field contains information about an alternate person to be contacted
about this citation. Usually, the first author serves as the contact for a citation resource, e.g., a reprint request. In some cases, an alternate individual(s) may serve that function, and can be indicated here. Since contact is of the type rp:ResponsibleParty, a reference may be used.</doc:description>
</xs:appinfo>
</xs:annotation>
Expand Down Expand Up @@ -273,6 +273,16 @@
</xs:element>
</xs:choice>
</xs:sequence>
<xs:element name="bibtex" type="xs:string">
<xs:annotation>
<xs:appinfo>
<doc:tooltip>Bibtex Citation</doc:tooltip>
<doc:summary>Citation in Bibtex format.</doc:summary>
<doc:description>The bibtex field provides a parseable citation formatted according to
the Bibtex formatting conventions. The citation entry is assigned a unique key that must be unique across all bibtex fields in the EML document. The citation key can be used in markdown sections of the text to refer to this citation using the pandoc-style of inline citation keys. See the markdown element for more details. The record is delimited using curly braces. Most reference software can both import and export citations in Bibtex format, so this is a simpler representation to produce and consume than native EML citation representations.</doc:description>
</xs:appinfo>
</xs:annotation>
</xs:element>
<xs:group ref="res:ReferencesGroup"/>
</xs:choice>
<xs:attribute name="id" type="res:IDType" use="optional"/>
Expand Down Expand Up @@ -1220,4 +1230,28 @@
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType name="CitationListType">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="citation" type="CitationType">
<xs:annotation>
<xs:appinfo>
<doc:tooltip>citation</doc:tooltip>
<doc:summary>A citation within a list of citations.</doc:summary>
<doc:description>A citation within a list of citations, usually used for a literatureCited
cited list or similar. Each citation is formatted following the EML CitationType
structure.</doc:description>
</xs:appinfo>
</xs:annotation>
</xs:element>
<xs:element name="bibtex" type="xs:string">
<xs:annotation>
<xs:appinfo>
<doc:tooltip>Bibtex Citation List</doc:tooltip>
<doc:summary>List of citations in Bibtex format.</doc:summary>
<doc:description>The bibtex field provides a parseable list of citations formatted according to the Bibtex formatting conventions. Each citation entry is assigned a unique key that must be unique across all bibtex fields in the EML document. The citation key can be used in markdown sections of the text to refer to this citation using the pandoc-style of inline citation keys. See the markdown element for more details. The record is delimited using curly braces. Most reference software can both import and export citations in Bibtex format, so this is a simpler representation to produce and consume than native EML citation representations.</doc:description>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:schema>
23 changes: 22 additions & 1 deletion xsd/eml-text.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,35 @@
markdown reference syntax, for example <code>![Figure 1][fig.1.ab567w]</code>, where "fig.1.ab567w"
is the unique <code>id</code> attribute for the entity containing the reference to the image. When
client tools process such image links, they should inline the image data from that entity at the
location specified, which may involve , for example, resolving the image url from an
location specified, which may involve, for example, resolving the image url from an
<code>otherEntity</code> section. This means that there is an implied link in all Markdown
documents of the form <code>[id]: url/to/image "Optional title attribute"</code>, which is derived
from the metadata for each entity within a document. Users do not need to insert these links in
order to use them, but client software that might be generating HTML from the markdown will likely
need to generate them from the entity metadata if they are using an external Markdown pre-processor
to handle conversion to HTML and other languages.
</para>
<para>
Inline citations can also be used to cite scholarly works in the text of an EML
document. This follows the Pandoc syntax for citation keys, in which the citation keys
are in inside square brackets and separated by semicolons. Each citation is identified
by a key, which consists of an ‘@’ symbol and the citation identifier from the entry for
that citation. Citation keys may optionally have a prefix, a locator, and a suffix to
further qualify what is being cited. For example, a simple citation would be
constructed as '[@fegraus_2005]', and a list would be '[@jones_2001; @fegraus_2005]'.
The keys must be present in either the 'id' field of a
citation element in the EML document, or as the BibTex key in a 'bibtex' entry in the
EML document. It is a validation error to cite an entry for which the corresponding
citation key is not present in the EML document, and it is a validation error for the
same citation key to be reused across citation and bibtex elements in the document (each
citation identifier must be unique within the document). Clients that parse and display
EML documents should first gather up all citation and bibtex elements in the document to
create a citation database in bibtext format, and then pass that database along with the
text in markdown sections to pandoc or an equivalent tool to convert the citations into
properly formatted, human readable citations. Pandoc supports the use of Citation Style
Language (CSL) files to specify the formatting of citations upon conversion. See
http://citationstyles.org/ for more details.
</para>
<para>
Because bulleted lists and other structures within Markdown are dependent on indenting the raw
markdown text, authors and processors should pay close attention to formatting within the
Expand Down

0 comments on commit 3beb10b

Please sign in to comment.