Revision history for DocKnot
v8.0.1 - 2024-07-14
- Fix formatting of Perl Changes files and possibly other text documents
when formatting multiple documents with App::DocKnot::Spin::Text in the
same process. Some data about the documents had leaked from one
document to the next.
- Add the ".css" suffix to the style specified in *.spin pointers for
Markdown files, matching the behavior of text and pod files.
- Fix conversion of partial style sheet URLs in *.rpod and *.faq pointers
to style sheet names in *.spin files during docknot update-spin.
v8.0.0 - 2024-07-07
- DocKnot now uses semantic versioning for the package and modules, with
a v prefix to work with Perl's packaging system.
- Merge faq2html into this package as App::DocKnot::Spin::Text, and add a
new command, docknot spin-text, which takes roughly the same options as
faq2html. This adds the ability to convert text files in my personal
format into HTML.
- Support *.spin pointers in addition to *.faq pointers for external text
files. *.faq files are deprecated and support will be removed in a
future version of DocKnot.
- Support version numbers prefixed with v in release tarball names, since
this appears to be the convention for Perl modules that use semantic
versions.
- Change the docknot.yaml field orphaned to unmaintained, and change the
templates to say the package is not maintained instead of orphaned.
This terminology is more precise and less metaphorical.
- Remove support information from the README.md and README templates for
packages that are no longer maintained, and adjust some of the wording
there and in the thread template.
- Add missing </address> closing tag in pages rendered from Markdown.
- Fix typo in README.md template for ExtUtils::MakeMaker packages.
- Fix the URL in the footer added by docknot spin to point to DocKnot
instead of my old web tools page.
7.01 - 2022-01-19
- Correctly handle Unicode output from commands run by pointers and from
POD processing by Pod::Thread. Previous versions since 6.01 were
double-encoding. Thanks to Julien ÉLIE for the report.
- Follow symlinks to ordinary files in docknot spin, just not
directories. The Path::Iterator::Rule conversion in 6.01 broke copying
of files referenced by symlink.
- The \size spin always used 1024-based units. It now correctly uses the
KiB, MiB, etc. abbreviations to match.
7.00 - 2022-01-17
- Various module APIs now take Path::Tiny objects instead of string
paths. Roughly, any module API that is not called directly by
App::DocKnot::Command now expects paths in the form of Path::Tiny
objects and does not always do an explicit conversion.
- Fix Unicode handling in App::DocKnot::Spin::Thread methods. Output to
files was handled correctly in most cases, but output to a scalar or to
standard output was not, nor was output to a file when the input was
generated by another program.
- Fix processing of old-style pointers in docknot spin.
- Fix import error when running docknot release.
- Fix .versions updating via docknot release when the package that needs
to be udpated is not the first line of the file.
- When spinning an input tree, process all .rss files first in a separate
pass. This ensurse the output files are seen when spinning the tree
into the output directory.
- Ensure docknot dist always regenerates the *.tar.xz file if necessary,
rather than reusing one left over from a previous build of the same
version.
- Always recreate GnuPG signatures when generating distribution tarballs
in docknot dist.
- When copying distribution files with docknot release, also copy the
modification timestamps of those files.
6.01 - 2022-01-15
- Add new docknot release command and corresponding App::DocKnot::Release
module to copy a tarball releaes (normally created by docknot dist)
into a release area, update symlinks, archive any previous releases,
and update the .versions file used by docknot spin. DocKnot now
depends on Sort::Versions.
- Add new docknot update-spin command and corresponding update_spin
method in App::DocKnot::Update to update a spin input tree to the
latest expectations. Currently, all this does is convert *.rpod
pointer files to *.spin pointer files.
- docknot spin now uses Path::Iterator::Rule and Path::Tiny to construct
its paths, which eliminates the need to change the working directory
while processing input files.
- Fix spurious requirement for a package metadata file when running
docknot spin.
- Don't overwrite output files from docknot generate or generate-all
if the generation fails.
- Require Pod::Thread 3.01 or later.
6.00 - 2021-12-25
- Add a new *.spin input file for docknot spin that points to an external
file with instructions for how to convert it to HTML. Via this
mechanism, support formatting Markdown files as HTML via docknot spin.
This support requires the pandoc program be installed. The path to
pandoc may be specified in the DocKnot global configuration file.
- Support *.spin pointers in addition to *.rpod pointers for external POD
files. The command-line flags used in *.rpod pointers are replaced by
the title and options key of the *.spin file. *.rpod files are
deprecated and support will be removed in a future version of DocKnot.
- Add spin_thread_output method to App::DocKnot::Spin::Thread, intended
to convert thread to HTML as part of a conversion pipeline of a
non-thread input file, while still using sitemap information and
generating the page footer. DocKnot now depends on Path::Tiny.
- Support creating distributions from branches named main rather than
master. The first of main or master that's found in the repository
will be used.
- Move some utility functions into a new App::DocKnot::Util module. This
is primarily intended for internal use by other App::DocKnot modules.
- Fix unintended localization of dates in RSS output, which are supposed
to be RFC 2822 dates and therefore always use English month and day of
week names. Thanks to Slaven Rezić for testing.
- Add load_yaml_file method to App::DocKnot, which loads a YAML file with
schema checking.
- Fix small whitespace problems in thread output.
5.00 - 2021-09-12
- Merge spin and spin-rss into this package, making it a full, if highly
idiosyncratic, static site generator built around a macro language
called thread. This adds new commands docknot spin, docknot spin-rss,
and docknot spin-thread, as well as modules App::DocKnot::Spin and
several submodules. docknot spin should be equivalent to the old spin
command except that \id support has been dropped. DocKnot now depends
on Date::Parse (from TimeDate), Git::Repository, Image::Size, and
Pod::Thread 3.00 or later.
- Support setting distribution.packaging.debian.package along with
distribution.packaging.debian.personal to specify the package name. Do
not generate links to Debian in that case.
- Ignore configure~ when checking distribution tarballs.
- Stop generating a developer link to a to-do list by default in thread
output. Not all of my packages use a TODO file, so the ones that do
should explicitly add this to the developer docs list.
4.01 - 2021-02-27
- DocKnot now supports a global configuration file. The default location
is $HOME/.config/docknot/config.yaml, but it honors the XDG environment
variables. Currently, this configuration file can be used to set the
distribution directory and signing PGP key for docknot dist.
- docknot dist can now optionally sign distribution tarballs with GnuPG
after they have been generated. To request signing, use the --pgp-key
command-line option or set pgp_key in the new global configuration
file.
- The -d option to docknot dist is now optional if distdir is set in
DocKnot's global configuration file.
- Remove the load_appdata_json helper function from App::DocKnot. This
is no longer used now that all DocKnot data is in YAML.
- Properly import Pod::Usage so that docknot --help works.
- Correct the REQUIREMENTS sections of the module documentation to
reflect new dependencies and the removal of a JSON dependency from most
of DocKnot.
- Fix left-over documentation references to the old metatada path.
4.00 - 2020-12-25
- Change the metadata format to a single YAML file, with a slightly
different internal representation, whose default location is
docs/docknot.yaml. The new docknot update command (or the
App::DocKnot::Update module) will convert from the old JSON format.
The new metadata format is checked against a schema when read. DocKnot
now depends on YAML::XS and Kwalify.
- Support a test.override metadata key that overrides the Testing section
in README and README.md files entirely, except for the note about
Lancaster Consensus environment variables.
- Move bootstrap metadata to build.bootstrap, build.lancaster to
test.lancaster, packaging to distribution.packaging, packaging.debian
to distribution.packaging.debian.package, debian to
distribution.packaging.debian, and readme.sections to sections to clean
up some old issues with the schema now that there's an upgrade process.
If readme.sections defined a testing section, move that to
test.override.
- Drop support for the support.cpan metadata key, since the CPAN RT
instance is going away. For packages with support.cpan set, if
vcs.github was set and support.github was not, set support.github to
match vcs.github during a docknot update.
- Drop the current version number from the title of README.md. This is
not a common practice and doesn't seem to add much value.
- Word wrap numeric lists and, in Markdown output, quoted paragraphs.
Previously these preserved the original spacing from the input text
snippets.
- Require paragraphs be indented by at least six spaces, not five, to be
treated as verbatim paragraphs and left unwrapped. (Markdown
paragraphs can still use four spaces because they are wrapped in markup
lines.)
- Add some additional markup to the Markdown version of building
instructions for packages that use Kerberos and Autoconf.
- Use https for the link and badge for unmaintained packages.
3.05 - 2020-08-09
- Change the heuristic for when to refrain from wrapping output
paragraphs to require they start with three short lines rather than
two, ignore the indentation, and increase the threshold for a short
line to 45 characters from 40.
- Force the badge for the Debian version in README.md to point to
unstable rather than stable.
- Depend on JSON::MaybeXS instead of JSON, and List::SomeUtils instead
of List::MoreUtils.
3.04 - 2020-05-16
- Change the vcs.travis metadata key to vcs.status.travis. This will
require changes to all templates and package metadata.json files that
use this key.
- Add support for generating a build status badge from a GitHub Actions
workflow. To do this, set vcs.status.workflow to the name of the
workflow that should be referenced for the badge.
- Also specify DocKnot's dependencies with a cpanfile. This makes it
easier to install its dependencies with some tools, such as cpm.
3.03 - 2020-01-19
- For CPAN packages pushed to GitHub, add a Shields.io license badge to
the Markdown README file.
- For packages with a Debian package, add a Shields.io badge for the
version in Debian.
- docknot dist now uses IO::Uncompress::Gunzip and IO::Compress::Xz to
generate a missing xz tarball rather than running external gzip and xz
programs, which avoids test failures when those programs aren't
available or don't support the expected options. Thanks to Slaven
Rezić for the testing and report. (#131406)
- docknot dist now supports a distribution/ignore metadata setting, which
contains a list of regular expressions of files to ignore when checking
a distribution tarball for completeness.
- Stop leaking exceptions via $@ to the caller of App::DocKnot::Config.
Configuration parsing catches and ignores a variety of errors, which
previously were polluting the caller's $@.
3.02 - 2020-01-08
- Add support for the No Maintenance Intended badge in the Markdown
README file if the package is marked as orphaned.
- If the native distribution generation commands create only a
gzip-compressed tarball, generate an xz-compressed tarball from the
gzip-compressed tarball during docknot dist.
- docknot dist now checks for files present in the source tree but
missing from the distribution, apart from a (currently hard-coded) list
of exceptions.
- docknot dist now removes any existing directory when creating a new
distribution. It overrides permissions if possible while doing this so
that it can clean up from a failed Automake make distcheck, so the
destination directory should be trusted, not one to which an attacker
may be able to write files.
- Remove make warnings from the commands when building a distribution
that supports C++ with the C++ compiler, since my current Autoconf
warning flag discovery code doesn't properly exclude options that are
unsupported by C++.
- Properly skip a test on Windows that requires tar.
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 (intentionally) 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.
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.
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.
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.
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.
1.04 - 2018-03-24
- Fix SPDX test failure on Windows.
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.
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.
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.
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.