< My friend Stirge | Russ Allbery > Eagle's Path > March 2018 | control-archive 1.8.0 > |
This is the software that I use to generate documentation for my
software. Currently, it just handles README
, README.md
, and
the top-level web page for the package.
This release adds a new metadata file, support/extra
, which
includes information that should be added to the middle of the normal
SUPPORT section of README
and README.md
files. It also adds
an explanatory paragraph about SPDX to the default templates, and adds
SPDX license identifiers to the package itself.
I've spent quite some time looking at good ways of maintaining accurate license metadata for my packages (and for Debian packages I maintain), including writing a truly ugly Perl script that generates a Debian copyright-format 1.0 file from a source tree. (There are multiple versions of this; mine is pickier than any other that I'm aware of.) Rather than trying to solve the free-form comment parsing problem, some form of structured metadata that's broadly adopted feels like the correct engineering solution (putting aside the fact that it will be hard to get everyone to adopt it). The SPDX project is trying to solve this, and although it seems very bureaucratic and the spec is almost unreadable, it does seem to be catching on to a degree.
I'm therefore adopting it in my packages at least to the extent of adding
SPDX-License-Identifier
headers to my source files and using the
SPDX-standard identifiers (which annoyingly differ from the Debian
copyright-format identifiers). I added a test to check that all the files
have these headers and will start adding that to all my packages as I
release them.
I'm still generating the LICENSE
file with my messed-up Perl
script. I want to switch from that to a better script that supports SPDX
and I don't have to maintain, and will take a look at both the SPDX
tooling and cme
when I have a chance.
You can get the latest release from the DocKnot distribution page.
Posted: 2018-03-17 17:42 — Why no comments?
< My friend Stirge | Russ Allbery > Eagle's Path > March 2018 | control-archive 1.8.0 > |