Regulatory

A LaTeX package that provides the structures, references and citations a regulatory document is built from.

Installation

A fresh clone holds no package files: everything in tex is generated from the sources in src, so run make generate first.

In order to install this package the texmf tree has to be copied to a directory LaTeX will search in. Consult tlmgr conf texmf TEXMFHOME to get any ideas of where that should be.

If it's favored to keep this tree separate from other LaTeX trees one can add a configuration to /etc/texmf/texmf.d which adds a TEXMF AUX TREE (Debian and derivatives only). This can be useful when you need to change the source and/or push changes with Git.

TEXMFAUXTREES=$HOME/src/regulatory/texmf,

/etc/texmf/texmf.d/01xerdi.cnf

Afterward execute update-texmf with root permissions. It can be validated by the output of: kpsewhich -var-value TEXMFAUXTREES.

Sources

The package is written as a set of .dtx files in the src directory:

Loading regulatory loads the first six modules; each of them can be loaded on its own as well, where regulatory-attachments requires regulatory-ref, which requires regulatory-struct. The seventh, regulatory-md, is pulled in by a hook whenever the markdown package is loaded.

Run make generate to write all of them into the tex directory with docstrip, or make build-docs to generate the package and both manuals.

Translations

Every language has its own definition file src/regulatory-<language>.def, comparable to the fc-<language>.def files of fmtcount. Those are written by hand rather than generated, so a translator never has to open a .dtx file: copy src/regulatory-english.def to src/regulatory-<language>.def, translate the right hand side of every \DeclareTranslation, and make generate puts it next to the package. Dutch and English are complete; German and French carry the designations and the citation register of an act of the Union and not the wording of an internal reference. The manual's Language support chapter says exactly what that costs.

The files are literate all the same – comments in doc's markup, code in macrocode – so they are printed in the language support chapter of the manual.

HTML

tex4ht carries no configuration for this package, so this one ships its own, generated from src/regulatory-html.dtx into tex/regulatory.4ht along with the rest. Without it a conversion with make4ht succeeds and produces a document with no headings and no sections at all; the manual's HTML chapter has the measurements.

Tests

The example documents live in test. The manual lists them, refers to their articles and definitions, and embeds their PDF files as attachments, so make build-docs builds them along the way.

make test runs two suites, both of which need nothing beyond a TeX installation:

make test              # both of the below
make test-engines      # every example through lualatex and pdflatex
make test-engines ENGINES=lualatex
make test-html         # one example through make4ht

The HTML test counts the <section> and <h1>..<h6> elements in the output. Without regulatory.4ht the conversion still succeeds and produces zero of both, so counting them is the only way to see that the configuration was found and applied.

The examples are built against TeX Live plus the tex directory of this project only, so a personal texmf tree cannot make a test pass or fail on its own.

PDF conformance

make conformance builds the same examples once per PDF standard and validates them with veraPDF in Docker (image pinned by digest, so the validator cannot shift the claim under you). No extra example files: the standard is declared on the commandline, and the documents only say \IfDocumentMetadataTF{}{\DocumentMetadata{}}, so a bare build is unaffected.

It writes test/conformance.tex, which is kept in the repository and read by the manual. veraPDF is not on CI, so the verdicts have to travel with the sources; the manual's Tests chapter explains the cases, the standards that are out of reach, and why one case has to fail.

A table in git can go stale, so two checks guard it:

• make conformance-stale compares a hash of the sources the table was made from against the sources as they are. It costs milliseconds – no Docker, no LaTeX, no rebuild.
• make conformance-check rebuilds and revalidates everything and fails on any difference in the verdicts themselves. It takes minutes and needs Docker.

make install-hooks points core.hooksPath at .githooks, whose pre-commit hook runs the cheap one whenever a package source or an example is staged, and tells you to run make conformance when it trips. Regenerating stays a deliberate act: a hook that takes minutes is a hook people disable.

Documentation

The documentation is available in Dutch and English and will be included in every release. See the releases page for the PDF files.

For more information on building all documentation, see Makefile and doc/Makefile in this project.

License

This project is licensed under the LPPL version 1.3c and maintained by Erik Nijenhuis. See LICENSE.txt for more information.