Process citations / references with pandoc-manubot-cite filter

merges #300

USAGE.md

@@ -111,15 +111,39 @@ For example, the following citations all refer to the same study, but will be tr
 
 #### Citation tags
 
-The system also supports citation tags, which are recommended for the following applications:
+The system also supports citation tags, which map from one citation key (an alias) to another.
+Tags are recommended for the following applications:
 
 1. A citation's identifier contains forbidden characters, such as `;` or `=`, or ends with a non-alphanumeric character other than `/`.
    In these instances, you must use a tag.
 2. A single reference is cited many times.
    Therefore, it might make sense to define a tag, so if the citation updates (e.g. a newer version becomes available), only a single change is required.
 
-Tags should be defined in [`content/citation-tags.tsv`](content/citation-tags.tsv).
+Tags can be defined using Markdown's [link reference syntax](https://spec.commonmark.org/0.29/#link-reference-definitions) as follows:
+
+```markdown
+Citing a URL containing a `?` character [@tag:my-url].
+Citing a DOI containing parentheses [@doi:my-doi].
+
+[@tag:my-url]: url:https://openreview.net/forum?id=HkwoSDPgg
+[@tag:my-doi]: doi:10.1016/S0022-2836(05)80360-2
+```
+
+This syntax is also used by [`pandoc-url2cite`](https://github.com/phiresky/pandoc-url2cite).
+Make sure to place these link reference definitions in their own paragraphs.
+
+Another method for defining tags is to define `pandoc.citekey-aliases` in `metadata.yaml`:
+
+```yaml
+pandoc:
+  citekey-aliases:
+    tag:my-url: url:https://openreview.net/forum?id=HkwoSDPgg
+    tag:my-doi: doi:10.1016/S0022-2836(05)80360-2
+```
+
+For backwards compatability, tags can also be defined in `content/citation-tags.tsv`.
 If `citation-tags.tsv` defines the tag `study-x`, then this study can be cited like `@tag:study-x`.
+This method is deprecated.
 
 ## Reference metadata
 

build/build.sh

@@ -17,6 +17,7 @@ manubot process \
   --content-directory=content \
   --output-directory=output \
   --cache-directory=ci/cache \
+  --skip-citations \
   --log-level=INFO
 
 # Pandoc's configuration is specified via files of option defaults

build/environment.yml

@@ -19,7 +19,7 @@ dependencies:
   - watchdog=0.9.0
   - pip:
     - errorhandler==2.0.1
-    - git+https://github.com/manubot/manubot@9c58b4ea44b5080de426f1e544c6734dc22771a0
+    - git+https://github.com/manubot/manubot@5ac49d740aeba413a3af94f8b5d9b78812b641f0
     - jsonref==0.2
     - opentimestamps-client==0.7.0
     - opentimestamps==0.4.1

build/pandoc-defaults/common.yaml

@@ -5,9 +5,9 @@ filters:
 - pandoc-fignos
 - pandoc-eqnos
 - pandoc-tablenos
+- pandoc-manubot-cite
 - pandoc-citeproc
 wrap: preserve
 metadata:
-  bibliography: output/references.json
   csl: build/assets/style.csl
   link-citations: true

content/02.delete-me.md

@@ -32,9 +32,9 @@ Combined *italics and __bold__*
 - List item
 - List item
 
-superscript<sup>2</sup>
+subscript: H~2~O is a liquid
 
-subscript<sub>2n+1</sub>
+superscript: 2^10^ is 1024.
 
 [unicode superscripts](https://www.google.com/search?q=superscript+generator)⁰¹²³⁴⁵⁶⁷⁸⁹
 
@@ -46,7 +46,6 @@ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliqu
 Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
 Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
-
 Putting each sentence on its own line has numerous benefits with regard to [editing](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line) and [version control](https://rhodesmill.org/brandon/2012/one-sentence-per-line/).
 
 Line break without starting a new paragraph by putting  
@@ -111,6 +110,10 @@ Citation by tag [@tag:deep-review].
 Multiple citations can be put inside the same set of brackets [@doi:10.7554/eLife.32822; @tag:deep-review; @isbn:9780262517638].
 Manubot plugins provide easier, more convenient visualization of and navigation between citations [@doi:10.1371/journal.pcbi.1007128; @pmid:30718888; @pmcid:PMC6103790; @tag:deep-review].
 
+Citation tags (i.e. aliases) can be defined in their own paragraphs using Markdown's reference link syntax:
+
+[@tag:deep-review]: doi:10.1098/rsif.2017.0387
+
 ## Referencing figures, tables, equations
 
 Figure @fig:square-image
@@ -131,14 +134,12 @@ Equation @eq:long-equation
 
 > Quoted text
 
-
 > Quoted block of text
 >
 > Two roads diverged in a wood, and I—  
 > I took the one less traveled by,  
 > And that has made all the difference.
 
-
 Code `in the middle` of normal text, aka `inline code`.
 
 Code block with Python syntax highlighting: