Merge pull request #82 from indigo-dc/release/v4.0

Release/v4.0

SETUP.md

@@ -1,7 +1,8 @@
 # Table of contents
 
 - [Creating a new manuscript](#creating-a-new-manuscript)
-  * [Configuration](#configuration)
+  * [Using setup script](#using-setup-script)
+  * [Manual configuration](#manual-configuration)
   * [Create repository](#create-repository)
   * [Continuous integration](#continuous-integration)
     + [GitHub Actions](#github-actions)
@@ -27,8 +28,33 @@ These steps should be performed in a command-line shell (terminal), starting in
 Setup is supported on Linux, macOS, and Windows.
 Windows setup requires [Git Bash](https://gitforwindows.org/) or [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/faq).
 
-## Configuration
+## Using setup script
+Creating a new manuscript using GitHub actions, the recommended default CI service (see below), can be achieved easily using the [setup script](https://github.com/manubot/rootstock/blob/main/setup.bash).
+This simply runs the steps detailed below in the manual configuration.
 
+Use the command below to copy `setup.bash` and run it.
+You can check the code that will be executed [here](https://github.com/manubot/rootstock/blob/main/setup.bash).
+
+````sh
+bash <( curl --location https://github.com/manubot/rootstock/raw/main/setup.bash )
+````
+The script will then take you through the process of cloning the rootstock repo, make the changes required to use GitHub actions, edit the README to point to your repo and commit the changes.
+Your new manuscript repo is then ready for you to start adding your own content.
+
+This script does not not create the remote repo for you, so you will be prompted to manually create an empty GitHub repository at <https://github.com/new>.
+Do not initialize the repository, other than optionally adding a description.
+
+### CLI
+There is also a command line interface for users who want to create manuscripts at scale and in an automated way.
+See the help for details.
+
+````sh
+bash setup.bash --help
+````
+
+## Manual configuration
+
+If you do not wish to use the above setup script to configure your new manuscript repository, you can instead execute the steps manually.
 First, you must configure two environment variables (`OWNER` and `REPO`).
 These variables specify the GitHub repository for the manuscript (i.e. `https://github.com/OWNER/REPO`).
 Make sure that the case of `OWNER` matches how your username is displayed on GitHub.
@@ -63,7 +89,8 @@ git remote set-url origin https://github.com/$OWNER/$REPO.git
 git remote set-url origin [email protected]:$OWNER/$REPO.git
 ```
 
-Next, you must manually create an empty GitHub repository at <https://github.com/new>.
+Then create an empty repository on GitHub. 
+You can do this at <https://github.com/new> or via the [GitHub command line interface](https://github.com/cli/cli) (if installed) with `gh repo create`.
 Make sure to use the same "Owner" and "Repository name" specified above.
 Do not initialize the repository, other than optionally adding a Description.
 Next, push your cloned manuscript:

USAGE.md

@@ -110,6 +110,19 @@ When choosing which source to use for a citation, we recommend the following ord
 9. For references that do not have any of the above persistent identifiers, the citation key does not need to include a prefix.
    Citing `@old-manuscript` will work, but only if reference metadata is [provided manually](#reference-metadata).
 
+Manubot is able to infer certain prefixes,
+such some citations can be formatted like `@accession` (without a prefix).
+Examples includes DOIs like `@10.15363/thinklab.4` or `@10/993`,
+PMC / PubMed identifiers like `@PMC4497619` or `@26158728`,
+arXiv identifier like `@1508.06576v2`,
+and Wikidata identifiers like `@Q50051684`.
+To disable citekey prefix inference, add the following to `metadata.yaml`:
+
+```yaml
+pandoc:
+  manubot-infer-citekey-prefixes: false
+```
+
 Cite multiple items at once like:
 
 ```md
@@ -120,14 +133,23 @@ Note that multiple citations must be semicolon separated.
 Be careful not to cite the same study using identifiers from multiple sources.
 For example, the following citations all refer to the same study, but will be treated as separate references: `[@doi:10.7717/peerj.705; @pmc:PMC4304851; @pubmed:25648772]`.
 
-Citation keys must adhere to the syntax described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citations):
+The citation key syntax is described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citation-syntax):
 
-> The citation key must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`).
+> Unless a citation key start with a letter, digit, or `_`,
+> and contains only alphanumerics and internal punctuation characters (`:.#$%&-+?<>~/`),
+> it must be surrounded by curly braces,
+> which are not considered part of the key.
+> In `@Foo_bar.baz.`, the key is `Foo_bar.baz`.
+> The final period is not *internal* punctuation,
+> so it is not included in the key.
+> In `@{Foo_bar.baz.}`, the key is `Foo_bar.baz.`, including the final period.
+> The curly braces are recommended if you use URLs as keys:
+> `[@{https://example.com/bib?name=foobar&date=2000}, p. 33]`.
 
-To evaluate whether a citation key fully matches this syntax, try [this online regex](https://regex101.com/r/mXZyY2/latest).
-If the citation key is not valid, use the [citation aliases](#citation-aliases) workaround below.
-This is required for citation keys that contain forbidden characters such as `;` or `=` or end with a non-alphanumeric character such as `/`.
-<!-- See [jgm/pandoc#6026](https://github.com/jgm/pandoc/issues/6026) for progress on a more flexible Markdown citation key syntax. -->
+If a citation key does not fully match [this online regex](https://regex101.com/r/mXZyY2/latest)
+(for example, contains characters such as `;` or `=` or end with a non-alphanumeric character such as `/`),
+make sure to surround it with curly braces or use the [citation aliases](#citation-aliases) workaround below.
+<!-- See [jgm/pandoc#6026](https://github.com/jgm/pandoc/issues/6026) on the curly-brace syntax for Markdown citation keys, which was introduced in Pandoc 2.14. -->
 
 Prior to Rootstock commit [`6636b91`](https://github.com/manubot/rootstock/commit/6636b912c6b41593acd2041d34cd4158c1b317fb) on 2020-01-14, Manubot processed citations separately from Pandoc.
 Switching to a Pandoc filter improved reliability on complex documents, but restricted the syntax of citation keys slightly.
@@ -136,7 +158,7 @@ By default, `pandoc-manubot-cite` does not fail upon invalid citations, although
 
 ```yaml
 pandoc:
-  manubot-fail-on-errors: True
+  manubot-fail-on-errors: true
 ```
 
 #### Citation aliases

build/assets/style.csl

@@ -47,7 +47,7 @@
       <text variable="citation-number"/>
     </layout>
   </citation>
-  <bibliography hanging-indent="true" second-field-align="flush">
+  <bibliography second-field-align="flush">
     <layout>
       <text variable="citation-number" suffix=". "/>
       <group delimiter=" ">

build/build.sh

@@ -85,6 +85,15 @@ if [ "${BUILD_DOCX:-}" = "true" ]; then
     --defaults=docx.yaml
 fi
 
+# Create LaTeX output (if BUILD_LATEX environment variable equals "true")
+if [ "${BUILD_LATEX:-}" = "true" ]; then
+  echo >&2 "Exporting LaTeX manuscript"
+  pandoc \
+    --data-dir="$PANDOC_DATA_DIR" \
+    --defaults=common.yaml \
+    --defaults=latex.yaml
+fi
+
 # Spellcheck
 if [ "${SPELLCHECK:-}" = "true" ]; then
   export ASPELL_CONF="add-extra-dicts $(pwd)/build/assets/custom-dictionary.txt; ignore-case true"

build/environment.yml

@@ -5,11 +5,10 @@ dependencies:
   - cairo=1.14.12
   - cairocffi=0.8.0
   - cffi=1.12.3
-  - ghp-import=0.5.5
+  - ghp-import=1.0.0
   - jinja2=2.11.2
   - jsonschema=3.2.0
-  - pandoc=2.9.2
-  - panflute=1.12.5
+  - pandoc=2.14
   - pango=1.40.14
   - pip=20.2
   - psutil=5.7.3
@@ -21,14 +20,15 @@ dependencies:
   - yamllint=1.25.0
   - pip:
     - errorhandler==2.0.1
-    - git+https://github.com/manubot/manubot@55c5e1e526261ebadd2aefed2c2757792d8d2ebf
+    - git+https://github.com/manubot/manubot@2c028a7a87be24a76e2dec3ac7db6e8754ae6d4a
     - isbnlib==3.10.3
     - opentimestamps-client==0.7.0
     - opentimestamps==0.4.1
-    - pandoc-eqnos==2.3.0
-    - pandoc-fignos==2.3.1
-    - pandoc-tablenos==2.2.2
-    - pandoc-xnos==2.4.3
+    - pandoc-eqnos==2.5.0
+    - pandoc-fignos==2.4.0
+    - pandoc-tablenos==2.3.0
+    - pandoc-xnos==2.5.0
+    - panflute==2.1.0
     - pybase62==0.4.3
     - pysha3==1.0.2
     - python-bitcoinlib==0.10.2

build/pandoc/defaults/common.yaml

@@ -6,7 +6,7 @@ filters:
 - pandoc-eqnos
 - pandoc-tablenos
 - pandoc-manubot-cite
-- pandoc-citeproc
+- citeproc
 wrap: preserve
 metadata:
   csl: build/assets/style.csl

build/pandoc/defaults/html.yaml

@@ -3,22 +3,29 @@
 to: html5
 output-file: output/manuscript.html
 # include-before-body:
-# - build/plugins/d3.html
+### third-party plugins
+#- build/plugins/d3.html
 include-after-body:
+### theme
 - build/themes/default.html
-# - build/plugins/inline-svg.html
-- build/plugins/anchors.html
+### first-party plugins
+- build/plugins/core.html # needed for all first-party plugins
 - build/plugins/accordion.html
-- build/plugins/tooltips.html
+- build/plugins/anchors.html
+- build/plugins/attributes.html
+#- build/plugins/inline-svg.html
 - build/plugins/jump-to-first.html
+- build/plugins/lightbox.html
 - build/plugins/link-highlight.html
 - build/plugins/table-of-contents.html
-- build/plugins/lightbox.html
-- build/plugins/attributes.html
-- build/plugins/math.html
-- build/plugins/hypothesis.html
+- build/plugins/tooltips.html
+### third-party plugins
 - build/plugins/analytics.html
+- build/plugins/hypothesis.html
+- build/plugins/mathjax.html
+#- build/plugins/scite.html
 variables:
-  math: ''
+  document-css: false
+  math: ""
 html-math-method:
   method: mathjax

build/pandoc/defaults/latex.yaml

@@ -0,0 +1,4 @@
+# Pandoc --defaults for LaTeX output.
+# Load on top of common defaults.
+to: latex
+output-file: output/manuscript.tex