Modish

Modish runs easy-to-write tests to check the output of a CSL bibliographic style.

• The Citation Style Language makes it possible to write bibliographic styles that automate the formatting of citations and bibliographies.
• Modish helps making sure that the citations and bibliographies formatted by a CSL style match the guidelines it implements.

Installation

For now, the easiest way to use Modish is to download the latest release for your platform. Unzip the standalone executable and place it in your PATH.

Getting started

• Create a directory named tests in your CSL project.

• In the tests directory, create a file in CSL JSON format (e.g. references.json). Easiest way: export relevant references from your Zotero library.

• Edit tests/books.yml (name the file however you want, but place it in the tests directory).

  Here is what a minimal test file could look like:

  style: src/apa.csl
  
  input:
    - Thompson1991 p. 128
    - Mills1959
  
  citations:
    - "(Thompson, 1963/1991, p. 128)"
    - "(Mills, 1956/1959)"
  
  bibliography:
    - "Mills, C. W. (1959). <i>The power elite</i>. Oxford University Press. (Original work published 1956)"
    - "Thompson, E. P. (1991). <i>The Making of the English working class</i>. Penguin Books. (Original work published 1963)"

  The first line (style) states the path of the CSL file to be tested; input gives, as a list, the references to be cited, using the id specified in the CSL-JSON file; citations and bibliography specify, as lists, the expected outputs. See below for more details on the test files.

• Run modish test.

Options When Testing

The modish test command accepts the following arguments:

• -b, --bail: Stop after the first test failure.
• -q, --quiet: Suppress all normal output.
• --verbose: Output results for all test files.
• -w, --watch: Rerun tests when files change.

Bibliography Files in CSL JSON

All .json files in the tests directory are expected to be in CSL JSON format. They stipulate the items (books, journal articles, etc.) for which the tests will check generated citations and/or bibliography.

It is expected that the CSL JSON files will be generated by exporting items from your bibliography management software. The BetterBibTex plugin for Zotero is recommended: it give much more control when exporting items, among other things by allowing you to specify how identifiers (also called "citation keys") are generated, to manually specify and fix identifiers for specific items, or to automatically update an export when items change in Zotero.

You can have any number of CSL JSON files in the tests directory.

Test Files

Test files are expected to be located in a tests directory at the root of your project (or, more exactly, in the directory where you run the modish test command). You can have as many test files as you want, each testing different things (e.g. different item types, bibliography entries VS subsequent citations, etc). Furthermore, as described below, each test file can include a series of different tests. By relying on this, it is also possible to put all the tests in the same file.

Test files are written in YAML, and need to specify:

• the path of the CSL file to be tested (style),
• the identifier of the references (specified in the CSL JSON files) for which citations will be generated (input),
• and the expected output for these items when they are formatted as citations and/or bibliography.

style and lang

style specifies the path of the CSL file, relative to where you run the command (typically the root of your project):

style: style.csl

Optionally, it is also possible to specify the language/locale:

style: style.csl
lang: de-CH

This has no effect when the style defines a default-locale. For styles without a default-locale, citations and bibliography are formatted using en-US by default.

input

The input is a list of identifiers:

input:
- ThompsonMaking p. 128
- PikettyCapital; MillsPower
- MillsPower chap. 1

The identifiers are the id strings in your CSL-JSON file(s). Each identifier in the input list can optionally be followed by a space and a locator, as shown in the examples. Locators in full form ("page", "chapter", "article", etc.) are supported, but you can also use English-language abbreviations and symbols ("p.", "pp.", "chap.", "art.", "bk.", "fig.", "figs.", "§", "§§", etc.). To include several references in the same citation (e.g. to test separators), connect them by semicolons, as in the example.

output: citations and bibliography

It is possible to test both citations and bibliography, or only either of them, but at least one must be specified in a test.

The expected citations are also given as a list, in the same order as the input:

citations:
- "Thompson (1991 [1963]), <i>The Making…</i>, p. 128."
- "Piketty (2014), <i>Capital…</i>; Mills (1956), <i>The Power Elite</i>."
- "Ibid."

The expected bibliography is also a list, but in the expected order (for instance, ordered alphabetically if that is what the style specifies):

bibliography:
- "Mills, C. W. (1959). <i>The power elite</i>. Oxford University Press. (Original work published 1956)"
- "Piketty, T. (2014). <i>Capital in the Twenty-First Century</i>. Harvard University Press"
- "Thompson, E. P. (1991). <i>The Making of the English working class</i>. Penguin Books. (Original work published 1963)"

several tests in the same file

Alternatively, it is possible to specify a series of tests in the same file. This is especially useful if the tests use the same style with different input or different lang, or different styles with the same input. The tests are given as a list, each test in the list specifying the mentioned variables: style, input, citations and bibliography:

tests:
- style: style1.csl
  input:
  - ThompsonMaking
  citations:
  - "(Thompson)"
- style: style2.csl
  input:
  - MillsPower
  citations:
  - "(Mills, 1959)"

Instead of specifying input and style in the entries in tests, they can be given once at the global level, and each test will reuse these values. For instance, one could test several styles using the same input:

input:
- ThompsonMaking
- MillsPower

tests:
- style: style1.csl
  citations:
  - "(Thompson)"
  - "(Mills)"

- style: style2.csl
  citations:
  - "(Thompson, 1991)"
  - "(Mills, 1959)"

Note that when tests is specified, global definitions of citations and bibliography will be ignored.