summaryrefslogtreecommitdiff
path: root/paper/lua-filters/cito
diff options
context:
space:
mode:
Diffstat (limited to 'paper/lua-filters/cito')
-rw-r--r--paper/lua-filters/cito/Makefile6
-rw-r--r--paper/lua-filters/cito/README.md76
-rw-r--r--paper/lua-filters/cito/cito.lua138
-rw-r--r--paper/lua-filters/cito/expected.md19
-rw-r--r--paper/lua-filters/cito/sample.bib24
-rw-r--r--paper/lua-filters/cito/sample.md10
6 files changed, 273 insertions, 0 deletions
diff --git a/paper/lua-filters/cito/Makefile b/paper/lua-filters/cito/Makefile
new file mode 100644
index 0000000..1997818
--- /dev/null
+++ b/paper/lua-filters/cito/Makefile
@@ -0,0 +1,6 @@
+test:
+ @pandoc --lua-filter=cito.lua --output=output.md --standalone sample.md
+ @diff -u expected.md output.md
+ @rm -f output.md
+
+.PHONY: test
diff --git a/paper/lua-filters/cito/README.md b/paper/lua-filters/cito/README.md
new file mode 100644
index 0000000..b0e2cd3
--- /dev/null
+++ b/paper/lua-filters/cito/README.md
@@ -0,0 +1,76 @@
+# cito
+
+This filter extracts optional CiTO (Citation Typing Ontology)
+information from citations and stores the information in the
+document's metadata. The extracted info is intended to be used in
+combination with other filters, templates, or custom writers. It
+is mandatory to run pandoc-citeproc *after* this filter if CiTO
+data is embedded in the document; otherwise pandoc-citeproc will
+interpret CiTO properties as part of the citation ID.
+
+## Using the Citation Typing Ontology
+
+The [citation typing ontology] (CiTO) allows authors to specify the
+reason a citation is given. This is helpful for the authors and
+their co-authors, and furthermore adds data that can be used by
+readers to search and navigate relevant publications.
+
+A CiTO annotation must come before the citation key and be
+followed by a colon. E.g., `@method_in:towbin_1979` signifies
+that the citation with ID *towbin_1979* is cited because the
+method described in that paper has been used in the paper at
+hand.
+
+[citation typing ontology]: http://purl.org/spar/cito
+
+## Recognized CiTO properties
+
+Below is the list of CiTO properties recognized by the filter,
+together with the aliases that can be used as shorthands.
+
+- agrees_with
+ - agree_with
+- citation
+- cites
+- cites_as_authority
+ - as_authority
+ - authority
+- cites_as_data_source
+- cites_as_evidence
+ - as_evidence
+ - evidence
+- cites_as_metadata_document
+ - as_metadata_document
+ - metadata_document
+ - metadata
+- cites_as_recommended_reading
+ - as_recommended_reading
+ - recommended_reading
+- disagrees_with
+ - disagree
+ - disagrees
+- disputes
+- documents
+- extends
+- includes_excerpt_from
+ - excerpt
+ - excerpt_from
+- includes_quotation_from
+ - quotation
+ - quotation_from
+- obtains_background_from
+ - background
+ - background_from
+- refutes
+- replies_to
+- updates
+- uses_data_from
+ - data
+ - data_from
+- uses_method_in
+ - method
+ - method_in
+
+## References
+
+This approach was described in <https://doi.org/10.7717/peerj-cs.112>.
diff --git a/paper/lua-filters/cito/cito.lua b/paper/lua-filters/cito/cito.lua
new file mode 100644
index 0000000..a1a3421
--- /dev/null
+++ b/paper/lua-filters/cito/cito.lua
@@ -0,0 +1,138 @@
+-- Copyright © 2017–2019 Albert Krewinkel, Robert Winkler
+--
+-- This library is free software; you can redistribute it and/or modify it
+-- under the terms of the MIT license. See LICENSE for details.
+
+local _version = '1.0.0'
+local properties_and_aliases = {
+ agrees_with = {
+ 'agree_with'
+ },
+ citation = {
+ },
+ cites = {
+ },
+ cites_as_authority = {
+ 'as_authority',
+ 'authority'
+ },
+ cites_as_data_source = {
+ "as_data_source",
+ "data_source"
+ },
+ cites_as_evidence = {
+ 'as_evidence',
+ 'evidence'
+ },
+ cites_as_metadata_document = {
+ 'as_metadata_document',
+ 'metadata_document',
+ 'metadata'
+ },
+ cites_as_recommended_reading = {
+ 'as_recommended_reading',
+ 'recommended_reading'
+ },
+ disagrees_with = {
+ 'disagree',
+ 'disagrees'
+ },
+ disputes = {
+ },
+ documents = {
+ },
+ extends = {
+ },
+ includes_excerpt_from = {
+ 'excerpt',
+ 'excerpt_from'
+ },
+ includes_quotation_from = {
+ 'quotation',
+ 'quotation_from'
+ },
+ obtains_background_from = {
+ 'background',
+ 'background_from'
+ },
+ refutes = {
+ },
+ replies_to = {
+ },
+ updates = {
+ },
+ uses_data_from = {
+ 'data',
+ 'data_from'
+ },
+ uses_method_in = {
+ 'method',
+ 'method_in'
+ },
+}
+
+local default_cito_property = 'citation'
+
+--- Map from cito aliases to the actual cito property.
+local properties_by_alias = {}
+for property, aliases in pairs(properties_and_aliases) do
+ -- every property is an alias for itself
+ properties_by_alias[property] = property
+ for _, alias in pairs(aliases) do
+ properties_by_alias[alias] = property
+ end
+end
+
+--- Split citation ID into cito property and the actual citation ID. If
+--- the ID does not seem to contain a CiTO property, the
+--- `default_cito_property` will be returned, together with the
+--- unchanged input ID.
+local function split_cito_from_id (citation_id)
+ local pattern = '^(.+):(.+)$'
+ local prop_alias, split_citation_id = citation_id:match(pattern)
+
+ if properties_by_alias[prop_alias] then
+ return properties_by_alias[prop_alias], split_citation_id
+ end
+
+ return default_cito_property, citation_id
+end
+
+--- Citations by CiTO properties.
+local function store_cito (cito_cites, prop, cite_id)
+ if not prop then
+ return
+ end
+ if not cito_cites[prop] then
+ cito_cites[prop] = {}
+ end
+ table.insert(cito_cites[prop], cite_id)
+end
+
+--- Returns a Cite filter function which extracts CiTO information and
+--- add it to the given collection table.
+local function extract_cito (cito_cites)
+ return function (cite)
+ for k, citation in pairs(cite.citations) do
+ local cito_prop, cite_id = split_cito_from_id(citation.id)
+ store_cito(cito_cites, cito_prop, cite_id)
+ citation.id = cite_id
+ end
+ return cite
+ end
+end
+
+--- Lists of citation IDs, indexed by CiTO properties.
+local citations_by_property = {}
+
+return {
+ {
+ Cite = extract_cito(citations_by_property)
+ },
+ {
+ Meta = function (meta)
+ meta.cito_cites = citations_by_property
+ return meta
+ end
+ }
+}
diff --git a/paper/lua-filters/cito/expected.md b/paper/lua-filters/cito/expected.md
new file mode 100644
index 0000000..707ff74
--- /dev/null
+++ b/paper/lua-filters/cito/expected.md
@@ -0,0 +1,19 @@
+---
+cito_cites:
+ cites_as_evidence:
+ - Li95
+ cites_as_recommended_reading:
+ - 'Upper\_writers\_1974'
+---
+
+Abstract
+========
+
+This is an example article. It was written under the influence of
+coffee, which acts to counter fatigue [@Li95].
+
+Further reading
+===============
+
+Authors struggling to fill their document with content are referred to
+@Upper_writers_1974.
diff --git a/paper/lua-filters/cito/sample.bib b/paper/lua-filters/cito/sample.bib
new file mode 100644
index 0000000..4a4ff62
--- /dev/null
+++ b/paper/lua-filters/cito/sample.bib
@@ -0,0 +1,24 @@
+@article{Li95,
+ author = {L. Linde},
+ journal = {Ergonomics},
+ pages = {864--885},
+ title = {Mental effects of caffeine in fatigued and
+ non-fatigued female and male subjects},
+ volume = {38},
+ year = {1995},
+}
+
+@article{Upper_writers_1974,
+ author = {Upper, Dennis},
+ journal = {Journal of Applied Behavior Analysis},
+ number = {3},
+ pages = {497--497},
+ publisher = {Blackwell Publishing Ltd},
+ title = {The unsuccessful self-treatment of a case of
+ “writer's block”},
+ volume = {7},
+ year = {1974},
+ doi = {10.1901/jaba.1974.7-497a},
+ issn = {1938-3703},
+ url = {http://dx.doi.org/10.1901/jaba.1974.7-497a},
+}
diff --git a/paper/lua-filters/cito/sample.md b/paper/lua-filters/cito/sample.md
new file mode 100644
index 0000000..a9989cb
--- /dev/null
+++ b/paper/lua-filters/cito/sample.md
@@ -0,0 +1,10 @@
+# Abstract
+
+This is an example article. It was written under the influence of
+coffee, which acts to counter fatigue [@cites_as_evidence:Li95].
+
+
+# Further reading
+
+Authors struggling to fill their document with content are referred to
+@recommended_reading:Upper_writers_1974.
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-03 10:19:05 +0000