User-Visible DocKnot Changes
DocKnot 3.01 (2019-07-14)
docknot dist now also runs make check-cppcheck for Autoconf build
systems.
If the valgrind key is set to true in the package build metadata,
docknot dist now also runs make check-valgrind for Autoconf build
systems.
Allow the path to Perl to be configured in App::DocKnot::Dist. This
is used primarily for testing so that we can try building a
distribution using Module::Build with the same Perl used to run the
test suite. This is exposed by the module API but (intentially) not
exposed on the docknot command line. Thanks, Slaven Rezic. (#129958)
Set user.name and user.email for Git in dist/basic.t test.
Hopefully fix tests on Windows via more correct use of File::Temp
objects: be clear about using the file name instead of the file
descriptor, and delete the file by letting the File::Temp object go
out of scope.
DocKnot 3.00 (2019-06-29)
Separate configuration parsing into a new App::DocKnot::Config module,
used by App::DocKnot::Generate.
Move the entry point for command-line commands from App::DocKnot to
App::DocKnot::Command. The App::DocKnot module now only provides some
helper methods to load application data, used by both
App::DocKnot::Config and App::DocKnot::Generate. It's no longer
necessary to explicitly load App::DocKnot before using one of the
submodules.
Add new docknot dist command and App::DocKnot::Dist module, which runs
appropriate commands to create a distribution tarball. This command
will also run the test suite, with both Clang and GCC for packages
using Autoconf, and will also build and test with C++ if the package
indicates that it supports C++ via the build.cplusplus key in the
package metadata.
Support orphaned warnings in the README and README.md output as well
as thread output.
Add bug tracker links pointing to the CPAN RT installation to the
developer documentation links section of the thread template if
support.cpan is set.
Output more helpful information about test failures on Windows and
other systems that don't have the diff command.
DocKnot 2.00 (2019-01-12)
Move previous docknot command functionality to a new docknot generate
subcommand. All docknot actions in the future will be added as
subcommands.
docknot generate now takes the name of the template as its first
positional argument instead of as the -t option.
generate() and therefore the generate subcommand now defaults to
looking for metadata in docs/metadata, and the -m option is now
optional.
The -o option to docknot generate and the output argument to
generate_output() is now optional if there is a default output file
defined for the template. The two defaults are README for the readme
template and README.md for the readme-md template, both in the current
directory.
Rename App::DocKnot to App:DocKnot::Generate and add a new
generate_output() method that writes the generated output to a
specified file instead of returning it as a string. App::DocKnot must
be loaded as well to use the module API.
Add new generate-all command and generate_all() method that generates
all package documentation files with a default output file.
Separate the TESTING section from BUILD AND INSTALLATION for Perl
modules in both README and README.md, and move the Lancaster
instructions to that section. Add instructions for how to run a
single test with Perl build systems. Test dependencies for Perl
modules should now move into docs/metadata/test/suffix, the same as
for packages with an Autoconf build system.
If build.lancaster is set to true, add the standard section on
Lancaster consensus variables to the end of a TESTING section in
README and README.md even when a custom testing section is provided in
the metadata.
Update to rra-c-util 8.0:
* Fix t/style/strict.t to skip blib and .git directories.
* Update style for the latest perltidy.
DocKnot 1.06 (2018-08-31)
When generating text output, put the footnotes containing URLs for
links immediately following the containing paragraph rather than the
end of the text block. This is both more readable and avoids odd
placement of the footnotes when a template adds further paragraphs to
the end of a text block containing footnotes.
Do not wrap paragraphs in output that seem to be a bunch of short
lines, and add support for broken quotes (multiple short lines, such
as poetry) in quotes in the thread template.
Adjust the README and README.md template to say that make warnings
requires either GCC or Clang, instead of only mentioning GCC.
Adjust the README.md wording for the list information URL when package
releases are announced on a mailing list.
Add support for additional developer documentation links in the thread
output template.
Add support for contributed program documentation links in the thread
output template.
DocKnot 1.05 (2018-05-05)
Add the Travis-CI badge to README.md and a link to Travis-CI to the
thread development links if the vcs.travis key is set in
metadata.json.
Add a Shields.io badge for the CPAN version to README.md and a link to
metacpan.org in the thread output if the distribution.cpan key is set
in metadata.json.
Move the description of Lancaster Consensus environment variables into
the testing section of README and README.md instead of the
requirements section, since they're more about running the tests and
less about package requirements in general.
Add support for a new packaging/extra metadata file (setting the
packaging.extra key in templates) and use it in the thread template.
Correctly handle multi-paragraph debian.summary metadata in the thread
template.
Fix formatting bug in the README template when additional bootstrap
documentation is provided.
DocKnot now requires Perl 5.24 or later.
DocKnot 1.04 (2018-03-24)
Fix SPDX test failure on Windows.
DocKnot 1.03 (2018-03-17)
Add support for a new metadata file, support/extra, that includes
information that should be added into the middle of the normal SUPPORT
section of README and README.md files.
Add a paragraph to the license section of README and README.md saying
that SPDX license identifiers are in use and providing a pointer to
the SPDX license list.
Add SPDX-License-Identifier headers to all substantial source files,
and add a test to check for them.
DocKnot 1.02 (2017-12-31)
Support quoted paragraphs (each line starting with ">") and turn them
into indentation when turning markup into plain text.
Support numbered lists when converting to thread.
Force long, unbreakable lines to be left intact when wrapping.
When wrapping paragraphs, preserve two spaces after periods even when
the period comes before a closing parenthesis or quote mark.
Support test/prefix metadata, which replaces the introduction to the
test instructions.
Add new license text BSD-3-clause-or-GPL-1+ to support pam-krb5.
Support markdown formatting in license texts when converting to
thread to handle the numbered clauses.
Support more complex quote attributions in thread output, and
automatically add \cite[] around work names if they don't contain
double quotes.
Add security advisory support to the thread template.
DocKnot 1.01 (2016-12-25)
Add build and test instructions for Autoconf packages, including
details about Kerberos configuration, to the README and README.md
templates. Allow a testing section in the metadata to override the
added testing section. Add a flag to indicate that the package is not
intended to be installed, which suppresses some of the template.
Add support for license notices (the notices metadata file), which
should be appended to the end of the stock license statement wherever
it is generated.
Add support for stock building and installation sections for Perl
module packages using either Module::Build or ExtUtils::MakeMaker.
Add thread template support for annotating quotes shorter than 80
characters with the "short" class.
Add support for additional bootstrapping requirements in a separate
bootstrap metadata file, appended to the Autotools bootstrapping
section (at least for right now).
Allow markup in the license notices section.
DocKnot 1.00 (2016-10-26)
Initial public release. Supports generating text and Markdown README
files and a thread index page. There is some automation of the
requirements section, but only automation for the build and test
section for Module::Build Perl modules.