Merge branch 'main' of github.com:habi/EAWAG-manuscript into main

.github/workflows/manubot.yaml

@@ -85,7 +85,9 @@ jobs:
           activate-environment: manubot
           environment-file: build/environment.yml
           auto-activate-base: false
+          miniforge-variant: Mambaforge
           miniforge-version: 'latest'
+          use-mamba: true
       - name: Install Spellcheck
         if: env.SPELLCHECK == 'true'
         run: bash ci/install-spellcheck.sh

USAGE.md

@@ -322,6 +322,8 @@ metadata:
   csl: https://github.com/citation-style-language/styles/raw/906cd6d43d0c136190ecfbb12f6af0ca794e3c5b/peerj.csl
 ```
 
+Instructions for generating additional manuscript output formats such as DOCX can be found in [`build/README.md`](build/README.md).
+
 ## Spellchecking
 
 When the `SPELLCHECK` environment variable is `true`, the pandoc [spellcheck filter](https://github.com/pandoc/lua-filters/tree/master/spellcheck) is run.

build/README.md

@@ -7,8 +7,19 @@ However, setting the `BUILD_PDF` environment variable to `false` will suppress P
 For example, run local builds using the command `BUILD_PDF=false bash build/build.sh`.
 
 To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variable to `true`.
-For example, use the command `BUILD_DOCX=true bash build/build.sh`.
-To export DOCX for all CI builds, set an environment variable (see docs for [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)).
+For example, use the command `BUILD_DOCX=true bash build/build.sh` locally.
+To export DOCX for all CI builds, set an environment variable in the CI configuration file.
+For GitHub Actions, set the variable in `.github\workflows\manubot.yaml` (see [docs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)):
+
+```yaml
+name: Manubot
+env:
+  BUILD_DOCX: true
+```
+
+To generate a single DOCX output of the latest manuscript with GitHub Actions, click the "Actions" tab at the top of the repository.
+Select the "Manubot" workflow, then the "Run workflow" button and check "generate DOCX output" before clicking the green "Run workflow" button.
+
 Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output.
 
 Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html).
@@ -20,12 +31,17 @@ To change the options, either edit the YAML files directly or add additional `--
 
 Note: currently, **Windows is not supported**.
 
-Install the [conda](https://conda.io) environment specified in [`environment.yml`](environment.yml) by running the following commands
+The Manubot environment is managed with [conda](https://conda.io).
+If you do not have `conda` installed, we recommend using the Miniforge3 (includes `conda`) or Mambaforge (includes `conda` and `mamba`) installers from [miniforge](https://github.com/conda-forge/miniforge).
+Install the environment from [`environment.yml`](environment.yml) by running one of following commands
 (from the repository's root directory):
 
 ```sh
-# Install the environment
+# Install the environment using conda
 conda env create --file build/environment.yml
+
+# Install the environment using mamba (faster)
+mamba env create --file build/environment.yml
 ```
 
 If the `manubot` environment is already installed, but needs to be updated to reflect changes to `environment.yml`, use one of the following options:
@@ -38,6 +54,9 @@ conda env update --file build/environment.yml
 # Slower than option 1, but guarantees a fresh environment.
 conda env remove --name manubot
 conda env create --file build/environment.yml
+
+# option 3: reinstall the manubot environment faster using mamba.
+mamba env create --force --file build/environment.yml
 ```
 
 Activate with `conda activate manubot` (assumes `conda` version of [at least](https://github.com/conda/conda/blob/9d759d8edeb86569c25f6eb82053f09581013a2a/CHANGELOG.md#440-2017-12-20) 4.4).

ci/install.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+## install.sh: run during an AppVeyor build to install the conda environment
+## and the optional Pandoc spellcheck dependencies.
+
+# Set options for extra caution & debugging
+set -o errexit \
+    -o pipefail
+
+wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh \
+  --output-document miniforge.sh
+bash miniforge.sh -b -p $HOME/miniconda
+source $HOME/miniconda/etc/profile.d/conda.sh
+hash -r
+conda config \
+  --set always_yes yes \
+  --set changeps1 no
+mamba env create --quiet --file build/environment.yml
+mamba list --name manubot
+conda activate manubot
+
+# Install Spellcheck filter for Pandoc
+if [ "${SPELLCHECK:-}" = "true" ]; then
+  bash ci/install-spellcheck.sh
+fi

content/00.front-matter.md

@@ -7,7 +7,7 @@
 _A preprint of this manuscript is available at bioRχiv with the [doi:10.1101/2023.03.30.534917](https://doi.org/10.1101/2023.03.30.534917)._
 _We submitted [`v1.0`](https://github.com/{{manubot.ci_source.repo_slug}}/releases/tag/v1.0) ([archived here](https://habi.github.io/EAWAG-manuscript/v/e1e2ef76a476174a4115937d77457037ddec95df/)) of the manuscript to [PLOS ONE](https://journals.plos.org/plosone/)._
 _A revised version [`v1.1`](https://github.com/{{manubot.ci_source.repo_slug}}/releases/tag/v1.1) ([archived here](https://habi.github.io/EAWAG-manuscript/v/c49d0b8ac8f078c226318972b06e8c4a39100bb2/)) has been submitted._
-_The version you see here [is further updated](https://github.com/{{manubot.ci_source.repo_slug}}/compare/v1.1...{%- if manubot.ci_source is defined -%}{{manubot.ci_source.commit}}{%- else -%}main{%- endif -%}#files_bucket) since re-submission._
+_The version you see here [is further updated](https://github.com/{{manubot.ci_source.repo_slug}}/compare/df99415...{%- if manubot.ci_source is defined -%}{{manubot.ci_source.commit}}{%- else -%}main{%- endif -%}#files_bucket) since re-submission._
 
 {## Template to insert build date and source ##}
 <small><em>