Makefile changes and doc

Makefile: use a FORMAT variable and loops to generate/test multiple expected files. Use a 'regenerate' target rather than the name of the output file. Regenerate target files before creating a release.
README.md: document the regenerate target and FORMAT variable.

Author: jdutant

Makefile

@@ -10,6 +10,11 @@ DIFF = diff
 # Use a POSIX sed with ERE ('v' is specific to GNU sed)
 SED := sed $(shell sed v </dev/null >/dev/null 2>&1 && echo " --posix") -E
 
+# Pandoc formats for test outputs
+ifeq "$(FORMAT)" ""
+FORMAT = native
+endif
+
 # Directory containing the Quarto extension
 QUARTO_EXT_DIR = _extensions/$(FILTER_NAME)
 # The extension's name. Used in the Quarto extension metadata
@@ -41,22 +46,27 @@ help:
 # Test
 #
 
-## Test that running the filter on the sample input yields expected output
+## Test that running the filter on the sample input yields expected outputs
 # The automatic variable `$<` refers to the first dependency
 # (i.e., the filter file).
 # let `test` be a PHONY target so that it is run each time it's called.
 .PHONY: test
 test: $(FILTER_FILE) test/input.md test/test.yaml
-	$(PANDOC) --defaults test/test.yaml | \
-		$(DIFF) test/expected.native -
-
+	@for ext in $(FORMAT) ; do \
+		$(PANDOC) --defaults test/test.yaml --to $$ext | \
+		$(DIFF) test/expected.$$ext - ; \
+	done
 
-## Re-generate the expected output
-# This file **must not** be a dependency of the `test` target, as that
+## Generate the expected output
+# This target **must not** be a dependency of the `test` target, as that
 # would cause it to be regenerated on each run, making the test
 # pointless.
-test/expected.native: $(FILTER_FILE) test/input.md test/test.yaml
-	$(PANDOC) --defaults test/test.yaml --output=$@
+.PHONY: generate
+generate: $(FILTER_FILE) test/input.md test/test.yaml
+	@for ext in $(FORMAT) ; do \
+		$(PANDOC) --defaults test/test.yaml --to $$ext \
+		--output test/expected.$$ext ; \
+	done
 
 #
 # Website
@@ -132,7 +142,7 @@ $(QUARTO_EXT_DIR)/$(FILTER_FILE): $(FILTER_FILE) $(QUARTO_EXT_DIR)
 
 ## Sets a new release (uses VERSION macro if defined)
 .PHONY: release
-release: quarto-extension
+release: quarto-extension regenerate
 	git commit -am "Release $(FILTER_NAME) $(VERSION)"
 	git tag v$(VERSION) -m "$(FILTER_NAME) $(VERSION)"
 	@echo 'Do not forget to push the tag back to github with `git push --tags`'

README.md

@@ -53,6 +53,11 @@ first two steps, everything else is up to you.
    will know what to expect. You may also want to update the URLs
    in the links above to match your repository.
 
+4. [ ] (optional) **Choose default test output formats**. Replace
+   the `FORMAT=native` line in Makefile with your desired default
+   output formats for tests, e.g. `FORMAT=html latex`. These must
+   be possible values of Pandoc's `--to` option.
+
 4. [ ] (optional) **Setup Quarto extension**: This step is
    recommended if you want to make it easy for [Quarto][] users to
    install and use your filter: Quarto expects the filter to be
@@ -82,21 +87,36 @@ targets while keeping the general structure.
 Use the Makefile with `make ...`, where `...` denotes one of the
 targets listed in this section.
 
-#### `test`
+#### `generate`
+
+(Re)generate test output files. This target runs your filter on the
+file `test/input.md` and generates one or more output files
+`test/expected.<FORMAT>` (`native` by default).
+
+Change desired output formats by replacing the Makefile's `FORMAT=...`
+line with e.g. `FORMAT=html docx`. These must be possible values of
+Pandoc's `--to` option.
+
+You can also set `FORMAT` on the command line to regenerate files in
+specific output formats:
 
-Tests the filter. This target runs your filter on file
-`test/input.md` and compares the result with
-`test/expected.native`. The latter file is also a valid make
-target; invoke it to regenerate the expected output.
+```bash
+make regenerate FORMAT=docx
+```
+
+Files are generated using the Pandoc default options given in
+`test/test.yaml`. This file is provided by default but you may want
+to check it into source control and modify it as needed.
+
+#### `test`
 
-You may want to modify this target if your filter is intended for
-a specific output format. E.g., if the filter only works for HTML
-output, you may choose to replace `test/expected.native` with
-`test/expected.html`, and to compare that file instead.
+Tests the filter. This target runs your filter on the file
+`test/input.md` using Pandoc options `test/test.yaml` and compares
+the result with one or more `test/expected.<FORMAT>` files
+(`native` by default).
 
-The test configs are kept in file `test/test.yaml`. The file is
-generated on demand, but you may want to check it into source
-control and modify it as needed.
+See the `regenerate` target on how to change default `FORMAT` values
+or passing it on the command lines.
 
 #### `quarto-extension`
 

test/test.yaml

@@ -1,5 +1,4 @@
 input-files: ["test/input.md"]
-to: native
 standalone: true
 filters:
   - {type: lua, path: greetings.lua}