chipsalliance / firrtl-spec

The specification for the FIRRTL language
44 stars 28 forks source link

[nfc] Make LaTeX Warnings Errors #152

Closed seldridge closed 11 months ago

seldridge commented 11 months ago

Switch to latexmk and turn on -Werror.

Example output with this for an undefined reference:

# make
pandoc spec.md --metadata-file spec.yaml --metadata-file=revision-history.yaml --metadata-file=include/common.yaml --pdf-engine=latexmk --pdf-engine-opt=-logfilewarninglist --pdf-engine-opt=-Werror --pdf-engine-opt=-silent --template include/spec-template.tex --syntax-definition include/firrtl.xml --syntax-definition include/ebnf.xml -r markdown+table_captions+inline_code_attributes+gfm_auto_identifiers --filter pandoc-crossref --metadata version:3.2.0-24-ga941e59-dirty -o build/spec.pdf
WARNING: pandoc-crossref was compiled with pandoc 3.1.5 but is being run through 3.1.8. This is not supported. Strange things may (and likely will) happen silently.
Latexmk: ====List of undefined refs and citations:
  Reference `sec:submodule-instancesx' on page 13 undefined on input line 662
----------------------
This message may duplicate earlier message.
Latexmk: Failure in processing file '/private/var/folders/n_/045jp6sd1gj5z6mf6z8x6cyr0000gn/T/tex2pdf.-7d5ec5d82607328c/input.tex':
   Warning(s) from latex (or c.) for '/private/var/folders/n_/045jp6sd1gj5z6mf6z8x6cyr0000gn/T/tex2pdf.-7d5ec5d82607328c/input.tex'; treated as error
----------------------
Latexmk: If appropriate, the -f option can be used to get latexmk
  to try to force complete processing.
Error producing PDF.
This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023/MacPorts 2023.66589_1) (preloaded format=pdflatex 2023.7.19)  14 NOV 2023 15:34
entering extended mode
 restricted \write18 enabled.
 %&-line parsing enabled.
**/private/var/folders/n_/045jp6sd1gj5z6mf6z8x6cyr0000gn/T/tex2pdf.-7d5ec5d8260
7328c/input.tex
...

You annoyingly get the full LaTeX build output at the bottom. The useful part is at the top. If warnings are not treated as errors, then you only get the useful part at the top. We need that non-zero exit code, though.

mmaloney-sf commented 11 months ago

Sounds good to me.