Document citation recipe

kgryte · kgryte · commit cda99c14946e · 2018-01-10T18:40:09.000-08:00
diff --git a/tools/make/lib/bib/README.md b/tools/make/lib/bib/README.md
@@ -12,6 +12,36 @@ This directory contains [`make`][make] recipes for managing the project bibliogr
 
 <!-- /.intro -->
 
+<!-- Usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```text
+Usage: make <command> [<ENV_VAR>=<value> <ENV_VAR>=<value> ...]
+```
+
+### Commands
+
+#### citation-reference
+
+Returns a Markdown formatted reference corresponding to a provided citation identifier.
+
+```bash
+$ make citation-reference CITATION=@marsaglia:2000a
+```
+
+The recipe recognizes the following environment variables:
+
+-   **CITATION**: citation identifier prefixed with an `@` symbol; e.g., `@marsaglia:2000a`.
+-   **CITATION_REFERENCE_DATABASE**: path to a citation reference database.
+-   **CITATION_REFERENCE_CSL**: path to a Citation Style Language (CSL) file.
+
+</section>
+
+<!-- /.usage -->
+
 <!-- Section to include notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
 
 <section class="notes">
diff --git a/tools/make/lib/bib/reference.mk b/tools/make/lib/bib/reference.mk
@@ -10,7 +10,7 @@ CITATION_REFERENCE ?= $(NODE) $(TOOLS_PKGS_DIR)/bib/citation-reference/bin/cli
 # Define the path to a citation reference database:
 CITATION_REFERENCE_DATABASE ?= $(ROOT_DIR)/docs/references/bib.bib
 
-# Define the path to a citation style language (CSL) file:
+# Define the path to a Citation Style Language (CSL) file:
 CITATION_REFERENCE_CSL ?= $(ROOT_DIR)/docs/references/csl/chicago-author-date.csl
 
 # Define the command-line options to be used when executing the command:
