path: root/Changes

                       Revision history for DocKnot

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.