diff --git a/.gitignore b/.gitignore index 83b2bd4..a88db7d 100644 --- a/.gitignore +++ b/.gitignore @@ -25,5 +25,17 @@ __pycache__/ # Don't make budgets public budgets/ -# Stupid Mac Folder crap -.DS_Store \ No newline at end of file +# Operating system specific files + +## Linux +*~ +.Trash-* + +## macOS +.DS_Store +._* +.Trashes + +## Windows +Thumbs.db +[Dd]esktop.ini diff --git a/.travis.yml b/.travis.yml index 60cc09a..29420f4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,7 +5,7 @@ branches: only: - master before_install: - - wget https://repo.continuum.io/miniconda/Miniconda3-4.5.4-Linux-x86_64.sh + - wget https://repo.continuum.io/miniconda/Miniconda3-4.5.11-Linux-x86_64.sh --output-document miniconda.sh - bash miniconda.sh -b -p $HOME/miniconda - source $HOME/miniconda/etc/profile.d/conda.sh diff --git a/SETUP.md b/SETUP.md index 554cabd..22a4f06 100644 --- a/SETUP.md +++ b/SETUP.md @@ -9,10 +9,12 @@ Setup is supported on Linux and macOS, but [**not on Windows**](https://github.c 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. +In general, assume that all commands in this setup are case-sensitive. **Edit the following commands with your manuscript's information:** ```sh -# GitHub account (change from greenelab) +# GitHub username (change from greenelab) OWNER=greenelab # Repository name (change from manubot-rootstock) REPO=manubot-rootstock diff --git a/USAGE.md b/USAGE.md index df02493..5bd3507 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,18 +1,18 @@ # Manubot usage guidelines -This repository uses the [Manubot](https://github.com/greenelab/manubot) to automatically produce a manuscript from its source. +This repository uses [Manubot](https://github.com/greenelab/manubot-rootstock) to automatically produce a manuscript from the source in the [`content`](content) directory. ## Manubot markdown Manuscript text should be written in markdown files, which should be located in [`content`](content) with a digit prefix for ordering (e.g. `01.`, `02.`, etc.) and a `.md` extension. -For basic formatting, check out the [CommonMark Help](http://commonmark.org/help/) page for an introduction to the formatting options provided by standard markdown. -In addition, manubot supports an extended version of markdown, tailored for scholarly writing, which includes [Pandoc's Markdown](http://pandoc.org/MANUAL.html#pandocs-markdown) and the extensions discussed below. +For basic formatting, check out the [CommonMark Help](https://commonmark.org/help/) page for an introduction to the formatting options provided by standard markdown. +In addition, Manubot supports an extended version of markdown, tailored for scholarly writing, which includes [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and the extensions discussed below. Within a paragraph in markdown, single newlines are interpreted as whitespace (same as a space). A paragraph's source does not need to contain newlines. However, "one paragraph per line" makes the git diff less precise, leading to less granular review commenting, and makes conflicts more likely. -Therefore, we recommend using [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/ "Semantic Linefeeds. Brandon Rhodes. 2012") — newlines between sentences. +Therefore, we recommend using [semantic linefeeds](https://rhodesmill.org/brandon/2012/one-sentence-per-line/ "Semantic Linefeeds. Brandon Rhodes. 2012") — newlines between sentences. We have found that "one sentence per line" is preferable to "word wrap" or "one paragraph per line". ### Tables @@ -30,7 +30,7 @@ Table: Caption for this example table. {#tbl:example-id} Support for table numbering and citation is provided by [`pandoc-tablenos`](https://github.com/tomduck/pandoc-tablenos). Above, `{#tbl:example-id}` sets the table ID, which creates an HTML anchor and allows citing the table like `@tbl:example-id`. -For easy creation of markdown tables, check out the [Tables Generator](http://www.tablesgenerator.com/markdown_tables) webapp. +For easy creation of markdown tables, check out the [Tables Generator](https://www.tablesgenerator.com/markdown_tables) webapp. ### Figures @@ -45,11 +45,11 @@ This figure can be cited in the text using `@fig:example-id`. In context, a figure citation may look like: `Figure {@fig:example-id}B shows …`. For images created by the manuscript authors that are hosted elsewhere on GitHub, we recommend using a [versioned](https://help.github.com/articles/getting-permanent-links-to-files/) GitHub URL to embed figures, thereby preserving exact image provenance. -When embedding SVG images hosted on GitHub, passing the URL through [RawGit](https://rawgit.com/) is necessary. -An example of a URL that has been passed through RawGit is: +When embedding SVG images hosted on GitHub, it's necessary to append `?sanitize=true` to the `raw.githubusercontent.com` URL. +For example: ``` -https://cdn.rawgit.com/greenelab/scihub/572d6947cb958e797d1a07fdb273157ad9154273/figure/citescore.svg +https://raw.githubusercontent.com/greenelab/scihub/572d6947cb958e797d1a07fdb273157ad9154273/figure/citescore.svg?sanitize=true ``` Figures placed in the [`content/images`](content/images) directory can be embedded using their relative path. @@ -59,19 +59,19 @@ For example, we embed an [ORCID](https://orcid.org/) icon inline using: ![ORCID icon](images/orcid.svg){height="13px"} ``` -The bracketed text following the image declaration is interpreted by Pandoc's [`link_attributes`](http://pandoc.org/MANUAL.html#extension-link_attributes) extension. +The bracketed text following the image declaration is interpreted by Pandoc's [`link_attributes`](https://pandoc.org/MANUAL.html#extension-link_attributes) extension. For example, the following will override the figure number to be "S1" and set the image width to 5 inches: ```md {#fig:supplement tag="S1" width="5in"} ``` -We recommend always specifying the width of SVG images (even if just `width="100%"`), since otherwise SVGs may not render properly in the [WeasyPrint](http://weasyprint.org/) PDF export. +We recommend always specifying the width of SVG images (even if just `width="100%"`), since otherwise SVGs may not render properly in the [WeasyPrint](https://weasyprint.org/) PDF export. ### Citations -Manubot supports Pandoc [citations](http://pandoc.org/MANUAL.html#citations) via `pandoc-citeproc`. -However, Manubot performs automated citation processing and metadata retrieval on raw citations. +Manubot supports Pandoc [citations](https://pandoc.org/MANUAL.html#citations) via `pandoc-citeproc`. +However, Manubot performs automated citation processing and metadata retrieval on in-text citations. Therefore, citations must be of the following form: `@source:identifier`, where `source` is one of the options described below. When choosing which source to use for a citation, we recommend the following order: @@ -80,6 +80,8 @@ When choosing which source to use for a citation, we recommend the following ord 3. PubMed ID, cite like `@pmid:26158728`. 4. _arXiv_ ID, cite like `@arxiv:1508.06576v2`. 5. URL / webpage, cite like `@url:http://openreview.net/pdf?id=Sk-oDY9ge`. +6. For references that do not have any of the persistent identifiers above, use a raw citation like `@raw:old-manuscript`. +Metadata for raw citations must be provided manually. Cite multiple items at once like: @@ -109,8 +111,8 @@ The Manubot workflow requires the bibliographic details for references (the set The Manubot attempts to automatically retrieve metadata and generate valid citeproc JSON for references, which is exported to `output/references.json`. However, in some cases the Manubot fails to retrieve metadata or generates incorrect or incomplete citeproc metadata. Errors are most common for `url` references. -For these references, you can manually specify the correct citeproc in [`content/manual-references.json`](content/manual-references.json), which will override the automatically generated reference data. -To do so, create a new citeproc record that contains the field `"standard_citation"` with the appropriate reference identifier as its value. +For these references, you can manually specify the correct CSL Data in [`content/manual-references.json`](content/manual-references.json), which will override the automatically generated reference data. +To do so, create a new CSL JSON Item that contains the field `"standard_citation"` with the appropriate reference identifier as its value. The identifier can be obtained from the `standard_citation` column of `citations.tsv`, which is located in the `output` branch or in the `output` subdirectory of local builds. As an example, `manual-references.json` contains: @@ -118,11 +120,23 @@ As an example, `manual-references.json` contains: "standard_citation": "url:https://github.com/greenelab/manubot-rootstock" ``` +The metadata for `raw` citations must be provided in `manual-references.json` or an error will occur. +For example, to cite `@raw:private-message` in a manuscript, a corresponding CSL Item in `manual-references.json` is required, such as: + +```json +{ + "type": "personal_communication", + "standard_citation": "raw:private-message", + "title": "Personal communication with Doctor X" +} +``` + +All references provided in `manual-references.json` must provide values for the `type` and `standard_citation` fields. For guidance on what CSL JSON should be like for different document types, refer to [these examples](https://github.com/aurimasv/zotero-import-export-formats/blob/a51c342e66bebd97b73a7230047b801c8f7bb690/CSL%20JSON.json). ## Manuscript metadata -[`content/metadata.yaml`](content/metadata.yaml) contains manuscript metadata that gets passed through to Pandoc, via a [`yaml_metadata_block`](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block). +[`content/metadata.yaml`](content/metadata.yaml) contains manuscript metadata that gets passed through to Pandoc, via a [`yaml_metadata_block`](https://pandoc.org/MANUAL.html#extension-yaml_metadata_block). `metadata.yaml` should contain the manuscript `title`, `authors` list, `keywords`, and `lang` ([language tag](https://www.w3.org/International/articles/language-tags/ "W3C: Language tags in HTML and XML")). Additional metadata, such as `date`, will automatically be created by the Manubot. Manubot uses the [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) specified in [`build.sh`](build/build.sh) for setting the manuscript's date. @@ -167,3 +181,20 @@ For additional examples, check out existing manuscripts that use the Manubot (so + The Manubot 2018 Development Proposal ([source](https://github.com/greenelab/manufund-2018), [manuscript](https://greenelab.github.io/manufund-2018/)) If you are using the Manubot, feel free to submit a pull request to add your manuscript to the list above. + +## Citing Manubot + +To cite the Manubot project or for more information on its design and history, see `@url:https://greenelab.github.io/meta-review/`: + +> **Open collaborative writing with Manubot**
+Daniel S. Himmelstein, David R. Slochower, Venkat S. Malladi, Casey S. +Greene, Anthony Gitter
+_Manubot Preprint_ (2018) + +## Acknowledgments + +We would like to thank the contributors and funders whose support makes the Manubot project possible. +Specifically, Manubot development has been financially supported by: + +- the **Alfred P. Sloan Foundation** in [Grant G-2018-11163](https://sloan.org/grant-detail/8501) to [**@dhimmel**](https://github.com/dhimmel). +- the **Gordon & Betty Moore Foundation** ([**@DDD-Moore**](https://github.com/DDD-Moore)) in [Grant GBMF4552](https://www.moore.org/grant-detail?grantId=GBMF4552) to [**@cgreene**](https://github.com/cgreene). diff --git a/build/assets/style.csl b/build/assets/style.csl index 756c758..07ba262 100644 --- a/build/assets/style.csl +++ b/build/assets/style.csl @@ -51,7 +51,7 @@ - + @@ -60,7 +60,7 @@ - + diff --git a/build/environment.yml b/build/environment.yml index a77ba34..77d7a50 100644 --- a/build/environment.yml +++ b/build/environment.yml @@ -6,23 +6,25 @@ dependencies: - conda-forge::cffi=1.11.5 - conda-forge::ghp-import=0.5.5 - conda-forge::jinja2=2.10 + - conda-forge::jsonschema=2.6.0 - conda-forge::pandas=0.23.4 - - conda-forge::pandoc=2.2.2 - - conda-forge::python=3.6.6 - - conda-forge::pyyaml=3.12 + - conda-forge::pandoc=2.3.1 + - conda-forge::python=3.6.5 + - conda-forge::pyyaml=3.13 - conda-forge::requests=2.19.1 - conda-forge::watchdog=0.8.3 - pip: - errorhandler==2.0.1 - - git+https://github.com/greenelab/manubot@66a6efc6f4b84153a813aa423ec00725ed1417c5 + - git+https://github.com/greenelab/manubot@a008126b39e3bd4b80ebaa5af9f9fa2f30b3a670 + - jsonref==0.2 - opentimestamps-client==0.6.0 - - opentimestamps==0.4.0 + - opentimestamps==0.3.0 - pandoc-eqnos==1.3.0 - pandoc-fignos==1.3.0 - pandoc-tablenos==1.3.0 - pandoc-xnos==1.1.1 - pybase62==0.4.0 - pysha3==1.0.2 - - python-bitcoinlib==0.10.1 + - python-bitcoinlib==0.9.0 - requests-cache==0.4.13 - weasyprint==0.42.3