DocKnot 1.03

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?

Last spun 2022-02-06 from thread modified 2018-03-19