Update Manubot Rootstock 2021-08-05 (#136)

* setup.bash: interactive script to guide setup merges manubot/rootstock#417 closes manubot/rootstock#401 * Add "gh repo create" to SETUP.md merges manubot/rootstock#419 closes manubot/rootstock#418 Co-authored-by: Daniel Himmelstein <daniel.himmelstein@gmail.com> Co-authored-by: Anthony Gitter <agitter@users.noreply.github.com> * BUILD_LATEX for basic LaTeX manuscript merges manubot/rootstock#384 refs manubot/rootstock#249 * Pandoc 2.14: update HTML plugins, CSL style, citekey syntax merges manubot/rootstock#427 Co-authored-by: Daniel Himmelstein <daniel.himmelstein@gmail.com> Co-authored-by: Anthony Gitter <agitter@users.noreply.github.com> Co-authored-by: nfry321 <58332182+nfry321@users.noreply.github.com> Co-authored-by: Tiago Lubiana <tiago.lubiana.alves@usp.br> Co-authored-by: Daniel Himmelstein <daniel.himmelstein@gmail.com> Co-authored-by: Anthony Gitter <agitter@users.noreply.github.com> Co-authored-by: Vincent Rubinetti <vince.rubinetti@gmail.com>
greenelab · Aug 5, 2021 · 45c6d5b · 45c6d5b
1 parent b44d607
commit 45c6d5b
Show file tree

Hide file tree

Showing 13 changed files with 323 additions and 33 deletions.
diff --git a/SETUP.md b/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 git@github.com:$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:

diff --git a/USAGE.md b/USAGE.md
@@ -133,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 must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`).
-
-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. -->
+The citation key syntax is described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citation-syntax):
+
+> 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]`.
+
+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.

diff --git a/build/assets/style.csl b/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=" ">

diff --git a/build/build.sh b/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"

diff --git a/build/environment.yml b/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@553090a16ac24a9fdc3f8df241a91b790c140865
+    - 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

diff --git a/build/pandoc/defaults/common.yaml b/build/pandoc/defaults/common.yaml
@@ -6,7 +6,7 @@ filters:
 - pandoc-eqnos
 - pandoc-tablenos
 - pandoc-manubot-cite
-- pandoc-citeproc
+- citeproc
 wrap: preserve
 metadata:
   csl: https://www.zotero.org/styles/cell-systems

diff --git a/build/pandoc/defaults/html.yaml b/build/pandoc/defaults/html.yaml
@@ -25,6 +25,7 @@ include-after-body:
 - build/plugins/mathjax.html
 #- build/plugins/scite.html
 variables:
+  document-css: false
   math: ""
 html-math-method:
   method: mathjax
diff --git a/build/pandoc/defaults/latex.yaml b/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
diff --git a/build/plugins/anchors.html b/build/plugins/anchors.html
@@ -10,7 +10,8 @@
 <script type="module">
   // which types of elements to add anchors next to, in "document.querySelector"
   // format
-  const typesQuery = 'h1, h2, h3, [id^="fig:"], [id^="tbl:"], [id^="eq:"]';
+  const typesQuery =
+    'h1, h2, h3, div[id^="fig:"], div[id^="tbl:"], span[id^="eq:"]';
 
   // start script
   function start() {

diff --git a/build/plugins/jump-to-first.html b/build/plugins/jump-to-first.html
@@ -15,9 +15,11 @@
 
   // start script
   function start() {
-    if (references !== "false") makeButtons("ref-", "p", "reference");
-    if (figures !== "false") makeButtons("fig:", "figcaption", "figure");
-    if (tables !== "false") makeButtons("tbl:", "caption", "table");
+    if (references !== "false")
+      makeButtons(`div[id^="ref-"]`, ".csl-left-margin", "reference");
+    if (figures !== "false")
+      makeButtons(`div[id^="fig:"]`, "figcaption", "figure");
+    if (tables !== "false") makeButtons(`div[id^="tbl:"]`, "caption", "table");
   }
 
   // when jump button clicked
@@ -45,7 +47,7 @@
 
   // add button next to each reference entry, figure, or table
   function makeButtons(query, containerQuery, subject) {
-    const elements = document.querySelectorAll(`[id^="${query}"`);
+    const elements = document.querySelectorAll(query);
     for (const element of elements) {
       const id = element.id;
       const buttonContainer = element.querySelector(containerQuery);

diff --git a/build/plugins/tooltips.html b/build/plugins/tooltips.html
@@ -230,6 +230,7 @@
       "data-selected",
       "data-highlighted",
       "data-glow",
+      "class",
     ];
     for (const attribute of attributes) {
       sourceCopy.removeAttribute(attribute);
@@ -290,9 +291,8 @@
     prevButton.classList.add("icon_button");
     nextButton.classList.add("icon_button");
     prevButton.innerHTML = document.querySelector(".icon_caret_left").innerHTML;
-    nextButton.innerHTML = document.querySelector(
-      ".icon_caret_right"
-    ).innerHTML;
+    nextButton.innerHTML =
+      document.querySelector(".icon_caret_right").innerHTML;
     navBar.appendChild(prevButton);
     navBar.appendChild(document.createTextNode(text));
     navBar.appendChild(nextButton);
@@ -336,7 +336,7 @@
     if (!target) return;
 
     // if ref or figure, modify target to get expected element
-    if (id.indexOf("ref-") === 0) target = target.querySelector("p");
+    if (id.indexOf("ref-") === 0) target = target.querySelector(":nth-child(2)");
     else if (id.indexOf("fig:") === 0) target = target.querySelector("figure");
 
     return target;

diff --git a/build/themes/default.html b/build/themes/default.html
@@ -267,8 +267,7 @@
   }
 
   /* table auto-number */
-  table > caption > span:first-of-type,
-  div.table_wrapper > table > caption > span:first-of-type {
+  table > caption > span:first-of-type {
     font-weight: bold;
     margin-right: 5px;
   }
@@ -495,6 +494,15 @@
     top: 0.125em;
   }
 
+  /* -------------------------------------------------- */
+  /* references */
+  /* -------------------------------------------------- */
+
+  .csl-entry {
+    margin-top: 15px;
+    margin-bottom: 15px;
+  }
+
   /* -------------------------------------------------- */
   /* print control */
   /* -------------------------------------------------- */
@@ -626,7 +634,6 @@
 
   /* tablenos wrapper */
   .tablenos {
-    /* show scrollbar on tables if necessary to prevent overflow */
     width: 100%;
     margin: 20px 0;
   }