Refactor and document testing

Makefile

@@ -122,12 +122,12 @@ test-pub-%:
 .PHONY: test-draft-jats test-draft-preprint test-draft-%
 test-draft-jats:
 	$(INARA_TEST_CMD) -o jats example/paper.md
-	diff test/expected-paper.jats/paper.jats example/jats/paper.jats
+	diff test/expected-draft/paper.jats/paper.jats example/jats/paper.jats
 test-draft-preprint: GOLDEN_FILE = paper.preprint.tex
 test-draft-%:        GOLDEN_FILE = paper.$*
 test-draft-%:
 	$(INARA_TEST_CMD) -o $* example/paper.md
-	diff test/expected-$(GOLDEN_FILE) example/$(GOLDEN_FILE)
+	diff test/expected-draft/$(GOLDEN_FILE) example/$(GOLDEN_FILE)
 
 NCBI_FTP = "ftp://ftp.ncbi.nih.gov/pub/jats/publishing/1.2/xsd/"
 test/JATS-Publishing-1-2-MathML2-XSD.zip:
@@ -141,6 +141,6 @@ test/JATS-journalpublishing1.xsd: \
 	rm -rf /tmp/JATS-Publishing-1-2-MathML2-XSD
 
 .PHONY: validate-jats
-validate-jats: test/expected-paper.jats/paper.jats \
+validate-jats: test/expected-draft/paper.jats/paper.jats \
 		test/JATS-journalpublishing1.xsd
 	xmllint --schema test/JATS-journalpublishing1.xsd $< --noout

test/README.md

@@ -0,0 +1,22 @@
+# Testing
+
+Testing in Inara works by checking both the _draft_ mode and
+_production_ mode (i.e., compiled with `-p`) for the following artifacts
+using the `diff` command:
+
+1. JATS XML (`jats`)
+2. Crossref XML (`crossref`)
+3. Preprint LaTeX (`preprint`)
+4. PDF (`pdf`), though note this is a binary comparison
+
+The _draft_ golden standard files are in the [expected-draft](expected-draft) folder while
+the _production_ golden standard files are in the [expected-pub](expected-pub) folder.
+
+## Maintaining the Golden Standard Files
+
+If you make updates to the underlying [paper.md](../example/paper.md) file in the `/examples`
+folder, you'll need to update at minimum the preprint and PDF. If you update the metadata
+in the `paper.md` or make changes to the templates, you might also have to update the JATS
+and Crossref XML files.
+
+**How to update the golden standard files** - TBA