From ddad2fc296bc353265004c5ec3700a7a921888bb Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Tue, 14 Sep 2021 20:30:22 -0700 Subject: Fix localization of RSS dates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- Changes | 6 ++++++ README | 1 + README.md | 1 + docs/docknot.yaml | 1 + lib/App/DocKnot/Command.pm | 12 ++++++------ lib/App/DocKnot/Spin/RSS.pm | 11 +++++++---- t/data/generate/docknot/output/thread | 1 + 7 files changed, 23 insertions(+), 10 deletions(-) diff --git a/Changes b/Changes index bb48b43..948113f 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,11 @@ Revision history for DocKnot +5.01 - Not Released + + - 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. + 5.00 - 2021-09-12 - Merge spin and spin-rss into this package, making it a full, if highly diff --git a/README b/README index 505a714..ba04a75 100644 --- a/README +++ b/README @@ -51,6 +51,7 @@ REQUIREMENTS Perl 5.24 or later and Module::Build are required to build this module. The following additional Perl modules are required to use it: + * Date::Language (part of TimeDate) * Date::Parse (part of TimeDate) * File::BaseDir * File::ShareDir diff --git a/README.md b/README.md index 8be94ad..8d1342e 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ for your own purposes. Perl 5.24 or later and Module::Build are required to build this module. The following additional Perl modules are required to use it: +* Date::Language (part of TimeDate) * Date::Parse (part of TimeDate) * File::BaseDir * File::ShareDir diff --git a/docs/docknot.yaml b/docs/docknot.yaml index bf85a81..12b9eb7 100644 --- a/docs/docknot.yaml +++ b/docs/docknot.yaml @@ -124,6 +124,7 @@ requirements: | Perl 5.24 or later and Module::Build are required to build this module. The following additional Perl modules are required to use it: + * Date::Language (part of TimeDate) * Date::Parse (part of TimeDate) * File::BaseDir * File::ShareDir diff --git a/lib/App/DocKnot/Command.pm b/lib/App/DocKnot/Command.pm index 093d0b5..50da1cc 100644 --- a/lib/App/DocKnot/Command.pm +++ b/lib/App/DocKnot/Command.pm @@ -293,12 +293,12 @@ App::DocKnot::Command - Run DocKnot commands =head1 REQUIREMENTS -Perl 5.24 or later and the modules Date::Parse (part of TimeDate), -File::BaseDir, File::ShareDir, Git::Repository, Image::Size, IO::Compress::Xz -(part of IO-Compress-Lzma), IO::Uncompress::Gunzip (part of IO-Compress), -IPC::Run, IPC::System::Simple, JSON::MaybeXS, Kwalify, List::SomeUtils, -Perl6::Slurp, Template (part of Template Toolkit), and YAML::XS, all of which -are available from CPAN. +Perl 5.24 or later and the modules Date::Language, Date::Parse (both part of +TimeDate), File::BaseDir, File::ShareDir, Git::Repository, Image::Size, +IO::Compress::Xz (part of IO-Compress-Lzma), IO::Uncompress::Gunzip (part of +IO-Compress), IPC::Run, IPC::System::Simple, JSON::MaybeXS, Kwalify, +List::SomeUtils, Perl6::Slurp, Template (part of Template Toolkit), and +YAML::XS, all of which are available from CPAN. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin/RSS.pm b/lib/App/DocKnot/Spin/RSS.pm index 7599426..dff4665 100644 --- a/lib/App/DocKnot/Spin/RSS.pm +++ b/lib/App/DocKnot/Spin/RSS.pm @@ -18,6 +18,7 @@ use warnings; use App::DocKnot; use App::DocKnot::Spin::Thread; use Cwd qw(getcwd); +use Date::Language (); use Date::Parse qw(str2time); use File::Basename qw(fileparse); use Perl6::Slurp qw(slurp); @@ -405,8 +406,9 @@ sub _rss_output { # Determine the current date and latest publication date of all of the # entries, published in the obnoxious format used by RSS. + my $lang = Date::Language->new('English'); my $format = '%a, %d %b %Y %H:%M:%S %z'; - my $now = strftime($format, localtime()); + my $now = $lang->strftime($format, [localtime()]); my $latest = $now; if ($entries_ref->@*) { $latest = strftime($format, localtime($entries_ref->[0]{date})); @@ -439,7 +441,7 @@ EOC # Output each entry, formatting the contents of the entry as we go. for my $entry_ref ($entries_ref->@*) { - my $date = strftime($format, localtime($entry_ref->{date})); + my $date = $lang->strftime($format, [localtime($entry_ref->{date})]); my $title = _escape($entry_ref->{title}); my $description; if ($entry_ref->{description}) { @@ -813,8 +815,9 @@ App::DocKnot::Spin::RSS - Generate RSS and thread from a feed description file =head1 REQUIREMENTS -Perl 5.006 or later and the modules Date::Parse (part of the TimeDate -distribution) and Perl6::Slurp, both of which are available from CPAN. +Perl 5.006 or later and the modules Date::Language, Date::Parse (both part of +the TimeDate distribution), and Perl6::Slurp, both of which are available from +CPAN. =head1 DESCRIPTION diff --git a/t/data/generate/docknot/output/thread b/t/data/generate/docknot/output/thread index f2044cd..6806bbf 100644 --- a/t/data/generate/docknot/output/thread +++ b/t/data/generate/docknot/output/thread @@ -104,6 +104,7 @@ for your own purposes. Perl 5.24 or later and Module::Build are required to build this module. The following additional Perl modules are required to use it: +\bullet(packed)[Date::Language (part of TimeDate)] \bullet(packed)[Date::Parse (part of TimeDate)] \bullet(packed)[File::BaseDir] \bullet(packed)[File::ShareDir] -- cgit v1.2.3 From ce7d21a2aefcf809953ac1d57b429acce90831aa Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Tue, 14 Sep 2021 21:02:58 -0700 Subject: Set locale to C in some tests The generated changes file intentionally uses the localized month name for headings, so set the locale to C in the tests that involve it for reproducible test output. --- t/cli/spin.t | 6 ++++++ t/spin/tree.t | 7 ++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/t/cli/spin.t b/t/cli/spin.t index 434cbb5..674047f 100755 --- a/t/cli/spin.t +++ b/t/cli/spin.t @@ -17,6 +17,7 @@ use Cwd qw(getcwd realpath); use File::Copy::Recursive qw(dircopy); use File::Spec (); use File::Temp (); +use POSIX qw(LC_ALL setlocale); use Test::RRA qw(is_file_contents); use Test::DocKnot::Spin qw(is_spin_output is_spin_output_tree); @@ -25,6 +26,11 @@ use Test::More; # Load the module. BEGIN { use_ok('App::DocKnot::Command') } +# Force the C locale because some of the output intentionally uses localized +# month names and we have to force those to English for comparison of test +# results. +setlocale(LC_ALL, 'C'); + # Create the command-line parser. my $docknot = App::DocKnot::Command->new(); isa_ok($docknot, 'App::DocKnot::Command'); diff --git a/t/spin/tree.t b/t/spin/tree.t index a88d0d0..b3bf302 100755 --- a/t/spin/tree.t +++ b/t/spin/tree.t @@ -18,11 +18,16 @@ use File::Copy::Recursive qw(dircopy); use File::Spec (); use File::Temp (); use Perl6::Slurp qw(slurp); -use POSIX qw(strftime); +use POSIX qw(LC_ALL setlocale strftime); use Test::DocKnot::Spin qw(is_spin_output_tree); use Test::More; +# Force the C locale because some of the output intentionally uses localized +# month names and we have to force those to English for comparison of test +# results. +setlocale(LC_ALL, 'C'); + # Expected output when spinning our tree of input files. my $EXPECTED_OUTPUT = <<'OUTPUT'; Generating thread file .../changes.th -- cgit v1.2.3 From 6da6c2d35ce754452331e2d9ec511b80a30857a9 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 17 Oct 2021 16:16:01 -0700 Subject: Fix stray indentation in thread output The addition of links to the developer section in the thread ouput for a package without separate API documentation was incorrectly indented due to a copy/paste error. Fix this. --- share/templates/thread.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/templates/thread.tmpl b/share/templates/thread.tmpl index d0c5990..7bfd907 100644 --- a/share/templates/thread.tmpl +++ b/share/templates/thread.tmpl @@ -193,7 +193,7 @@ Security advisories: [% END %][% END %] Developer documentation: [% FOREACH doc IN docs.developer %] - \doc[[% doc.name %].html][[% doc.title %]][% END %][% IF vcs.github %] +\doc[[% doc.name %].html][[% doc.title %]][% END %][% IF vcs.github %] \doc[https://github.com/[% vcs.github %]] [GitHub][% END %][% IF support.github %] \doc[https://github.com/[% support.github %]/issues] -- cgit v1.2.3 From 22ff9e7e3bc4c8ae61578888232d5d04719841d7 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 17 Oct 2021 16:19:06 -0700 Subject: Update the pam-krb5 generate test Update to the latest version so that the generation of the to-do link for packages without API documentation is tested. --- t/data/generate/pam-krb5/docknot.yaml | 635 +++++++++++++++--------------- t/data/generate/pam-krb5/output/readme | 61 ++- t/data/generate/pam-krb5/output/readme-md | 67 ++-- t/data/generate/pam-krb5/output/thread | 30 +- 4 files changed, 432 insertions(+), 361 deletions(-) diff --git a/t/data/generate/pam-krb5/docknot.yaml b/t/data/generate/pam-krb5/docknot.yaml index cf4ce0b..2fd2dfd 100644 --- a/t/data/generate/pam-krb5/docknot.yaml +++ b/t/data/generate/pam-krb5/docknot.yaml @@ -1,15 +1,28 @@ +# Package metadata for pam-krb5. +# +# This file contains configuration for DocKnot used to generate +# documentation files (like README.md) and web pages. Other documentation +# in this package is generated automatically from these files as part of +# the release process. For more information, see DocKnot's documentation. +# +# DocKnot is available from . +# +# Copyright 2017, 2020-2021 Russ Allbery +# +# SPDX-License-Identifier: BSD-3-clause or GPL-1+ + format: v1 name: pam-krb5 maintainer: Russ Allbery -version: '4.8' +version: '4.11' synopsis: PAM module for Kerberos authentication license: name: BSD-3-clause-or-GPL-1+ copyrights: - holder: Russ Allbery - years: 2005-2010, 2014-2015, 2017 + years: 2005-2010, 2014-2015, 2017, 2020-2021 - holder: The Board of Trustees of the Leland Stanford Junior University years: 2009-2011 - holder: Andres Salomon @@ -24,25 +37,26 @@ build: kerberos: true manpages: true middle: | - The module will be installed in `/usr/local/lib/security` by default, - except on 64-bit versions of Linux which will use - `/usr/local/lib64/security` to match the default PAM configuration. You - can change the installation locations with the `--prefix`, `--mandir`, and - `--libdir` options to configure. The module will always be installed in a - subdirectory named `security` under the specified libdir. On Linux, use - `--prefix=/usr` to install the man page into `/usr/share/man` and the PAM - module in `/lib/security` or `/lib64/security`. + The module will be installed in `/usr/local/lib/security` by default, but + expect to have to override this using `--libdir`. The correct + installation path for PAM modules varies considerably between systems. + The module will always be installed in a subdirectory named `security` + under the specified value of `--libdir`. On Red Hat Linux, for example, + `--libdir=/usr/lib64` is appropriate to install the module into the system + PAM directory. On Debian's amd64 architecture, + `--libdir=/usr/lib/x86_64-linux-gnu` would be correct. reduced_depends: true type: Autoconf + valgrind: true distribution: packaging: debian: package: libpam-krb5 summary: | Debian packages are available from Debian in Debian 4.0 (etch) and - later releases as libpam-krb5 and libpam-heimdal. The former - packages are built against the MIT Kerberos libraries and the - latter against the Heimdal libraries. + later releases as libpam-krb5 and libpam-heimdal. The former packages + are built against the MIT Kerberos libraries and the latter against + the Heimdal libraries. section: kerberos tarname: pam-krb5 version: pam-krb5 @@ -54,6 +68,8 @@ vcs: browse: https://git.eyrie.org/?p=kerberos/pam-krb5.git github: rra/pam-krb5 openhub: https://www.openhub.net/p/pamkrb5 + status: + workflow: build type: Git url: https://git.eyrie.org/git/kerberos/pam-krb5.git @@ -66,6 +82,9 @@ quote: title: '"Look, ma, no hands!"' work: Salon advisories: + - date: 2020-03-30 + threshold: '4.9' + versions: 4.8 and earlier - date: 2009-02-11 threshold: '3.13' versions: 3.12 and earlier @@ -73,6 +92,9 @@ docs: user: - name: pam-krb5 title: Manual page + developer: + - name: todo + title: To-do list blurb: | pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It @@ -88,33 +110,104 @@ blurb: | description: | pam-krb5 provides a Kerberos PAM module that supports authentication, user ticket cache handling, simple authorization (via .k5login or checking - Kerberos principals against local usernames), and password changing. It - can be configured through either options in the PAM configuration itself - or through entries in the system krb5.conf file, and it tries to work - around PAM implementation flaws in commonly-used PAM-enabled applications - such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent - that the underlying Kerberos libraries support these features. + Kerberos principals against local usernames), and password changing. It can + be configured through either options in the PAM configuration itself or + through entries in the system krb5.conf file, and it tries to work around + PAM implementation flaws in commonly-used PAM-enabled applications such as + OpenSSH and xdm. It supports both PKINIT and FAST to the extent that the + underlying Kerberos libraries support these features. This is not the Kerberos PAM module maintained on Sourceforge and used on Red Hat systems. It is an independent implementation that, if it ever shared any common code, diverged long ago. It supports some features that the Sourceforge module does not (particularly around authorization), and does not support some options (particularly ones not directly related to - Kerberos) that it does. This module will never support Kerberos v4 or - AFS. For an AFS session module that works with this module (or any other - Kerberos PAM module), see + Kerberos) that it does. This module will never support Kerberos v4 or AFS. + For an AFS session module that works with this module (or any other Kerberos + PAM module), see [pam-afs-session](https://www.eyrie.org/~eagle/software/pam-afs-session/). If there are other options besides AFS and Kerberos v4 support from the Sourceforge PAM module that you're missing in this module, please let me know. +requirements: | + Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal are + supported. MIT Keberos 1.3 or later may be required; this module has not + been tested with earlier versions. + + For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later + are required. Earlier MIT Kerberos 1.6 releases have a bug in their + handling of PKINIT options. MIT Kerberos 1.12 or later is required to use + the use_pkinit PAM option. + + For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos + 1.7 or higher is required. For anonymous FAST support, anonymous + authentication (generally anonymous PKINIT) support is required in both the + Kerberos libraries and in the local KDC. + + This module should work on Linux and build with gcc or clang. It may still + work on Solaris and build with the Sun C compiler, but I have only tested it + on Linux recently. There is beta-quality support for the AIX NAS Kerberos + implementation that has not been tested in years. Other PAM implementations + will probably require some porting, although untested build system support + is present for FreeBSD, Mac OS X, and HP-UX. I personally can only test on + Linux and rely on others to report problems on other operating systems. + + Old versions of OpenSSH are known to call `pam_authenticate` followed by + `pam_setcred(PAM_REINITIALIZE_CRED)` without first calling + `pam_open_session`, thereby requesting that an existing ticket cache be + renewed (similar to what a screensaver would want) rather than requesting a + new ticket cache be created. Since this behavior is indistinguishable at + the PAM level from a screensaver, pam-krb5 when used with these old versions + of OpenSSH will refresh the ticket cache of the OpenSSH daemon rather than + setting up a new ticket cache for the user. The resulting ticket cache will + have the correct permissions (this is not a security concern), but will not + be named correctly or referenced in the user's environment and will be + overwritten by the next user login. The best solution to this problem is to + upgrade OpenSSH. I'm not sure exactly when this problem was fixed, but at + the very least OpenSSH 4.3 and later do not exhibit it. + +test: + lancaster: true + prefix: | + pam-krb5 comes with a comprehensive test suite, but it requires some + configuration in order to test anything other than low-level utility + functions. For the full test suite, you will need to have a running KDC + in which you can create two test accounts, one with admin access to the + other. Using a test KDC environment, if you have one, is recommended. + + Follow the instructions in `tests/config/README` to configure the test + suite. + + Now, you can run the test suite with: + suffix: | + The default libkadm5clnt library on the system must match the + implementation of your KDC for the module/expired test to work, since the + two kadmin protocols are not compatible. If you use the MIT library + against a Heimdal server, the test will be skipped; if you use the Heimdal + library against an MIT server, the test suite may hang. + + Several `module/expired` tests are expected to fail with Heimdal 1.5 due + to a bug in Heimdal with reauthenticating immediately after a + library-mediated password change of an expired password. This is fixed in + later releases of Heimdal. + + To run the full test suite, Perl 5.10 or later is required. The following + additional Perl modules will be used if present: + + * Test::Pod + * Test::Spelling + + All are available on CPAN. Those tests will be skipped if the modules are + not available. + sections: - title: Configuring body: | - Just installing the module does not enable it or change anything - about your system authentication configuration. To use the module - for all system authentication on Debian systems, put something like: + Just installing the module does not enable it or change anything about + your system authentication configuration. To use the module for all + system authentication on Debian systems, put something like: ``` auth sufficient pam_krb5.so minimum_uid=1000 @@ -135,42 +228,42 @@ sections: account required pam_unix.so ``` - in `/etc/pam.d/common-account`. The `minimum_uid` setting tells the - PAM module to pass on any users with a UID lower than 1000, thereby - bypassing Kerberos authentication for the root account and any - system accounts. You normally want to do this since otherwise, if - the network is down, the Kerberos authentication can time out and - make it difficult to log in as root and fix matters. This also - avoids problems with Kerberos principals that happen to match system - accounts accidentally getting access to those accounts. + in `/etc/pam.d/common-account`. The `minimum_uid` setting tells the PAM + module to pass on any users with a UID lower than 1000, thereby + bypassing Kerberos authentication for the root account and any system + accounts. You normally want to do this since otherwise, if the network + is down, the Kerberos authentication can time out and make it difficult + to log in as root and fix matters. This also avoids problems with + Kerberos principals that happen to match system accounts accidentally + getting access to those accounts. - Be sure to include the module in the session group as well as the - auth group. Without the session entry, the user's ticket cache will - not be created properly for ssh logins (among possibly others). + Be sure to include the module in the session group as well as the auth + group. Without the session entry, the user's ticket cache will not be + created properly for ssh logins (among possibly others). - If your users should normally all use Kerberos passwords - exclusively, putting something like: + If your users should normally all use Kerberos passwords exclusively, + putting something like: ``` password sufficient pam_krb5.so minimum_uid=1000 password required pam_unix.so try_first_pass obscure md5 ``` - in `/etc/pam.d/common-password` will change users' passwords in - Kerberos by default and then only fall back on Unix if that doesn't - work. (You can make this tighter by using the more complex - new-style PAM configuration.) If you instead want to synchronize - local and Kerberos passwords and change them both at the same time, - you can do something like: + in `/etc/pam.d/common-password` will change users' passwords in Kerberos + by default and then only fall back on Unix if that doesn't work. (You + can make this tighter by using the more complex new-style PAM + configuration.) If you instead want to synchronize local and Kerberos + passwords and change them both at the same time, you can do something + like: ``` password required pam_unix.so obscure sha512 password required pam_krb5.so use_authtok minimum_uid=1000 ``` - If you have multiple environments that you want to synchronize and - you don't want password changes to continue if the Kerberos password - change fails, use the `clear_on_fail` option. For example: + If you have multiple environments that you want to synchronize and you + don't want password changes to continue if the Kerberos password change + fails, use the `clear_on_fail` option. For example: ``` password required pam_krb5.so clear_on_fail minimum_uid=1000 @@ -178,19 +271,19 @@ sections: password required pam_smbpass.so use_authtok ``` - In this case, if `pam_krb5` cannot change the password (due to - password strength rules on the KDC, for example), it will clear the - stored password (because of the `clear_on_fail` option), and since - `pam_unix` and `pam_smbpass` are both configured with `use_authtok`, - they will both fail. `clear_on_fail` is not the default because it - would interfere with the more common pattern of falling back to - local passwords if the user doesn't exist in Kerberos. + In this case, if `pam_krb5` cannot change the password (due to password + strength rules on the KDC, for example), it will clear the stored + password (because of the `clear_on_fail` option), and since `pam_unix` + and `pam_smbpass` are both configured with `use_authtok`, they will both + fail. `clear_on_fail` is not the default because it would interfere + with the more common pattern of falling back to local passwords if the + user doesn't exist in Kerberos. - If you use a more complex configuration with the Linux PAM `[]` - syntax for the session and account groups, note that `pam_krb5` - returns a status of ignore, not success, if the user didn't log on - with Kerberos. You may need to handle that explicitly with - `ignore=ignore` in your action list. + If you use a more complex configuration with the Linux PAM `[]` syntax + for the session and account groups, note that `pam_krb5` returns a + status of ignore, not success, if the user didn't log on with Kerberos. + You may need to handle that explicitly with `ignore=ignore` in your + action list. There are many, many other possibilities. See the Linux PAM documentation for all the configuration options. @@ -200,19 +293,17 @@ sections: You can also use pam-krb5 only for specific services. In that case, modify the files in `/etc/pam.d` for that particular service to use - `pam_krb5.so` for authentication. For services that are using - passwords over TLS to authenticate users, you may want to use the - `ignore_k5login` and `no_ccache` options to the authenticate module. - `.k5login` authorization is only meaningful for local accounts and - ticket caches are usually (although not always) only useful for - interactive sessions. - - Configuring the module for Solaris is both simpler and less - flexible, since Solaris (at least Solaris 8 and 9, which are the - last versions of Solaris with which this module was extensively - tested) use a single `/etc/pam.conf` file that contains - configuration for all programs. For console login on Solaris, try - something like: + `pam_krb5.so` for authentication. For services that are using passwords + over TLS to authenticate users, you may want to use the `ignore_k5login` + and `no_ccache` options to the authenticate module. `.k5login` + authorization is only meaningful for local accounts and ticket caches + are usually (although not always) only useful for interactive sessions. + + Configuring the module for Solaris is both simpler and less flexible, + since Solaris (at least Solaris 8 and 9, which are the last versions of + Solaris with which this module was extensively tested) use a single + `/etc/pam.conf` file that contains configuration for all programs. For + console login on Solaris, try something like: ``` login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100 @@ -223,70 +314,66 @@ sections: login session required /usr/lib/security/pam_unix_session.so.1 ``` - A similar configuration could be used for other services, such as - ssh. See the pam.conf(5) man page for more information. When using - this module with Solaris login (at least on Solaris 8 and 9), you - will probably also need to add `retain_after_close` to the PAM - configuration to avoid having the user's credentials deleted before - they are logged in. - - The Solaris Kerberos library reportedly does not support prompting - for a password change of an expired account during authentication. - Supporting password change for expired accounts on Solaris with - native Kerberos may therefore require setting the `defer_pwchange` - or `force_pwchange` option for selected login applications. See the - description and warnings about that option in the pam_krb5(5) man - page. - - Some configuration options may be put in the `krb5.conf` file used - by your Kerberos libraries (usually `/etc/krb5.conf` or + A similar configuration could be used for other services, such as ssh. + See the pam.conf(5) man page for more information. When using this + module with Solaris login (at least on Solaris 8 and 9), you will + probably also need to add `retain_after_close` to the PAM configuration + to avoid having the user's credentials deleted before they are logged + in. + + The Solaris Kerberos library reportedly does not support prompting for a + password change of an expired account during authentication. Supporting + password change for expired accounts on Solaris with native Kerberos may + therefore require setting the `defer_pwchange` or `force_pwchange` + option for selected login applications. See the description and + warnings about that option in the pam_krb5(5) man page. + + Some configuration options may be put in the `krb5.conf` file used by + your Kerberos libraries (usually `/etc/krb5.conf` or `/usr/local/etc/krb5.conf`) instead or in addition to the PAM configuration. See the man page for more details. - The Kerberos library, via pam-krb5, will prompt the user to change - their password if their password is expired, but when using OpenSSH, - this will only work when `ChallengeResponseAuthentication` is - enabled. Unless this option is enabled, OpenSSH doesn't pass PAM - messages to the user and can only respond to a simple password - prompt. - - If you are using MIT Kerberos, be aware that users whose passwords - are expired will not be prompted to change their password unless the - KDC configuration for your realm in `[realms]` in `krb5.conf` - contains a `master_kdc` setting or, if using DNS SRV records, you - have a DNS entry for `_kerberos-master` as well as `_kerberos`. + The Kerberos library, via pam-krb5, will prompt the user to change their + password if their password is expired, but when using OpenSSH, this will + only work when `ChallengeResponseAuthentication` is enabled. Unless + this option is enabled, OpenSSH doesn't pass PAM messages to the user + and can only respond to a simple password prompt. + + If you are using MIT Kerberos, be aware that users whose passwords are + expired will not be prompted to change their password unless the KDC + configuration for your realm in `[realms]` in `krb5.conf` contains a + `master_kdc` setting or, if using DNS SRV records, you have a DNS entry + for `_kerberos-master` as well as `_kerberos`. - title: Debugging body: | - The first step when debugging any problems with this module is to - add `debug` to the PAM options for the module (either in the PAM - configuration or in `krb5.conf`). This will significantly increase - the logging from the module and should provide a trace of exactly - what failed and any available error information. - - Many Kerberos authentication problems are due to configuration - issues in `krb5.conf`. If pam-krb5 doesn't work, first check that - `kinit` works on the same system. That will test your basic - Kerberos configuration. If the system has a keytab file installed - that's readable by the process doing authentication via PAM, make - sure that the keytab is current and contains a key for - `host/` where is the fully-qualified hostname. - pam-krb5 prevents KDC spoofing by checking the user's credentials - when possible, but this means that if a keytab is present it must be - correct or authentication will fail. You can check the keytab with - `klist -k` and `kinit -k`. - - Be sure that all libraries and modules, including PAM modules, - loaded by a program use the same Kerberos libraries. Sometimes - programs that use PAM, such as current versions of OpenSSH, also - link against Kerberos directly. If your sshd is linked against one - set of Kerberos libraries and pam-krb5 is linked against a different - set of Kerberos libraries, this will often cause problems (such as - segmentation faults, bus errors, assertions, or other strange - behavior). Similar issues apply to the com_err library or any other - library used by both modules and shared libraries and by the - application that loads them. If your OS ships Kerberos libraries, - it's usually best if possible to build all Kerberos software on the - system against those libraries. + The first step when debugging any problems with this module is to add + `debug` to the PAM options for the module (either in the PAM + configuration or in `krb5.conf`). This will significantly increase the + logging from the module and should provide a trace of exactly what + failed and any available error information. + + Many Kerberos authentication problems are due to configuration issues in + `krb5.conf`. If pam-krb5 doesn't work, first check that `kinit` works + on the same system. That will test your basic Kerberos configuration. + If the system has a keytab file installed that's readable by the process + doing authentication via PAM, make sure that the keytab is current and + contains a key for `host/` where is the fully-qualified + hostname. pam-krb5 prevents KDC spoofing by checking the user's + credentials when possible, but this means that if a keytab is present it + must be correct or authentication will fail. You can check the keytab + with `klist -k` and `kinit -k`. + + Be sure that all libraries and modules, including PAM modules, loaded by + a program use the same Kerberos libraries. Sometimes programs that use + PAM, such as current versions of OpenSSH, also link against Kerberos + directly. If your sshd is linked against one set of Kerberos libraries + and pam-krb5 is linked against a different set of Kerberos libraries, + this will often cause problems (such as segmentation faults, bus errors, + assertions, or other strange behavior). Similar issues apply to the + com_err library or any other library used by both modules and shared + libraries and by the application that loads them. If your OS ships + Kerberos libraries, it's usually best if possible to build all Kerberos + software on the system against those libraries. - title: Implementation Notes body: | The normal sequence of actions taken for a user login is: @@ -304,60 +391,56 @@ sections: pam_close_session ``` - followed by closing the open PAM session. The corresponding - `pam_sm_*` functions in this module are called when an application - calls those public interface functions. Not all applications call - all of those functions, or in particularly that order, although - `pam_authenticate` is always first and has to be. - - When `pam_authenticate` is called, pam-krb5 creates a temporary - ticket cache in `/tmp` and sets the PAM environment variable - `PAM_KRB5CCNAME` to point to it. This ticket cache will be - automatically destroyed when the PAM session is closed and is there - only to pass the initial credentials to the call to `pam_setcred`. - The module would use a memory cache, but memory caches will only - work if the application preserves the PAM environment between the - calls to `pam_authenticate` and `pam_setcred`. Most do, but OpenSSH - notoriously does not and calls `pam_authenticate` in a subprocess, - so this method is used to pass the tickets to the `pam_setcred` call - in a different process. - - `pam_authenticate` does a complete authentication, including - checking the resulting TGT by obtaining a service ticket for the - local host if possible, but this requires read access to the system - keytab. If the keytab doesn't exist, can't be read, or doesn't - include the appropriate credentials, the default is to accept the - authentication. This can be controlled by setting - `verify_ap_req_nofail` to true in `[libdefaults]` in - `/etc/krb5.conf`. `pam_authenticate` also does a basic - authorization check, by default calling `krb5_kuserok` (which uses - `~/.k5login` if available and falls back to checking that the - principal corresponds to the account name). This can be customized - with several options documented in the pam_krb5(5) man page. - - pam-krb5 treats `pam_open_session` and - `pam_setcred(PAM_ESTABLISH_CRED)` as synonymous, as some - applications call one and some call the other. Both copy the - initial credentials from the temporary cache into a permanent cache - for this session and set `KRB5CCNAME` in the environment. It will - remember when the credential cache has been established and then - avoid doing any duplicate work afterwards, since some applications - call `pam_setcred` or `pam_open_session` multiple times (most - notably X.Org 7 and earlier xdm, which also throws away the module - settings the last time it calls them). + followed by closing the open PAM session. The corresponding `pam_sm_*` + functions in this module are called when an application calls those + public interface functions. Not all applications call all of those + functions, or in particularly that order, although `pam_authenticate` is + always first and has to be. + + When `pam_authenticate` is called, pam-krb5 creates a temporary ticket + cache in `/tmp` and sets the PAM environment variable `PAM_KRB5CCNAME` + to point to it. This ticket cache will be automatically destroyed when + the PAM session is closed and is there only to pass the initial + credentials to the call to `pam_setcred`. The module would use a memory + cache, but memory caches will only work if the application preserves the + PAM environment between the calls to `pam_authenticate` and + `pam_setcred`. Most do, but OpenSSH notoriously does not and calls + `pam_authenticate` in a subprocess, so this method is used to pass the + tickets to the `pam_setcred` call in a different process. + + `pam_authenticate` does a complete authentication, including checking + the resulting TGT by obtaining a service ticket for the local host if + possible, but this requires read access to the system keytab. If the + keytab doesn't exist, can't be read, or doesn't include the appropriate + credentials, the default is to accept the authentication. This can be + controlled by setting `verify_ap_req_nofail` to true in `[libdefaults]` + in `/etc/krb5.conf`. `pam_authenticate` also does a basic authorization + check, by default calling `krb5_kuserok` (which uses `~/.k5login` if + available and falls back to checking that the principal corresponds to + the account name). This can be customized with several options + documented in the pam_krb5(5) man page. + + pam-krb5 treats `pam_open_session` and `pam_setcred(PAM_ESTABLISH_CRED)` + as synonymous, as some applications call one and some call the other. + Both copy the initial credentials from the temporary cache into a + permanent cache for this session and set `KRB5CCNAME` in the + environment. It will remember when the credential cache has been + established and then avoid doing any duplicate work afterwards, since + some applications call `pam_setcred` or `pam_open_session` multiple + times (most notably X.Org 7 and earlier xdm, which also throws away the + module settings the last time it calls them). `pam_acct_mgmt` finds the ticket cache, reads it in to obtain the - authenticated principal, and then does is another authorization - check against `.k5login` or the local account name as described - above. + authenticated principal, and then does is another authorization check + against `.k5login` or the local account name as described above. - After the call to `pam_setcred` or `pam_open_session`, the ticket - cache will be destroyed whenever the calling application either - destroys the PAM environment or calls `pam_close_session`, which it - should do on user logout. + After the call to `pam_setcred` or `pam_open_session`, the ticket cache + will be destroyed whenever the calling application either destroys the + PAM environment or calls `pam_close_session`, which it should do on user + logout. - The normal sequence of events when refreshing a ticket cache (such - as inside a screensaver) is: + The normal sequence of events when refreshing a ticket cache (such as + inside a screensaver) is: ``` pam_authenticate @@ -365,36 +448,36 @@ sections: pam_acct_mgmt ``` - (`PAM_REFRESH_CRED` may be used instead.) Authentication proceeds - as above. At the `pam_setcred` stage, rather than creating a new - ticket cache, the module instead finds the current ticket cache - (from the `KRB5CCNAME` environment variable or the default ticket - cache location from the Kerberos library) and then reinitializes it - with the credentials from the temporary `pam_authenticate` ticket - cache. When refreshing a ticket cache, the application should not - open a session. Calling `pam_acct_mgmt` is optional; pam-krb5 - doesn't do anything different when it's called in this case. - - If `pam_authenticate` apparently didn't succeed, or if an account - was configured to be ignored via `ignore_root` or `minimum_uid`, + (`PAM_REFRESH_CRED` may be used instead.) Authentication proceeds as + above. At the `pam_setcred` stage, rather than creating a new ticket + cache, the module instead finds the current ticket cache (from the + `KRB5CCNAME` environment variable or the default ticket cache location + from the Kerberos library) and then reinitializes it with the + credentials from the temporary `pam_authenticate` ticket cache. When + refreshing a ticket cache, the application should not open a session. + Calling `pam_acct_mgmt` is optional; pam-krb5 doesn't do anything + different when it's called in this case. + + If `pam_authenticate` apparently didn't succeed, or if an account was + configured to be ignored via `ignore_root` or `minimum_uid`, `pam_setcred` (and therefore `pam_open_session`) and `pam_acct_mgmt` - return `PAM_IGNORE`, which tells the PAM library to proceed as if - that module wasn't listed in the PAM configuration at all. - `pam_authenticate`, however, returns failure in the ignored user - case by default, since otherwise a configuration using `ignore_root` - with pam-krb5 as the only PAM module would allow anyone to log in as - root without a password. There doesn't appear to be a case where - returning `PAM_IGNORE` instead would improve the module's behavior, - but if you know of a case, please let me know. + return `PAM_IGNORE`, which tells the PAM library to proceed as if that + module wasn't listed in the PAM configuration at all. + `pam_authenticate`, however, returns failure in the ignored user case by + default, since otherwise a configuration using `ignore_root` with + pam-krb5 as the only PAM module would allow anyone to log in as root + without a password. There doesn't appear to be a case where returning + `PAM_IGNORE` instead would improve the module's behavior, but if you + know of a case, please let me know. By default, `pam_authenticate` intentionally does not follow the PAM - standard for handling expired accounts and instead returns failure - from `pam_authenticate` unless the Kerberos libraries are able to - change the account password during authentication. Too many - applications either do not call `pam_acct_mgmt` or ignore its exit - status. The fully correct PAM behavior (returning success from - `pam_authenticate` and `PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) - can be enabled with the `defer_pwchange` option. + standard for handling expired accounts and instead returns failure from + `pam_authenticate` unless the Kerberos libraries are able to change the + account password during authentication. Too many applications either do + not call `pam_acct_mgmt` or ignore its exit status. The fully correct + PAM behavior (returning success from `pam_authenticate` and + `PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) can be enabled with the + `defer_pwchange` option. The `defer_pwchange` option is unfortunately somewhat tricky to implement. In this case, the calling sequence is: @@ -410,124 +493,62 @@ sections: During the first `pam_authenticate`, we can't obtain credentials and therefore a ticket cache since the password is expired. But `pam_authenticate` isn't called again after `pam_chauthtok`, so - `pam_chauthtok` has to create a ticket cache. We however don't want - it to do this for the normal password change (`passwd`) case. + `pam_chauthtok` has to create a ticket cache. We however don't want it + to do this for the normal password change (`passwd`) case. What we do is set a flag in our PAM data structure saying that we're processing an expired password, and `pam_chauthtok`, if it sees that - flag, redoes the authentication with password prompting disabled - after it finishes changing the password. - - Unfortunately, when handling password changes this way, - `pam_chauthtok` will always have to prompt the user for their - current password again even though they just typed it. This is - because the saved authentication tokens are cleared after - `pam_authenticate` returns, for security reasons. We could hack - around this by saving the password in our PAM data structure, but - this would let the application gain access to it (exactly what the - clearing is intended to prevent) and breaks a PAM library guarantee. - We could also work around this by having `pam_authenticate` get the - `kadmin/changepw` authenticator in the expired password case and - store it for `pam_chauthtok`, but it doesn't seem worth the hassle. + flag, redoes the authentication with password prompting disabled after + it finishes changing the password. + + Unfortunately, when handling password changes this way, `pam_chauthtok` + will always have to prompt the user for their current password again + even though they just typed it. This is because the saved + authentication tokens are cleared after `pam_authenticate` returns, for + security reasons. We could hack around this by saving the password in + our PAM data structure, but this would let the application gain access + to it (exactly what the clearing is intended to prevent) and breaks a + PAM library guarantee. We could also work around this by having + `pam_authenticate` get the `kadmin/changepw` authenticator in the + expired password case and store it for `pam_chauthtok`, but it doesn't + seem worth the hassle. - title: History and Acknowledgements body: | Originally written by Frank Cusack , with the following acknowledgement: > Thanks to Naomaru Itoi , Curtis King - > , and Derrick Brashear , - > all of whom have written and made available Kerberos 4/5 modules. + > , and Derrick Brashear , all + > of whom have written and made available Kerberos 4/5 modules. > Although no code in this module is directly from these author's > modules, (except the get_user_info() routine in support.c; derived - > from whichever of these authors originally wrote the first module - > the other 2 copied from), it was extremely helpful to look over - > their code which aided in my design. + > from whichever of these authors originally wrote the first module the + > other 2 copied from), it was extremely helpful to look over their code + > which aided in my design. The module was then patched for the FreeBSD ports collection with - additional modifications by unknown maintainers and then was - modified by Joel Kociolek to be usable with - Debian GNU/Linux. - - It was packaged by Sam Hartman as the Kerberos v5 PAM module for - Debian and improved and modified by him and later by Russ Allbery to - fix bugs and add additional features. It was then adopted by Andres - Salomon, who added support for refreshing credentials. - - The current distribution is maintained by Russ Allbery, who also - added support for reading configuration from `krb5.conf`, added many - features for compatibility with the Sourceforge module, commented - and standardized the formatting of the code, and overhauled the + additional modifications by unknown maintainers and then was modified by + Joel Kociolek to be usable with Debian GNU/Linux. + + It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian + and improved and modified by him and later by Russ Allbery to fix bugs + and add additional features. It was then adopted by Andres Salomon, who + added support for refreshing credentials. + + The current distribution is maintained by Russ Allbery, who also added + support for reading configuration from `krb5.conf`, added many features + for compatibility with the Sourceforge module, commented and + standardized the formatting of the code, and overhauled the documentation. Thanks to Douglas E. Engert for the initial implementation of PKINIT - support. I have since modified and reworked it extensively, so any - bugs or compilation problems are my fault. + support. I have since modified and reworked it extensively, so any bugs + or compilation problems are my fault. - Thanks to Markus Moeller for lots of debugging and multiple patches - and suggestions for improved portability. + Thanks to Markus Moeller for lots of debugging and multiple patches and + suggestions for improved portability. Thanks to Booker Bense for the implementation of the `alt_auth_map` option. Thanks to Sam Hartman for the FAST support implementation. - -requirements: | - Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal - are supported. MIT Keberos 1.3 or later may be required; this module has - not been tested with earlier versions. - - For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later - are required. Earlier MIT Kerberos 1.6 releases have a bug in their - handling of PKINIT options. - - For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos - 1.7 or higher is required. For anonymous FAST support, anonymous - authentication (generally anonymous PKINIT) support is required in both - the Kerberos libraries and in the local KDC. - - This module should work on Linux and Solaris (and build with gcc, clang, - or the Sun C compiler), but has been far more heavily tested on Linux. - There is beta-quality support for the AIX NAS Kerberos implementation. - Other PAM implementations will probably require some porting, although - untested build system support is present for FreeBSD, Mac OS X, and HP-UX. - I personally can only test on Linux and rely on others to report problems - on other operating systems. - - Old versions of OpenSSH are known to call `pam_authenticate` followed by - `pam_setcred(PAM_REINITIALIZE_CRED)` without first calling - `pam_open_session`, thereby requesting that an existing ticket cache be - renewed (similar to what a screensaver would want) rather than requesting - a new ticket cache be created. Since this behavior is indistinguishable - at the PAM level from a screensaver, pam-krb5 when used with these old - versions of OpenSSH will refresh the ticket cache of the OpenSSH daemon - rather than setting up a new ticket cache for the user. The resulting - ticket cache will have the correct permissions (this is not a security - concern), but will not be named correctly or referenced in the user's - environment and will be overwritten by the next user login. The best - solution to this problem is to upgrade OpenSSH. I'm not sure exactly when - this problem was fixed, but at the very least OpenSSH 4.3 and later do not - exhibit it. - -test: - prefix: | - pam-krb5 comes with a comprehensive test suite, but it requires some - configuration in order to test anything other than low-level utility - functions. For the full test suite, you will need to have a running KDC - in which you can create two test accounts, one with admin access to the - other. Using a test KDC environment, if you have one, is recommended. - - Follow the instructions in `tests/config/README` to configure the test - suite. - - Now, you can run the test suite with: - suffix: | - The default libkadm5clnt library on the system must match the - implementation of your KDC for the module/expired test to work, since the - two kadmin protocols are not compatible. If you use the MIT library - against a Heimdal server, the test will be skipped; if you use the Heimdal - library against an MIT server, the test suite may hang. - - Several `module/expired` tests are expected to fail with Heimdal 1.5 due - to a bug in Heimdal with reauthenticating immediately after a - library-mediated password change of an expired password. This is fixed in - later releases of Heimdal. diff --git a/t/data/generate/pam-krb5/output/readme b/t/data/generate/pam-krb5/output/readme index 5d6e7a0..3b7cb5c 100644 --- a/t/data/generate/pam-krb5/output/readme +++ b/t/data/generate/pam-krb5/output/readme @@ -1,13 +1,13 @@ - pam-krb5 4.8 + pam-krb5 4.11 (PAM module for Kerberos authentication) Maintained by Russ Allbery - Copyright 2005-2010, 2014-2015, 2017 Russ Allbery . - Copyright 2009-2011 The Board of Trustees of the Leland Stanford Junior - University. Copyright 2005 Andres Salomon . - Copyright 1999-2000 Frank Cusack . This software - is distributed under a BSD-style license. Please see the section - LICENSE below for more information. + Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery + . Copyright 2009-2011 The Board of Trustees of the + Leland Stanford Junior University. Copyright 2005 Andres Salomon + . Copyright 1999-2000 Frank Cusack + . This software is distributed under a BSD-style + license. Please see the section LICENSE below for more information. BLURB @@ -56,17 +56,19 @@ REQUIREMENTS For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later are required. Earlier MIT Kerberos 1.6 releases have a bug in - their handling of PKINIT options. + their handling of PKINIT options. MIT Kerberos 1.12 or later is + required to use the use_pkinit PAM option. For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos 1.7 or higher is required. For anonymous FAST support, anonymous authentication (generally anonymous PKINIT) support is required in both the Kerberos libraries and in the local KDC. - This module should work on Linux and Solaris (and build with gcc, clang, - or the Sun C compiler), but has been far more heavily tested on Linux. - There is beta-quality support for the AIX NAS Kerberos implementation. - Other PAM implementations will probably require some porting, although + This module should work on Linux and build with gcc or clang. It may + still work on Solaris and build with the Sun C compiler, but I have only + tested it on Linux recently. There is beta-quality support for the AIX + NAS Kerberos implementation that has not been tested in years. Other + PAM implementations will probably require some porting, although untested build system support is present for FreeBSD, Mac OS X, and HP-UX. I personally can only test on Linux and rely on others to report problems on other operating systems. @@ -107,14 +109,14 @@ BUILDING AND INSTALLATION directory is also supported, if you wish, by creating an empty directory and then running configure with the correct relative path. - The module will be installed in /usr/local/lib/security by default, - except on 64-bit versions of Linux which will use - /usr/local/lib64/security to match the default PAM configuration. You - can change the installation locations with the --prefix, --mandir, and - --libdir options to configure. The module will always be installed in a - subdirectory named security under the specified libdir. On Linux, use - --prefix=/usr to install the man page into /usr/share/man and the PAM - module in /lib/security or /lib64/security. + The module will be installed in /usr/local/lib/security by default, but + expect to have to override this using --libdir. The correct + installation path for PAM modules varies considerably between systems. + The module will always be installed in a subdirectory named security + under the specified value of --libdir. On Red Hat Linux, for example, + --libdir=/usr/lib64 is appropriate to install the module into the system + PAM directory. On Debian's amd64 architecture, + --libdir=/usr/lib/x86_64-linux-gnu would be correct. Normally, configure will use krb5-config to determine the flags to use to compile with your Kerberos libraries. To specify a particular @@ -197,6 +199,22 @@ TESTING library-mediated password change of an expired password. This is fixed in later releases of Heimdal. + To run the full test suite, Perl 5.10 or later is required. The + following additional Perl modules will be used if present: + + * Test::Pod + * Test::Spelling + + All are available on CPAN. Those tests will be skipped if the modules + are not available. + + To enable tests that don't detect functionality problems but are used to + sanity-check the release, set the environment variable RELEASE_TESTING + to a true value. To enable tests that may be sensitive to the local + environment or that produce a lot of false positives without uncovering + many problems, set the environment variable AUTHOR_TESTING to a true + value. + CONFIGURING Just installing the module does not enable it or change anything about @@ -566,7 +584,8 @@ LICENSE The pam-krb5 package as a whole is covered by the following copyright statement and license: - Copyright 2005-2010, 2014-2015, 2017 Russ Allbery + Copyright 2005-2010, 2014-2015, 2017, 2020-2021 + Russ Allbery Copyright 2009-2011 The Board of Trustees of the Leland Stanford Junior University Copyright 2005 Andres Salomon diff --git a/t/data/generate/pam-krb5/output/readme-md b/t/data/generate/pam-krb5/output/readme-md index 9834f04..e74b675 100644 --- a/t/data/generate/pam-krb5/output/readme-md +++ b/t/data/generate/pam-krb5/output/readme-md @@ -1,14 +1,17 @@ # pam-krb5 +[![Build +status](https://github.com/rra/pam-krb5/workflows/build/badge.svg)](https://github.com/rra/pam-krb5/actions) [![Debian package](https://img.shields.io/debian/v/libpam-krb5/unstable)](https://tracker.debian.org/pkg/libpam-krb5) -Copyright 2005-2010, 2014-2015, 2017 Russ Allbery . -Copyright 2009-2011 The Board of Trustees of the Leland Stanford Junior -University. Copyright 2005 Andres Salomon . -Copyright 1999-2000 Frank Cusack . This software is -distributed under a BSD-style license. Please see the section -[License](#license) below for more information. +Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery +. Copyright 2009-2011 The Board of Trustees of the +Leland Stanford Junior University. Copyright 2005 Andres Salomon +. Copyright 1999-2000 Frank Cusack +. This software is distributed under a BSD-style +license. Please see the section [License](#license) below for more +information. ## Blurb @@ -55,20 +58,22 @@ not been tested with earlier versions. For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later are required. Earlier MIT Kerberos 1.6 releases have a bug in their -handling of PKINIT options. +handling of PKINIT options. MIT Kerberos 1.12 or later is required to use +the use_pkinit PAM option. For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos 1.7 or higher is required. For anonymous FAST support, anonymous authentication (generally anonymous PKINIT) support is required in both the Kerberos libraries and in the local KDC. -This module should work on Linux and Solaris (and build with gcc, clang, -or the Sun C compiler), but has been far more heavily tested on Linux. -There is beta-quality support for the AIX NAS Kerberos implementation. -Other PAM implementations will probably require some porting, although -untested build system support is present for FreeBSD, Mac OS X, and HP-UX. -I personally can only test on Linux and rely on others to report problems -on other operating systems. +This module should work on Linux and build with gcc or clang. It may +still work on Solaris and build with the Sun C compiler, but I have only +tested it on Linux recently. There is beta-quality support for the AIX +NAS Kerberos implementation that has not been tested in years. Other PAM +implementations will probably require some porting, although untested +build system support is present for FreeBSD, Mac OS X, and HP-UX. I +personally can only test on Linux and rely on others to report problems on +other operating systems. Old versions of OpenSSH are known to call `pam_authenticate` followed by `pam_setcred(PAM_REINITIALIZE_CRED)` without first calling @@ -108,14 +113,14 @@ probably have to be done as root. Building outside of the source directory is also supported, if you wish, by creating an empty directory and then running configure with the correct relative path. -The module will be installed in `/usr/local/lib/security` by default, -except on 64-bit versions of Linux which will use -`/usr/local/lib64/security` to match the default PAM configuration. You -can change the installation locations with the `--prefix`, `--mandir`, and -`--libdir` options to configure. The module will always be installed in a -subdirectory named `security` under the specified libdir. On Linux, use -`--prefix=/usr` to install the man page into `/usr/share/man` and the PAM -module in `/lib/security` or `/lib64/security`. +The module will be installed in `/usr/local/lib/security` by default, but +expect to have to override this using `--libdir`. The correct +installation path for PAM modules varies considerably between systems. +The module will always be installed in a subdirectory named `security` +under the specified value of `--libdir`. On Red Hat Linux, for example, +`--libdir=/usr/lib64` is appropriate to install the module into the system +PAM directory. On Debian's amd64 architecture, +`--libdir=/usr/lib/x86_64-linux-gnu` would be correct. Normally, configure will use `krb5-config` to determine the flags to use to compile with your Kerberos libraries. To specify a particular @@ -208,6 +213,22 @@ to a bug in Heimdal with reauthenticating immediately after a library-mediated password change of an expired password. This is fixed in later releases of Heimdal. +To run the full test suite, Perl 5.10 or later is required. The following +additional Perl modules will be used if present: + +* Test::Pod +* Test::Spelling + +All are available on CPAN. Those tests will be skipped if the modules are +not available. + +To enable tests that don't detect functionality problems but are used to +sanity-check the release, set the environment variable `RELEASE_TESTING` +to a true value. To enable tests that may be sensitive to the local +environment or that produce a lot of false positives without uncovering +many problems, set the environment variable `AUTHOR_TESTING` to a true +value. + ## Configuring Just installing the module does not enable it or change anything about @@ -586,7 +607,7 @@ requests are gratefully reviewed and normally accepted. The pam-krb5 package as a whole is covered by the following copyright statement and license: -> Copyright 2005-2010, 2014-2015, 2017 +> Copyright 2005-2010, 2014-2015, 2017, 2020-2021 > Russ Allbery > > Copyright 2009-2011 diff --git a/t/data/generate/pam-krb5/output/thread b/t/data/generate/pam-krb5/output/thread index e8ac73e..6554083 100644 --- a/t/data/generate/pam-krb5/output/thread +++ b/t/data/generate/pam-krb5/output/thread @@ -48,11 +48,15 @@ \h2[Security Advisories] + \link[security/2020-03-30.html] + [2020-03-30]: pam-krb5 4.8 and earlier\break + \link[security/2009-02-11.html] [2009-02-11]: pam-krb5 3.12 and earlier\break \h2[Development] + \link[todo.html][To-do list] \break \link[https://github.com/rra/pam-krb5] [GitHub] \break \link[https://github.com/rra/pam-krb5/issues] @@ -110,20 +114,22 @@ not been tested with earlier versions. For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later are required. Earlier MIT Kerberos 1.6 releases have a bug in their -handling of PKINIT options. +handling of PKINIT options. MIT Kerberos 1.12 or later is required to use +the use_pkinit PAM option. For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos 1.7 or higher is required. For anonymous FAST support, anonymous authentication (generally anonymous PKINIT) support is required in both the Kerberos libraries and in the local KDC. -This module should work on Linux and Solaris (and build with gcc, clang, -or the Sun C compiler), but has been far more heavily tested on Linux. -There is beta-quality support for the AIX NAS Kerberos implementation. -Other PAM implementations will probably require some porting, although -untested build system support is present for FreeBSD, Mac OS X, and HP-UX. -I personally can only test on Linux and rely on others to report problems -on other operating systems. +This module should work on Linux and build with gcc or clang. It may +still work on Solaris and build with the Sun C compiler, but I have only +tested it on Linux recently. There is beta-quality support for the AIX +NAS Kerberos implementation that has not been tested in years. Other PAM +implementations will probably require some porting, although untested +build system support is present for FreeBSD, Mac OS X, and HP-UX. I +personally can only test on Linux and rely on others to report problems on +other operating systems. Old versions of OpenSSH are known to call \code[pam_authenticate] followed by \code[pam_setcred(PAM_REINITIALIZE_CRED)] without first calling @@ -158,7 +164,7 @@ The distribution: An \link[https://archives.eyrie.org/software/ARCHIVE/pam-krb5/] [archive of older releases] is also available. \class(alert)[Versions older than -3.13 have known security vulnerabilities and should not be used.] +4.9 have known security vulnerabilities and should not be used.] Debian packages are available from Debian in Debian 4.0 (etch) and later releases as libpam-krb5 and libpam-heimdal. The former packages are built @@ -188,11 +194,15 @@ User documentation: Security advisories: +\doc[security/2020-03-30.html] + [2020-03-30: 4.8 and earlier] + \doc[security/2009-02-11.html] [2009-02-11: 3.12 and earlier] Developer documentation: +\doc[todo.html][To-do list] \doc[https://github.com/rra/pam-krb5] [GitHub] \doc[https://github.com/rra/pam-krb5/issues] @@ -207,7 +217,7 @@ license: \block[ - Copyright 2005-2010, 2014-2015, 2017 + Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery Copyright 2009-2011 -- cgit v1.2.3 From 3722a15cf5b2325d8ef8fc914c6b744c3a9e4192 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 17 Oct 2021 16:24:16 -0700 Subject: Fix blank lines between security advisories The new pam-krb5 test revealed a whitespace problem causing blank lines to be introduced between security advisories in the sidebar. Avoid that with more careful templating. --- Changes | 2 ++ share/templates/thread.tmpl | 8 ++++---- t/data/generate/pam-krb5/output/thread | 6 ++---- t/data/generate/remctl/output/thread | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Changes b/Changes index 948113f..c31715d 100644 --- a/Changes +++ b/Changes @@ -6,6 +6,8 @@ to be RFC 2822 dates and therefore always use English month and day of week names. Thanks to Slaven Rezić for testing. + - 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 diff --git a/share/templates/thread.tmpl b/share/templates/thread.tmpl index 7bfd907..cffeb18 100644 --- a/share/templates/thread.tmpl +++ b/share/templates/thread.tmpl @@ -47,8 +47,8 @@ \h2[Security Advisories] [% FOREACH advisory IN advisories %] \link[security/[% advisory.date %].html] - [[% advisory.date %]]: [% name %] [% advisory.versions %]\break -[% END %][% END %] + [[% advisory.date %]]: [% name %] [% advisory.versions %] \break[% END %] +[% END %] \h2[Development] [% FOREACH doc IN docs.developer %] \link[[% doc.name %].html][[% doc.title %]] \break[% END %][% IF vcs.github %] @@ -189,8 +189,8 @@ User documentation: Security advisories: [% FOREACH advisory IN advisories %] \doc[security/[% advisory.date %].html] - [[% advisory.date %]: [% advisory.versions %]] -[% END %][% END %] + [[% advisory.date %]: [% advisory.versions %]][% END %] +[% END %] Developer documentation: [% FOREACH doc IN docs.developer %] \doc[[% doc.name %].html][[% doc.title %]][% END %][% IF vcs.github %] diff --git a/t/data/generate/pam-krb5/output/thread b/t/data/generate/pam-krb5/output/thread index 6554083..a370131 100644 --- a/t/data/generate/pam-krb5/output/thread +++ b/t/data/generate/pam-krb5/output/thread @@ -49,10 +49,9 @@ \h2[Security Advisories] \link[security/2020-03-30.html] - [2020-03-30]: pam-krb5 4.8 and earlier\break - + [2020-03-30]: pam-krb5 4.8 and earlier \break \link[security/2009-02-11.html] - [2009-02-11]: pam-krb5 3.12 and earlier\break + [2009-02-11]: pam-krb5 3.12 and earlier \break \h2[Development] @@ -196,7 +195,6 @@ Security advisories: \doc[security/2020-03-30.html] [2020-03-30: 4.8 and earlier] - \doc[security/2009-02-11.html] [2009-02-11: 3.12 and earlier] diff --git a/t/data/generate/remctl/output/thread b/t/data/generate/remctl/output/thread index 615ed8f..3ecd5f8 100644 --- a/t/data/generate/remctl/output/thread +++ b/t/data/generate/remctl/output/thread @@ -54,7 +54,7 @@ \h2[Security Advisories] \link[security/2018-04-01.html] - [2018-04-01]: remctl 3.12 and 3.13\break + [2018-04-01]: remctl 3.12 and 3.13 \break \h2[Development] -- cgit v1.2.3 From 4aab7cb9631a8abedb5675baef772a65cb3539e8 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 17 Oct 2021 19:21:17 -0700 Subject: Support distribution from a main branch 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. Use Git::Repository for creating distributions and testing the distribution code rather than hand-rolling git invocations. --- Changes | 4 ++++ lib/App/DocKnot/Dist.pm | 29 +++++++++++++++++++---------- t/dist/basic.t | 45 +++++++++++++++++++-------------------------- 3 files changed, 42 insertions(+), 36 deletions(-) diff --git a/Changes b/Changes index c31715d..a82f801 100644 --- a/Changes +++ b/Changes @@ -2,6 +2,10 @@ 5.01 - Not Released + - 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. + - 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. diff --git a/lib/App/DocKnot/Dist.pm b/lib/App/DocKnot/Dist.pm index 1db9b13..4caa9b5 100644 --- a/lib/App/DocKnot/Dist.pm +++ b/lib/App/DocKnot/Dist.pm @@ -23,12 +23,13 @@ use Cwd qw(getcwd); use File::Copy qw(move); use File::Find qw(find); use File::Path qw(remove_tree); +use Git::Repository (); use IO::Compress::Xz (); use IO::Uncompress::Gunzip (); use IPC::Run qw(run); use IPC::System::Simple qw(systemx); use List::SomeUtils qw(lastval); -use List::Util qw(any); +use List::Util qw(any first); # Base commands to run for various types of distributions. Additional # variations may be added depending on additional configuration parameters. @@ -390,13 +391,19 @@ sub make_distribution { } # Export the Git repository into a new directory. - my @git = ( - 'git', 'archive', - "--remote=$source", "--prefix=${prefix}/", - 'master', + my $repo = Git::Repository->new(work_tree => $source); + my @branches = $repo->run( + 'for-each-ref' => '--format=%(refname:short)', 'refs/heads/', ); - my @tar = qw(tar xf -); - run(\@git, q{|}, \@tar) or die "@git | @tar failed with status $?\n"; + my $head = first { $_ eq 'main' || $_ eq 'master' } @branches; + my $archive = $repo->command(archive => "--prefix=${prefix}/", $head); + run([qw(tar xf -)], '<', $archive->stdout) + or die "git archive | tar xf - failed with status $?\n"; + $archive->close(); + + if ($archive->exit != 0) { + die 'git archive failed with status ' . $archive->exit . "\n"; + } # Change to that directory and run the configured commands. chdir($prefix); @@ -461,9 +468,9 @@ App::DocKnot::Dist - Prepare a distribution tarball =head1 REQUIREMENTS Git, Perl 5.24 or later, and the modules File::BaseDir, File::ShareDir, -IO::Compress::Xz (part of IO-Compress-Lzma), IO::Uncompress::Gunzip (part of -IO-Compress), IPC::Run, IPC::System::Simple, Kwalify, List::SomeUtils, and -YAML::XS, all of which are available from CPAN. +Git::Repository, IO::Compress::Xz (part of IO-Compress-Lzma), +IO::Uncompress::Gunzip (part of IO-Compress), IPC::Run, IPC::System::Simple, +Kwalify, List::SomeUtils, and YAML::XS, all of which are available from CPAN. The tools to build whatever type of software distribution is being prepared are also required, since the distribution is built and tested as part of @@ -557,6 +564,8 @@ an implementation detail of make_distribution(). =item make_distribution() Generate distribution tarballs in the C directory provided to new(). +The distribution will be generated from the first branch found named either +C
or C. If C already contains a subdirectory whose name matches the C of the distribution, it will be forcibly removed. In order to diff --git a/t/dist/basic.t b/t/dist/basic.t index 95a6986..f8ca97b 100755 --- a/t/dist/basic.t +++ b/t/dist/basic.t @@ -17,6 +17,7 @@ use Cwd qw(getcwd); use File::Copy::Recursive qw(dircopy); use File::Spec; use File::Temp; +use Git::Repository; use IPC::Run qw(run); use IPC::System::Simple qw(capturex systemx); @@ -36,44 +37,36 @@ my $dir = File::Temp->newdir(); my $sourcedir = File::Spec->catfile($dir, 'source'); my $distdir = File::Spec->catfile($dir, 'dist'); -# Check whether git is available and can be used to initialize a repository. -eval { - systemx( - 'git', 'init', '-b', 'master', '-q', - File::Spec->catfile($dir, 'source'), - ); -}; -if ($@) { - plan skip_all => 'git init failed (possibly no git binary)'; -} - -# Copy all files from the data directory, and commit them. We have to rename -# the test while we copy it to avoid having it picked up by the main package -# test suite. +# Create a new repository, copy all files from the data directory, and commit +# them. We have to rename the test while we copy it to avoid having it picked +# up by the main package test suite. dircopy($dataroot, $sourcedir) or die "$0: cannot copy $dataroot to $sourcedir: $!\n"; my $testpath = File::Spec->catfile($sourcedir, 't', 'api', 'empty.t'); rename($testpath . '.in', $testpath); -chdir($sourcedir); -systemx(qw(git config --add user.name Test)); -systemx(qw(git config --add user.email test@example.com)); -systemx(qw(git add -A .)); -systemx(qw(git commit -q -m Initial)); +Git::Repository->run(init => '-b', 'main', { cwd => $sourcedir, quiet => 1 }); +my $repo = Git::Repository->new(work_tree => $sourcedir); +$repo->run(config => '--add', 'user.name', 'Test'); +$repo->run(config => '--add', 'user.email', 'test@example.com'); +$repo->run(add => '-A', q{.}); +$repo->run(commit => '-q', '-m', 'Initial commit'); # Check whether we have all the necessary tools to run the test. -my $out; -my $result - = eval { run(['git', 'archive', 'HEAD'], q{|}, ['tar', 'tf', q{-}], \$out) }; +my $result; +eval { + my $archive = $repo->command(archive => 'HEAD'); + my $out; + $result = run([qw(tar tf -)], '<', $archive->stdout, '>', \$out); + $archive->close(); + $result &&= $archive->exit == 0; +}; if ($@ || !$result) { - chdir($cwd); plan skip_all => 'git and tar not available'; } else { plan tests => 20; } -# Load the module. Change back to the starting directory for this so that -# coverage analysis works. -chdir($cwd); +# Load the module now that we're sure we can run tests. require_ok('App::DocKnot::Dist'); # Put some existing files in the directory that are marked read-only. These -- cgit v1.2.3 From 3bc6eae68d8206f232fc9835450e793758a8ea8c Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 17 Oct 2021 19:29:57 -0700 Subject: Fix tests with git without -b flag Don't require that git support a -b flag when running the dist/basic.t test. --- t/dist/basic.t | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/t/dist/basic.t b/t/dist/basic.t index f8ca97b..319b5cb 100755 --- a/t/dist/basic.t +++ b/t/dist/basic.t @@ -44,7 +44,7 @@ dircopy($dataroot, $sourcedir) or die "$0: cannot copy $dataroot to $sourcedir: $!\n"; my $testpath = File::Spec->catfile($sourcedir, 't', 'api', 'empty.t'); rename($testpath . '.in', $testpath); -Git::Repository->run(init => '-b', 'main', { cwd => $sourcedir, quiet => 1 }); +Git::Repository->run('init', { cwd => $sourcedir, quiet => 1 }); my $repo = Git::Repository->new(work_tree => $sourcedir); $repo->run(config => '--add', 'user.name', 'Test'); $repo->run(config => '--add', 'user.email', 'test@example.com'); -- cgit v1.2.3 From 8312775b24d2b126b4a6a9de0d293844b18eda3a Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 19 Dec 2021 16:02:45 -0800 Subject: Fix App::DocKnot::Spin::Thread examples Update the examples in the documentation to match the current API. --- lib/App/DocKnot/Spin/Thread.pm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 492666d..46fa7ba 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -1502,7 +1502,7 @@ App::DocKnot::Spin::Thread - Generate HTML from the macro language thread use App::DocKnot::Spin::Thread; my $thread = App::DocKnot::Spin::Thread->new(); - $thread->spin_file('/path/to/file.th', '/path/to/file.html'); + my $output = $thread->spin_thread($input); use App::DocKnot::Spin::Sitemap; use App::DocKnot::Spin::Versions; @@ -1515,7 +1515,7 @@ App::DocKnot::Spin::Thread - Generate HTML from the macro language thread sitemap => $sitemap, versions => $versions, }); - $thread->spin_file('/input/file.th', '/output/file.th'); + $thread->spin_thread_file('/input/file.th', '/output/file.html'); =head1 REQUIREMENTS -- cgit v1.2.3 From 3f8cd16b8469c577c582efcc78861b37a9484a50 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 19 Dec 2021 20:35:42 -0800 Subject: Fix App::DocKnot::Spin::Thread synopsis The code in the synopsis used an undefined variable. --- lib/App/DocKnot/Spin/Thread.pm | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 46fa7ba..2523d8d 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -1501,6 +1501,7 @@ App::DocKnot::Spin::Thread - Generate HTML from the macro language thread use App::DocKnot::Spin::Thread; + my $input = 'some thread'; my $thread = App::DocKnot::Spin::Thread->new(); my $output = $thread->spin_thread($input); -- cgit v1.2.3 From d26471ced74e5017f77bdfce1db876389137618a Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 19 Dec 2021 20:37:03 -0800 Subject: Add load_yaml_file to App::DocKnot Add load_yaml_file method to App::DocKnot, which loads a YAML file with schema checking. --- Changes | 3 ++ lib/App/DocKnot.pm | 45 ++++++++++++++++++++-- lib/App/DocKnot/Config.pm | 39 +------------------ .../output/software/docknot/api/app-docknot.html | 12 +++++- 4 files changed, 57 insertions(+), 42 deletions(-) diff --git a/Changes b/Changes index a82f801..05eeb0a 100644 --- a/Changes +++ b/Changes @@ -10,6 +10,9 @@ 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 diff --git a/lib/App/DocKnot.pm b/lib/App/DocKnot.pm index 7a9101f..e7d5b65 100644 --- a/lib/App/DocKnot.pm +++ b/lib/App/DocKnot.pm @@ -20,6 +20,8 @@ use warnings; use File::BaseDir qw(config_files); use File::ShareDir qw(module_file); use File::Spec; +use Kwalify qw(validate); +use YAML::XS (); ############################################################################## # Helper methods @@ -53,6 +55,36 @@ sub appdata_path { return $path; } +# Load a YAML file with schema checking. +# +# $path - Path to the YAML file to load +# $schema - Name of the schema file against which to check it +# +# Returns: Contents of the file as a hash +# Throws: YAML::XS exception on invalid file +# Text exception on schema mismatch +sub load_yaml_file { + my ($self, $path, $schema) = @_; + + # Tell YAML::XS to use real booleans. Otherwise, Kwalify is unhappy with + # data elements set to false. + local $YAML::XS::Boolean = 'JSON::PP'; + + # Load the metadata and check it against the schema. + my $data_ref = YAML::XS::LoadFile($path); + my $schema_path = $self->appdata_path('schema', $schema . '.yaml'); + my $schema_ref = YAML::XS::LoadFile($schema_path); + eval { validate($schema_ref, $data_ref) }; + if ($@) { + my $errors = $@; + chomp($errors); + die "schema validation for $path failed:\n$errors\n"; + } + + # Return the verified contents. + return $data_ref; +} + ############################################################################## # Module return value and documentation ############################################################################## @@ -62,7 +94,7 @@ __END__ =for stopwords Allbery DocKnot docknot MERCHANTABILITY NONINFRINGEMENT sublicense -submodules +submodules Kwalify =head1 NAME @@ -70,8 +102,8 @@ App::DocKnot - Documentation and software release management =head1 REQUIREMENTS -Perl 5.24 or later and the modules File::BaseDir and File::ShareDir, both of -which are available from CPAN. +Perl 5.24 or later and the modules File::BaseDir, File::ShareDir, Kwalify, and +YAML::XS, all of which are available from CPAN. =head1 DESCRIPTION @@ -96,6 +128,13 @@ overridden by the user via files in F<$HOME/.config/docknot> or F (or whatever $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS are set to). Raises a text exception if the desired file could not be located. +=item load_yaml_file(PATH, SCHEMA) + +Load a YAML file with schema checking. PATH is the path to the file. +SCHEMA is the name of the schema, which will be loaded from the F +directory using appdata_path(). See the description of that method for the +paths that are searched. + =back =head1 AUTHOR diff --git a/lib/App/DocKnot/Config.pm b/lib/App/DocKnot/Config.pm index f67b489..f4a118b 100644 --- a/lib/App/DocKnot/Config.pm +++ b/lib/App/DocKnot/Config.pm @@ -18,43 +18,8 @@ use warnings; use Carp qw(croak); use File::BaseDir qw(config_files); -use Kwalify qw(validate); use YAML::XS (); -############################################################################## -# Helper methods -############################################################################## - -# Load a YAML file with schema checking. -# -# $path - Path to the YAML file to load -# $schema - Name of the schema file against which to check it -# -# Returns: Contents of the file as a hash -# Throws: YAML::XS exception on invalid file -# Text exception on schema mismatch -sub _load_yaml_file { - my ($self, $path, $schema) = @_; - - # Tell YAML::XS to use real booleans. Otherwise, Kwalify is unhappy with - # data elements set to false. - local $YAML::XS::Boolean = 'JSON::PP'; - - # Load the metadata and check it against the schema. - my $data_ref = YAML::XS::LoadFile($path); - my $schema_path = $self->appdata_path('schema', $schema); - my $schema_ref = YAML::XS::LoadFile($schema_path); - eval { validate($schema_ref, $data_ref) }; - if ($@) { - my $errors = $@; - chomp($errors); - die "schema validation for $path failed:\n$errors\n"; - } - - # Return the verified contents. - return $data_ref; -} - ############################################################################## # Public Interface ############################################################################## @@ -92,7 +57,7 @@ sub config { my ($self) = @_; # Load the package metadata. - my $data_ref = $self->_load_yaml_file($self->{metadata}, 'docknot.yaml'); + my $data_ref = $self->load_yaml_file($self->{metadata}, 'docknot'); # build.install defaults to true. if (!exists($data_ref->{build}{install})) { @@ -136,7 +101,7 @@ sub global_config { if (!defined($config_path)) { return {}; } - my $data_ref = $self->_load_yaml_file($config_path, 'config.yaml'); + my $data_ref = $self->load_yaml_file($config_path, 'config'); # Return the resulting configuration. return $data_ref; diff --git a/t/data/spin/output/software/docknot/api/app-docknot.html b/t/data/spin/output/software/docknot/api/app-docknot.html index 5076e73..ea3d829 100644 --- a/t/data/spin/output/software/docknot/api/app-docknot.html +++ b/t/data/spin/output/software/docknot/api/app-docknot.html @@ -45,8 +45,8 @@

REQUIREMENTS

-Perl 5.24 or later and the modules File::BaseDir and File::ShareDir, both of -which are available from CPAN. +Perl 5.24 or later and the modules File::BaseDir, File::ShareDir, Kwalify, and +YAML::XS, all of which are available from CPAN.

DESCRIPTION

@@ -77,6 +77,14 @@ overridden by the user via files in $HOME/.config/docknot or /etc/xdg/docknot (or whatever $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS are set to). Raises a text exception if the desired file could not be located.

+ +
load_yaml_file(PATH, SCHEMA)
+

+Load a YAML file with schema checking. PATH is the path to the file. +SCHEMA is the name of the schema, which will be loaded from the schema +directory using appdata_path(). See the description of that method for the +paths that are searched. +

AUTHOR

-- cgit v1.2.3 From 75c60cbc6a3c81f1991fac42966e13fa3cc77b51 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 23 Dec 2021 16:25:43 -0800 Subject: Add *.spin pointers and Markdown support 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. Remove an extra blank line after the leading navbar in output converted from thread. --- .github/workflows/build.yaml | 2 + Changes | 8 +- lib/App/DocKnot/Spin.pm | 20 +- lib/App/DocKnot/Spin/Pointer.pm | 379 +++++++++++++++++++++ lib/App/DocKnot/Spin/Sitemap.pm | 1 - lib/App/DocKnot/Spin/Thread.pm | 8 +- share/schema/config.yaml | 2 + share/schema/pointer.yaml | 20 ++ share/templates/html.tmpl | 22 ++ t/data/spin/markdown/input/.sitemap | 4 + t/data/spin/markdown/input/other.spin | 3 + t/data/spin/markdown/input/test.spin | 3 + t/data/spin/markdown/output/other.html | 42 +++ t/data/spin/markdown/output/test.html | 42 +++ t/data/spin/markdown/test.md | 9 + .../output/software/docknot/api/app-docknot.html | 1 - t/data/spin/output/software/docknot/index.html | 1 - t/data/spin/output/software/index.html | 1 - t/data/spin/output/usefor/index.html | 1 - t/lib/Test/DocKnot/Spin.pm | 2 +- t/spin/markdown.t | 56 +++ t/spin/sitemap.t | 1 - t/style/coverage.t | 5 +- 23 files changed, 618 insertions(+), 15 deletions(-) create mode 100644 lib/App/DocKnot/Spin/Pointer.pm create mode 100644 share/schema/pointer.yaml create mode 100644 share/templates/html.tmpl create mode 100644 t/data/spin/markdown/input/.sitemap create mode 100644 t/data/spin/markdown/input/other.spin create mode 100644 t/data/spin/markdown/input/test.spin create mode 100644 t/data/spin/markdown/output/other.html create mode 100644 t/data/spin/markdown/output/test.html create mode 100644 t/data/spin/markdown/test.md create mode 100755 t/spin/markdown.t diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 935056e..85b7dfa 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -36,6 +36,8 @@ jobs: steps: - uses: actions/checkout@v2 + - name: Install pandoc + run: apt-get -y --no-install-recommends install pandoc - uses: perl-actions/install-with-cpm@v1.4 with: cpanfile: "cpanfile" diff --git a/Changes b/Changes index 05eeb0a..9d14a27 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,12 @@ Revision history for DocKnot -5.01 - Not Released +6.00 - Not Released + + - 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 creating distributions from branches named main rather than master. The first of main or master that's found in the repository diff --git a/lib/App/DocKnot/Spin.pm b/lib/App/DocKnot/Spin.pm index 655aa64..27b57e0 100644 --- a/lib/App/DocKnot/Spin.pm +++ b/lib/App/DocKnot/Spin.pm @@ -17,6 +17,7 @@ use 5.024; use autodie; use warnings; +use App::DocKnot::Spin::Pointer; use App::DocKnot::Spin::RSS; use App::DocKnot::Spin::Sitemap; use App::DocKnot::Spin::Thread; @@ -116,7 +117,7 @@ sub _footer { if ($self->{sitemap} && $self->{output}) { my $page = $out_path; $page =~ s{ \A \Q$self->{output}\E }{}xms; - $output .= join(q{}, $self->{sitemap}->navbar($page)); + $output .= join(q{}, $self->{sitemap}->navbar($page)) . "\n"; } # Figure out the modification dates. Use the RCS/CVS Id if available, @@ -427,6 +428,14 @@ sub _process_file { if (-e $rss_path) { $self->{rss}->generate($rss_path, $file); } + } elsif ($file =~ m{ [.] spin \z }xms) { + $output =~ s{ [.] spin \z }{.html}xms; + $shortout =~ s{ [.] spin \z }{.html}xms; + $self->{generated}{$output} = 1; + if ($self->{pointer}->is_out_of_date($input, $output)) { + _print_checked("Converting $shortout\n"); + $self->{pointer}->spin_pointer($input, $output); + } } elsif ($file =~ m{ [.] th \z }xms) { $output =~ s{ [.] th \z }{.html}xms; $shortout =~ s{ [.] th \z }{.html}xms; @@ -594,6 +603,15 @@ sub spin { }, ); + # Create the processor for pointers. + $self->{pointer} = App::DocKnot::Spin::Pointer->new( + { + output => $output, + sitemap => $self->{sitemap}, + 'style-url' => $self->{style_url}, + }, + ); + # Process the input tree. find( { diff --git a/lib/App/DocKnot/Spin/Pointer.pm b/lib/App/DocKnot/Spin/Pointer.pm new file mode 100644 index 0000000..969660f --- /dev/null +++ b/lib/App/DocKnot/Spin/Pointer.pm @@ -0,0 +1,379 @@ +# Generate HTML from a pointer to an external file. +# +# The input tree for spin may contain pointers to external files in various +# formats. This module parses those pointer files and performs the conversion +# of those external files into HTML. +# +# SPDX-License-Identifier: MIT + +############################################################################## +# Modules and declarations +############################################################################## + +package App::DocKnot::Spin::Pointer 5.00; + +use 5.024; +use autodie; +use parent qw(App::DocKnot); +use warnings; + +use App::DocKnot::Config; +use Carp qw(croak); +use Encode qw(decode encode); +use File::BaseDir qw(config_files); +use IPC::System::Simple qw(capturex); +use Kwalify qw(validate); +use POSIX qw(strftime); +use Template (); +use YAML::XS (); + +# The URL to the software page for all of my web page generation software, +# used to embed a link to the software that generated the page. +my $URL = 'https://www.eyrie.org/~eagle/software/web/'; + +############################################################################## +# Utility functions +############################################################################## + +# Check if a file, which may not exist, is newer than another list of files. +# +# $file - File whose timestamp to compare +# @others - Other files to compare against +# +# Returns: True if $file exists and is newer than @others, false otherwise +sub _is_newer { + my ($file, @others) = @_; + return if !-e $file; + my $file_mtime = (stat($file))[9]; + my @others_mtimes = map { (stat)[9] } @others; + return all { $file_mtime >= $_ } @others_mtimes; +} + +# print with error checking and an explicit file handle. autodie +# unfortunately can't help us because print can't be prototyped and hence +# can't be overridden. +# +# $fh - Output file handle +# $file - File name for error reporting +# @args - Remaining arguments to print +# +# Returns: undef +# Throws: Text exception on output failure +sub _print_fh { + my ($fh, $file, @args) = @_; + print {$fh} @args or croak("cannot write to $file: $!"); + return; +} + +############################################################################## +# Format conversions +############################################################################## + +# Convert a Markdown file to HTML. +# +# $data_ref - Data from the pointer file +# path - Path to the Markdown file to convert +# $output - Path to the output file +# +# Throws: Text exception on conversion failure +sub _spin_markdown { + my ($self, $data_ref, $output) = @_; + my $source = $data_ref->{path}; + + # Do the Markdown conversion using pandoc. + my $html = capturex( + $self->{pandoc_path}, '--wrap=preserve', '-f', 'markdown', + '-t', 'html', $source, + ); + + # Pull the title out of the contents of the

header if not set. + my $title = $data_ref->{title}; + if (!defined($title)) { + ($title) = $html =~ m{

]+ > (.*?)

}xms; + } + + # Construct the template variables. + my ($links, $navbar, $style); + if ($self->{sitemap}) { + my $page = $output; + $page =~ s{ \A \Q$self->{output}\E }{}xms; + my @links = $self->{sitemap}->links($page); + if (@links) { + $links = join(q{}, @links); + } + my @navbar = $self->{sitemap}->navbar($page); + if (@navbar) { + $navbar = join(q{}, @navbar); + } + } + if ($data_ref->{style}) { + $style = $self->{style_url} . $data_ref->{style}; + } + my %vars = ( + docknot_url => $URL, + html => decode('utf-8', $html), + links => $links, + modified => strftime('%Y-%m-%d', gmtime((stat($source))[9])), + navbar => $navbar, + now => strftime('%Y-%m-%d', gmtime()), + style => $style, + title => $title, + ); + + # Construct the output page from those template variables. + my $result; + $self->{template}->process($self->{template_path}, \%vars, \$result) + or croak($self->{template}->error()); + + # Write the result to the output file. + open(my $outfh, '>', $output); + _print_fh($outfh, $output, encode('utf-8', $result)); + close($outfh); + return; +} + +############################################################################## +# Public interface +############################################################################## + +# Create a new HTML converter for pointers. This object can (and should) be +# reused for all pointer conversions done while spinning a tree of files. +# +# $args - Anonymous hash of arguments with the following keys: +# docknot-url - URL to DocKnot itself for use in page footers +# output - Root of the output tree +# sitemap - App::DocKnot::Spin::Sitemap object +# style-url - Partial URL to style sheets +# +# Returns: Newly created object +# Throws: Text exception on failure to initialize Template Toolkit +sub new { + my ($class, $args_ref) = @_; + + # Get the configured path to pandoc, if any. + my $config_reader = App::DocKnot::Config->new(); + my $global_config_ref = $config_reader->global_config(); + my $pandoc = $global_config_ref->{pandoc} // 'pandoc'; + + # Add a trailing slash to the partial URL for style sheets. + my $style_url = $args_ref->{'style-url'} // q{}; + if ($style_url) { + $style_url =~ s{ /* \z }{/}xms; + } + + # Create and return the object. + my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); + my $self = { + output => $args_ref->{output}, + pandoc_path => $pandoc, + sitemap => $args_ref->{sitemap}, + style_url => $style_url, + template => $tt, + }; + bless($self, $class); + $self->{template_path} = $self->appdata_path('templates', 'html.tmpl'); + return $self; +} + +# Check if the result of a pointer file needs to be regenerated. +# +# $pointer - Pointer file to process +# $output - Corresponding output path +# +# Returns: True if the output file does not exist or has a modification date +# older than either the pointer file or the underlying source file, +# false otherwise +# Throws: YAML::XS exception on invalid pointer +sub is_out_of_date { + my ($self, $pointer, $output) = @_; + my $data_ref = $self->load_yaml_file($pointer, 'pointer'); + if (!-e $data_ref->{path}) { + die "$pointer: path $data_ref->{path} does not exist\n"; + } + return !_is_newer($output, $pointer, $data_ref->{path}); +} + +# Process a given pointer file. +# +# $pointer - Pointer file to process +# $output - Corresponding output path +# +# Throws: YAML::XS exception on invalid pointer +# Text exception for missing input file +# Text exception on failure to convert the file +sub spin_pointer { + my ($self, $pointer, $output, $options_ref) = @_; + my $data_ref = $self->load_yaml_file($pointer, 'pointer'); + + # Dispatch to the appropriate conversion function. + if ($data_ref->{format} eq 'markdown') { + $self->_spin_markdown($data_ref, $output); + } else { + die "$pointer: unknown output format $data_ref->{format}\n"; + } + return; +} + +############################################################################## +# Module return value and documentation +############################################################################## + +1; + +__END__ + +=for stopwords +Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT Kwalify sublicense unstyled + +=head1 NAME + +App::DocKnot::Spin::Pointer - Generate HTML from a pointer to an external file + +=head1 SYNOPSIS + + use App::DocKnot::Spin::Pointer; + use App::DocKnot::Spin::Sitemap; + + my $sitemap = App::DocKnot::Spin::Sitemap->new('/input/.sitemap'); + my $pointer = App::DocKnot::Spin::Pointer->new({ + output => '/output', + sitemap => $sitemap, + }); + $pointer->spin_pointer('/input/file.spin', '/output/file.html'); + +=head1 REQUIREMENTS + +Perl 5.24 or later and the modules File::ShareDir, Kwalify, and YAML::XS, all +of which are available from CPAN. + +=head1 DESCRIPTION + +The tree of input files for App::DocKnot::Spin may contain pointers to +external files in various formats. These files are in YAML format and end in +C<.spin>. This module processes those files and converts them to HTML and, if +so configured, adds the links to integrate the page with the rest of the site. + +For the details of the pointer file format, see L below. + +=head1 CLASS METHODS + +=over 4 + +=item new(ARGS) + +Create a new App::DocKnot::Spin::Pointer object. A single converter object +can be used repeatedly to convert pointers in a tree of files. ARGS should +be a hash reference with one or more of the following keys, all of which are +optional: + +=over 4 + +=item output + +The path to the root of the output tree when converting a tree of files. This +will be used to calculate relative path names for generating inter-page links +using the provided C argument. If C is given, this option +should also always be given. + +=item sitemap + +An App::DocKnot::Spin::Sitemap object. This will be used to create inter-page +links. For inter-page links, the C argument must also be provided. + +=item style-url + +The base URL for style sheets. A style sheet specified in a pointer file will +be considered to be relative to this URL and this URL will be prepended to it. +If this option is not given, the name of the style sheet will be used verbatim +as its URL, except with C<.css> appended. + +=back + +=back + +=head1 INSTANCE METHODS + +=over 4 + +=item is_out_of_date(POINTER, OUTPUT) + +Returns true if OUTPUT is missing or if it was modified less recently than the +modification time of either POINTER or the underlying file that it points to. + +=item spin_pointer(POINTER, OUTPUT) + +Convert a single pointer file to HTML. POINTER is the path to the pointer +file, and OUTPUT is the path to where to write the output. + +=back + +=head1 POINTER FILES + +A pointer file is a YAML file ending in C<.spin> that points to the source +file for a generated HTML page and provides additional configuration for its +conversion. The valid keys for a pointer file are: + +=over 4 + +=item format + +The format of the source file. The only valid value currently is C. +Required. + +=item path + +The path to the source file. It may be relative, in which case it's relative +to the pointer file. Required. + +=item style + +The style sheet to use for the converted output. Optional. If not set, the +converted output may be unstyled or may use a default style sheet appropriate +to the input format. + +=item title + +The title of the converted page. Optional. If not set, the title will be +taken from the converted file in a format-specific way. For Markdown, the +title will be the contents of the first top-level heading. + +=back + +=head1 AUTHOR + +Russ Allbery + +=head1 COPYRIGHT AND LICENSE + +Copyright 2021 Russ Allbery + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +=head1 SEE ALSO + +L, L, L + +This module is part of the App-DocKnot distribution. The current version of +DocKnot is available from CPAN, or directly from its web site at +L. + +=cut + +# Local Variables: +# copyright-at-end-flag: t diff --git a/lib/App/DocKnot/Spin/Sitemap.pm b/lib/App/DocKnot/Spin/Sitemap.pm index 038cc9f..1a37964 100644 --- a/lib/App/DocKnot/Spin/Sitemap.pm +++ b/lib/App/DocKnot/Spin/Sitemap.pm @@ -312,7 +312,6 @@ sub navbar { @breadcrumbs, $next_link, "\n", - "\n", ); } diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 2523d8d..6669286 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -1262,7 +1262,7 @@ sub _cmd_signature { if ($self->{sitemap} && $self->{output}) { my $page = $self->{out_path}; $page =~ s{ \A \Q$self->{output}\E }{}xms; - $output .= join(q{}, $self->{sitemap}->navbar($page)); + $output .= join(q{}, $self->{sitemap}->navbar($page)) . "\n"; } # Figure out the modification dates. Use the Git repository if available. @@ -1277,12 +1277,12 @@ sub _cmd_signature { } # Determine which template to use and substitute in the appropriate times. - $output .= "
\n" . q{ } x 4; + $output .= "
\n"; my $link = qq{spun}; if ($modified eq $now) { - $output .= "Last modified and\n $link $modified\n"; + $output .= " Last modified and\n $link $modified\n"; } else { - $output .= "Last $link\n $now from thread modified $modified\n"; + $output .= " Last $link\n $now from thread modified $modified\n"; } # Close out the document. diff --git a/share/schema/config.yaml b/share/schema/config.yaml index d63f829..d49312c 100644 --- a/share/schema/config.yaml +++ b/share/schema/config.yaml @@ -8,5 +8,7 @@ type: map mapping: distdir: type: text + pandoc: + type: text pgp_key: type: text diff --git a/share/schema/pointer.yaml b/share/schema/pointer.yaml new file mode 100644 index 0000000..fc8232d --- /dev/null +++ b/share/schema/pointer.yaml @@ -0,0 +1,20 @@ +# Kwalify schema for spin pointers to external files. +# +# Copyright 2021 Russ Allbery +# +# SPDX-License-Identifier: MIT + +type: map +mapping: + format: + type: text + required: true + enum: + - markdown + path: + type: text + required: true + style: + type: text + title: + type: text diff --git a/share/templates/html.tmpl b/share/templates/html.tmpl new file mode 100644 index 0000000..c9c72db --- /dev/null +++ b/share/templates/html.tmpl @@ -0,0 +1,22 @@ + + + + + [% title %] + [% IF style %] + [% END %] +[% IF links %][% links %][% END %] + + +[% IF navbar %][% navbar %] +[% END %][% html %][% IF navbar %] +[% navbar %][% END %] +
[% IF modified == now %] + Last modified and + spun [% modified %][% ELSE %] + Last spun + [% now %] from Markdown modified [% modified %][% END %] + + diff --git a/t/data/spin/markdown/input/.sitemap b/t/data/spin/markdown/input/.sitemap new file mode 100644 index 0000000..8c523a1 --- /dev/null +++ b/t/data/spin/markdown/input/.sitemap @@ -0,0 +1,4 @@ +/: Test Root + /foo.html: Some document + /other.html: Other test Markdown + /test.html: Test Markdown diff --git a/t/data/spin/markdown/input/other.spin b/t/data/spin/markdown/input/other.spin new file mode 100644 index 0000000..000cefe --- /dev/null +++ b/t/data/spin/markdown/input/other.spin @@ -0,0 +1,3 @@ +format: markdown +path: ../test.md +title: Other test Markdown diff --git a/t/data/spin/markdown/input/test.spin b/t/data/spin/markdown/input/test.spin new file mode 100644 index 0000000..7927ae8 --- /dev/null +++ b/t/data/spin/markdown/input/test.spin @@ -0,0 +1,3 @@ +format: markdown +path: ../test.md +style: markdown.css diff --git a/t/data/spin/markdown/output/other.html b/t/data/spin/markdown/output/other.html new file mode 100644 index 0000000..8948c0b --- /dev/null +++ b/t/data/spin/markdown/output/other.html @@ -0,0 +1,42 @@ + + + + + Other test Markdown + + + + + + + + + + + + +
< Some document + Test Root + Test Markdown >
+ +

Test Markdown

+

This is a test Markdown document.

+

Another header

+

Another section.

+

Some Üniçodé¡

+ + + + + +
< Some document + Test Root + Test Markdown >
+ +
+ Last spun + %DATE% from thread modified %DATE% + + diff --git a/t/data/spin/markdown/output/test.html b/t/data/spin/markdown/output/test.html new file mode 100644 index 0000000..2e9178d --- /dev/null +++ b/t/data/spin/markdown/output/test.html @@ -0,0 +1,42 @@ + + + + + Test Markdown + + + + + + + + + + + + +
< Other test Markdown + Test Root +
+ +

Test Markdown

+

This is a test Markdown document.

+

Another header

+

Another section.

+

Some Üniçodé¡

+ + + + + +
< Other test Markdown + Test Root +
+ +
+ Last spun + %DATE% from thread modified %DATE% + + diff --git a/t/data/spin/markdown/test.md b/t/data/spin/markdown/test.md new file mode 100644 index 0000000..4d00f0f --- /dev/null +++ b/t/data/spin/markdown/test.md @@ -0,0 +1,9 @@ +# Test Markdown + +This is a test Markdown document. + +## Another header + +Another section. + +Some Ãœniçodé¡ diff --git a/t/data/spin/output/software/docknot/api/app-docknot.html b/t/data/spin/output/software/docknot/api/app-docknot.html index ea3d829..944c09c 100644 --- a/t/data/spin/output/software/docknot/api/app-docknot.html +++ b/t/data/spin/output/software/docknot/api/app-docknot.html @@ -27,7 +27,6 @@ App::DocKnot::Command > -

App::DocKnot

(Documentation and software release management)

diff --git a/t/data/spin/output/software/docknot/index.html b/t/data/spin/output/software/docknot/index.html index aed23d8..b0352b3 100644 --- a/t/data/spin/output/software/docknot/index.html +++ b/t/data/spin/output/software/docknot/index.html @@ -26,7 +26,6 @@ rra-c-util> > -

DocKnot

diff --git a/t/data/spin/output/software/index.html b/t/data/spin/output/software/index.html index 630b839..00a8f2d 100644 --- a/t/data/spin/output/software/index.html +++ b/t/data/spin/output/software/index.html @@ -26,7 +26,6 @@ FAQs and Documentation > -

Software

diff --git a/t/data/spin/output/usefor/index.html b/t/data/spin/output/usefor/index.html index 216f66e..964c216 100644 --- a/t/data/spin/output/usefor/index.html +++ b/t/data/spin/output/usefor/index.html @@ -25,7 +25,6 @@ NNTP > -

The Usenet Article Format and Protocols

diff --git a/t/lib/Test/DocKnot/Spin.pm b/t/lib/Test/DocKnot/Spin.pm index 74cb592..c7c33b8 100644 --- a/t/lib/Test/DocKnot/Spin.pm +++ b/t/lib/Test/DocKnot/Spin.pm @@ -50,7 +50,7 @@ sub is_spin_output { Last [ ] modified [ ] and \s+ (]+>spun) [ ] [%]DATE[%] }{Last $1\n %DATE% from thread modified %DATE%}gxms; $results =~ s{ - %DATE% [ ] from [ ] POD [ ] modified [ ] %DATE% + %DATE% [ ] from [ ] (Markdown|POD) [ ] modified [ ] %DATE% }{%DATE% from thread modified %DATE%}gxms; $results =~ s{ () \d+ () diff --git a/t/spin/markdown.t b/t/spin/markdown.t new file mode 100755 index 0000000..7b098bb --- /dev/null +++ b/t/spin/markdown.t @@ -0,0 +1,56 @@ +#!/usr/bin/perl +# +# Test Markdown conversion. +# +# Copyright 2021 Russ Allbery +# +# SPDX-License-Identifier: MIT + +use 5.024; +use autodie; +use warnings; + +use lib 't/lib'; + +use Capture::Tiny qw(capture_stdout); +use Carp qw(croak); +use Cwd qw(getcwd); +use File::Copy::Recursive qw(dircopy); +use File::Temp (); +use IPC::Cmd qw(can_run); +use Test::DocKnot::Spin qw(is_spin_output_tree); +use Template (); + +use Test::More; + +# This test can only be run if pandoc is available. +if (!can_run('pandoc')) { + plan(skip_all => 'pandoc required for test'); +} + +# Isolate from the environment. +local $ENV{XDG_CONFIG_HOME} = '/nonexistent'; +local $ENV{XDG_CONFIG_DIRS} = '/nonexistent'; + +require_ok('App::DocKnot::Spin'); +require_ok('App::DocKnot::Spin::Pointer'); + +# Ensure Devel::Cover has loaded the HTML template before we start changing +# the working directory with File::Find. (This is a dumb workaround, but I +# can't find a better one; +ignore doesn't work.) +my $pointer = App::DocKnot::Spin::Pointer->new(); +my $template = $pointer->appdata_path('templates', 'html.tmpl'); +my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); +$tt->process($template, {}, \my $result); + +# Spin the tree of files and check the result. +my $datadir = File::Spec->catfile('t', 'data', 'spin', 'markdown'); +my $input = File::Spec->catfile($datadir, 'input'); +my $output = File::Temp->newdir(); +my $expected = File::Spec->catfile($datadir, 'output'); +my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' }); +my $stdout = capture_stdout { $spin->spin($input, $output->dirname) }; +my $count = is_spin_output_tree($output, $expected, 'spin'); + +# Report the end of testing. +done_testing($count + 2); diff --git a/t/spin/sitemap.t b/t/spin/sitemap.t index 1cac856..0ae949c 100755 --- a/t/spin/sitemap.t +++ b/t/spin/sitemap.t @@ -57,7 +57,6 @@ is_deeply(\@links, \@expected, 'links output'); q{ } . qq{Soundness for C News >\n}, qq{\n}, - qq{\n}, ); is_deeply(\@navbar, \@expected, 'navbar output'); diff --git a/t/style/coverage.t b/t/style/coverage.t index 5fd6feb..6cb4c22 100755 --- a/t/style/coverage.t +++ b/t/style/coverage.t @@ -6,7 +6,7 @@ # which can be found at . # # Written by Russ Allbery -# Copyright 2019-2020 Russ Allbery +# Copyright 2019-2021 Russ Allbery # Copyright 2013-2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -52,7 +52,8 @@ use_prereq('Devel::Cover'); use_prereq('Test::Strict'); # Build a list of test directories to use for coverage. -my %ignore = map { $_ => 1 } qw(data docs style), @COVERAGE_SKIP_TESTS; +my %ignore = map { $_ => 1 } qw(config data docs lib style), + @COVERAGE_SKIP_TESTS; opendir(my $testdir, 't') or BAIL_OUT("cannot open t: $!"); my @t_dirs = readdir($testdir) or BAIL_OUT("cannot read t: $!"); closedir($testdir) or BAIL_OUT("cannot close t: $!"); -- cgit v1.2.3 From 74c5d402923e0d4085200a38cfddeea8af16f341 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 23 Dec 2021 21:57:43 -0800 Subject: Move utility functions to new module Move is_newer, print_checked, and print_fh into a new App::DocKnot::Util module to share them between the multiple modules that use them. --- Changes | 3 + lib/App/DocKnot/Spin.pm | 88 ++++++-------------- lib/App/DocKnot/Spin/Pointer.pm | 43 ++-------- lib/App/DocKnot/Spin/RSS.pm | 65 +++++---------- lib/App/DocKnot/Spin/Thread.pm | 25 ++---- lib/App/DocKnot/Util.pm | 172 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 229 insertions(+), 167 deletions(-) create mode 100644 lib/App/DocKnot/Util.pm diff --git a/Changes b/Changes index 9d14a27..4de1bc4 100644 --- a/Changes +++ b/Changes @@ -12,6 +12,9 @@ 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. diff --git a/lib/App/DocKnot/Spin.pm b/lib/App/DocKnot/Spin.pm index 27b57e0..d1fe6f0 100644 --- a/lib/App/DocKnot/Spin.pm +++ b/lib/App/DocKnot/Spin.pm @@ -22,6 +22,7 @@ use App::DocKnot::Spin::RSS; use App::DocKnot::Spin::Sitemap; use App::DocKnot::Spin::Thread; use App::DocKnot::Spin::Versions; +use App::DocKnot::Util qw(is_newer print_checked print_fh); use Carp qw(croak); use Cwd qw(getcwd realpath); use File::Basename qw(fileparse); @@ -29,8 +30,7 @@ use File::Copy qw(copy); use File::Find qw(find finddepth); use File::Spec (); use Git::Repository (); -use List::SomeUtils qw(all); -use IPC::System::Simple qw(capture systemx); +use IPC::System::Simple qw(capture); use Pod::Thread 3.00 (); use POSIX qw(strftime); @@ -46,52 +46,10 @@ my @EXCLUDES = ( # used to embed a link to the software that generated the page. my $URL = 'https://www.eyrie.org/~eagle/software/web/'; -############################################################################## -# Utility functions -############################################################################## - -# Check if a file, which may not exist, is newer than another list of files. -# -# $file - File whose timestamp to compare -# @others - Other files to compare against -# -# Returns: True if $file exists and is newer than @others, false otherwise -sub _is_newer { - my ($file, @others) = @_; - return if !-e $file; - my $file_mtime = (stat($file))[9]; - my @others_mtimes = map { (stat)[9] } @others; - return all { $file_mtime >= $_ } @others_mtimes; -} - ############################################################################## # Output ############################################################################## -# print with error checking. autodie unfortunately can't help us because -# print can't be prototyped and hence can't be overridden. -sub _print_checked { - my (@args) = @_; - print @args or croak('print failed'); - return; -} - -# print with error checking and an explicit file handle. autodie -# unfortunately can't help us because print can't be prototyped and -# hence can't be overridden. -# -# $fh - Output file handle -# $file - File name for error reporting -# @args - Remaining arguments to print -# -# Returns: undef -# Throws: Text exception on output failure -sub _print_fh { - my ($fh, $file, @args) = @_; - print {$fh} @args or croak("cannot write to $file: $!"); - return; -} - # Build te page footer, which consists of the navigation links, the regular # signature, and the last modified date. # @@ -188,15 +146,15 @@ sub _write_converter_output { if ($self->{sitemap} && $line =~ m{ \A }xmsi) { my @links = $self->{sitemap}->links($page); if (@links) { - _print_fh($out_fh, $output, @links); + print_fh($out_fh, $output, @links); } } - _print_fh($out_fh, $output, $line); + print_fh($out_fh, $output, $line); if ($line =~ m{ {sitemap}) { my @navbar = $self->{sitemap}->navbar($page); if (@navbar) { - _print_fh($out_fh, $output, @navbar); + print_fh($out_fh, $output, @navbar); } } last; @@ -210,13 +168,13 @@ sub _write_converter_output { my $line; while (defined($line = shift($page_ref->@*))) { last if $line =~ m{ }xmsi; - _print_fh($out_fh, $output, $line); + print_fh($out_fh, $output, $line); } # Add the footer and finish with the output. - _print_fh($out_fh, $output, $footer->($blurb, $docid)); + print_fh($out_fh, $output, $footer->($blurb, $docid)); if (defined($line)) { - _print_fh($out_fh, $output, $line, $page_ref->@*); + print_fh($out_fh, $output, $line, $page_ref->@*); } close($out_fh); return; @@ -421,7 +379,7 @@ sub _process_file { if (-e $output && !-d $output) { die "cannot replace $output with a directory\n"; } elsif (!-d $output) { - _print_checked("Creating $shortout\n"); + print_checked("Creating $shortout\n"); mkdir($output, 0755); } my $rss_path = File::Spec->catfile($file, '.rss'); @@ -433,7 +391,7 @@ sub _process_file { $shortout =~ s{ [.] spin \z }{.html}xms; $self->{generated}{$output} = 1; if ($self->{pointer}->is_out_of_date($input, $output)) { - _print_checked("Converting $shortout\n"); + print_checked("Converting $shortout\n"); $self->{pointer}->spin_pointer($input, $output); } } elsif ($file =~ m{ [.] th \z }xms) { @@ -447,13 +405,13 @@ sub _process_file { my $relative = $input; $relative =~ s{ ^ \Q$self->{source}\E / }{}xms; my $time = $self->{versions}->latest_release($relative); - return if _is_newer($output, $file) && (stat($output))[9] >= $time; + return if is_newer($output, $file) && (stat($output))[9] >= $time; } else { - return if _is_newer($output, $file); + return if is_newer($output, $file); } # The output file is not newer. Respin it. - _print_checked("Spinning $shortout\n"); + print_checked("Spinning $shortout\n"); $self->{thread}->spin_thread_file($input, $output); } else { my ($extension) = ($file =~ m{ [.] ([^.]+) \z }xms); @@ -463,13 +421,13 @@ sub _process_file { $shortout =~ s{ [.] \Q$extension\E \z }{.html}xms; $self->{generated}{$output} = 1; my ($source, $options, $style) = $self->_read_pointer($input); - return if _is_newer($output, $input, $source); - _print_checked("Running $name for $shortout\n"); + return if is_newer($output, $input, $source); + print_checked("Running $name for $shortout\n"); $self->$sub($source, $output, $options, $style); } else { $self->{generated}{$output} = 1; - return if _is_newer($output, $file); - _print_checked("Updating $shortout\n"); + return if is_newer($output, $file); + print_checked("Updating $shortout\n"); copy($file, $output) or die "copy of $input to $output failed: $!\n"; } @@ -492,7 +450,7 @@ sub _delete_files { return if $self->{generated}{$file}; my $shortfile = $file; $shortfile =~ s{ ^ \Q$self->{output}\E }{...}xms; - _print_checked("Deleting $shortfile\n"); + print_checked("Deleting $shortfile\n"); if (-d $file) { rmdir($file); } else { @@ -564,7 +522,7 @@ sub spin { # Canonicalize and check output. if (!-d $output) { - _print_checked("Creating $output\n"); + print_checked("Creating $output\n"); mkdir($output, 0755); } $output = realpath($output) or die "cannot canonicalize $output: $!\n"; @@ -650,10 +608,10 @@ App::DocKnot::Spin - Static site builder supporting thread macro language =head1 REQUIREMENTS -Perl 5.24 or later and the modules Git::Repository, Image::Size, and -Pod::Thread, all of which are available from CPAN. Also expects to find -B, B, and B on the user's PATH to convert -certain types of files. +Perl 5.24 or later and the modules Git::Repository, Image::Size, +List::SomeUtils, and Pod::Thread, all of which are available from CPAN. Also +expects to find B, B, and B on the user's PATH +to convert certain types of files. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin/Pointer.pm b/lib/App/DocKnot/Spin/Pointer.pm index 969660f..2e1c67d 100644 --- a/lib/App/DocKnot/Spin/Pointer.pm +++ b/lib/App/DocKnot/Spin/Pointer.pm @@ -18,6 +18,7 @@ use parent qw(App::DocKnot); use warnings; use App::DocKnot::Config; +use App::DocKnot::Util qw(is_newer print_fh); use Carp qw(croak); use Encode qw(decode encode); use File::BaseDir qw(config_files); @@ -31,40 +32,6 @@ use YAML::XS (); # used to embed a link to the software that generated the page. my $URL = 'https://www.eyrie.org/~eagle/software/web/'; -############################################################################## -# Utility functions -############################################################################## - -# Check if a file, which may not exist, is newer than another list of files. -# -# $file - File whose timestamp to compare -# @others - Other files to compare against -# -# Returns: True if $file exists and is newer than @others, false otherwise -sub _is_newer { - my ($file, @others) = @_; - return if !-e $file; - my $file_mtime = (stat($file))[9]; - my @others_mtimes = map { (stat)[9] } @others; - return all { $file_mtime >= $_ } @others_mtimes; -} - -# print with error checking and an explicit file handle. autodie -# unfortunately can't help us because print can't be prototyped and hence -# can't be overridden. -# -# $fh - Output file handle -# $file - File name for error reporting -# @args - Remaining arguments to print -# -# Returns: undef -# Throws: Text exception on output failure -sub _print_fh { - my ($fh, $file, @args) = @_; - print {$fh} @args or croak("cannot write to $file: $!"); - return; -} - ############################################################################## # Format conversions ############################################################################## @@ -127,7 +94,7 @@ sub _spin_markdown { # Write the result to the output file. open(my $outfh, '>', $output); - _print_fh($outfh, $output, encode('utf-8', $result)); + print_fh($outfh, $output, encode('utf-8', $result)); close($outfh); return; } @@ -190,7 +157,7 @@ sub is_out_of_date { if (!-e $data_ref->{path}) { die "$pointer: path $data_ref->{path} does not exist\n"; } - return !_is_newer($output, $pointer, $data_ref->{path}); + return !is_newer($output, $pointer, $data_ref->{path}); } # Process a given pointer file. @@ -243,8 +210,8 @@ App::DocKnot::Spin::Pointer - Generate HTML from a pointer to an external file =head1 REQUIREMENTS -Perl 5.24 or later and the modules File::ShareDir, Kwalify, and YAML::XS, all -of which are available from CPAN. +Perl 5.24 or later and the modules File::ShareDir, Kwalify, List::SomeUtils, +and YAML::XS, all of which are available from CPAN. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin/RSS.pm b/lib/App/DocKnot/Spin/RSS.pm index dff4665..be5b105 100644 --- a/lib/App/DocKnot/Spin/RSS.pm +++ b/lib/App/DocKnot/Spin/RSS.pm @@ -17,6 +17,7 @@ use warnings; use App::DocKnot; use App::DocKnot::Spin::Thread; +use App::DocKnot::Util qw(print_checked print_fh); use Cwd qw(getcwd); use Date::Language (); use Date::Parse qw(str2time); @@ -28,30 +29,6 @@ use POSIX qw(strftime); # Utility functions ############################################################################## -# print with error checking. autodie unfortunately can't help us because -# print can't be prototyped and hence can't be overridden. -sub _print_checked { - my (@args) = @_; - print @args or croak('print failed'); - return; -} - -# print with error checking and an explicit file handle. autodie -# unfortunately can't help us because print can't be prototyped and hence -# can't be overridden. -# -# $fh - Output file handle -# $file - File name for error reporting -# @args - Remaining arguments to print -# -# Returns: undef -# Throws: Text exception on output failure -sub _print_fh { - my ($fh, $file, @args) = @_; - print {$fh} @args or croak("cannot write to $file: $!"); - return; -} - # Escapes &, <, and > characters for HTML or XML output. # # $string - Input string @@ -415,7 +392,7 @@ sub _rss_output { } # Output the RSS header. - _print_fh($fh, $file, <<"EOC"); + print_fh($fh, $file, <<"EOC"); @@ -430,14 +407,14 @@ EOC if ($metadata_ref->{'rss-base'}) { my ($name) = fileparse($file); my $url = $metadata_ref->{'rss-base'} . $name; - _print_fh( + print_fh( $fh, $file, qq{ \n}, ); } - _print_fh($fh, $file, "\n"); + print_fh($fh, $file, "\n"); # Output each entry, formatting the contents of the entry as we go. for my $entry_ref ($entries_ref->@*) { @@ -470,7 +447,7 @@ EOC } # Output the entry. - _print_fh( + print_fh( $fh, $file, " \n", @@ -486,7 +463,7 @@ EOC } # Close the RSS structure. - _print_fh($fh, $file, " \n\n"); + print_fh($fh, $file, " \n\n"); return; } @@ -505,9 +482,9 @@ sub _thread_output { # Page prefix. if ($metadata_ref->{'thread-prefix'}) { - _print_fh($fh, $file, $metadata_ref->{'thread-prefix'}, "\n"); + print_fh($fh, $file, $metadata_ref->{'thread-prefix'}, "\n"); } else { - _print_fh( + print_fh( $fh, $file, "\\heading[Recent Changes][indent]\n\n", @@ -522,13 +499,13 @@ sub _thread_output { # Put headings before each month. if (!$last_month || $month ne $last_month) { - _print_fh($fh, $file, "\\h2[$month]\n\n"); + print_fh($fh, $file, "\\h2[$month]\n\n"); $last_month = $month; } # Format each entry. my $date = strftime('%Y-%m-%d', localtime($entry_ref->{date})); - _print_fh( + print_fh( $fh, $file, "\\desc[$date \\entity[mdash]\n", @@ -538,11 +515,11 @@ sub _thread_output { my $description = $entry_ref->{description}; $description =~ s{ ^ }{ }xmsg; $description =~ s{ \\ }{\\\\}xmsg; - _print_fh($fh, $file, $description, "]\n\n"); + print_fh($fh, $file, $description, "]\n\n"); } # Print out the end of the page. - _print_fh($fh, $file, "\\signature\n"); + print_fh($fh, $file, "\\signature\n"); return; } @@ -651,7 +628,7 @@ sub _index_output { # Output the prefix. if ($metadata_ref->{'index-prefix'}) { - _print_fh($fh, $file, $metadata_ref->{'index-prefix'}, "\n"); + print_fh($fh, $file, $metadata_ref->{'index-prefix'}, "\n"); } # Output each entry. @@ -681,7 +658,7 @@ sub _index_output { }{$1 . _relative_url($2, $metadata_ref->{'index-base'}) . ']' }xmsge; # Print out the entry. - _print_fh( + print_fh( $fh, $file, "\\h2[$day: $entry_ref->{title}]\n\n", @@ -694,9 +671,9 @@ sub _index_output { # Print out the end of the page. if ($metadata_ref->{'index-suffix'}) { - _print_fh($fh, $file, $metadata_ref->{'index-suffix'}, "\n"); + print_fh($fh, $file, $metadata_ref->{'index-suffix'}, "\n"); } - _print_fh($fh, $file, "\\signature\n"); + print_fh($fh, $file, "\\signature\n"); return; } @@ -766,7 +743,7 @@ sub generate { # Write the output. if ($format eq 'thread') { - _print_checked("Generating thread file $prettyfile\n"); + print_checked("Generating thread file $prettyfile\n"); open(my $fh, '>', $path); $self->_thread_output($fh, $path, $metadata_ref, \@entries); close($fh); @@ -774,7 +751,7 @@ sub generate { if (scalar(@entries) > $metadata_ref->{recent}) { splice(@entries, $metadata_ref->{recent}); } - _print_checked("Generating RSS file $prettyfile\n"); + print_checked("Generating RSS file $prettyfile\n"); open(my $fh, '>', $path); $self->_rss_output($fh, $path, $metadata_ref, \@entries); close($fh); @@ -782,7 +759,7 @@ sub generate { if (scalar(@entries) > $metadata_ref->{recent}) { splice(@entries, $metadata_ref->{recent}); } - _print_checked("Generating index file $prettyfile\n"); + print_checked("Generating index file $prettyfile\n"); open(my $fh, '>', $path); $self->_index_output($fh, $path, $metadata_ref, \@entries); close($fh); @@ -816,8 +793,8 @@ App::DocKnot::Spin::RSS - Generate RSS and thread from a feed description file =head1 REQUIREMENTS Perl 5.006 or later and the modules Date::Language, Date::Parse (both part of -the TimeDate distribution), and Perl6::Slurp, both of which are available from -CPAN. +the TimeDate distribution), List::SomeUtils, and Perl6::Slurp, both of which +are available from CPAN. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 6669286..93f6908 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -16,6 +16,7 @@ use autodie; use warnings; use App::DocKnot; +use App::DocKnot::Util qw(print_fh); use Cwd qw(getcwd realpath); use File::Basename qw(fileparse); use File::Spec (); @@ -104,22 +105,6 @@ sub _read_file { return $text; } -# print with error checking and an explicit file handle. autodie -# unfortunately can't help us because print can't be prototyped and hence -# can't be overridden. -# -# $fh - Output file handle -# $file - File name for error reporting -# @args - Remaining arguments to print -# -# Returns: undef -# Throws: Text exception on output failure -sub _print_fh { - my ($fh, $file, @args) = @_; - print {$fh} @args or croak("cannot write to $file: $!"); - return; -} - # Sends something to the output file with special handling of whitespace for # more readable HTML output. # @@ -159,7 +144,7 @@ sub _output { } # Send the results to the output file. - _print_fh($self->{out_fh}, $self->{out_path}, $output); + print_fh($self->{out_fh}, $self->{out_path}, $output); return; } @@ -688,7 +673,7 @@ sub _parse_document { } # Close open tags and print any deferred whitespace. - _print_fh($out_fh, $out_path, $self->_block_end(), $self->{space}); + print_fh($out_fh, $out_path, $self->_block_end(), $self->{space}); return; } @@ -1520,8 +1505,8 @@ App::DocKnot::Spin::Thread - Generate HTML from the macro language thread =head1 REQUIREMENTS -Perl 5.24 or later and the modules Git::Repository and Image::Size, both of -which are available from CPAN. +Perl 5.24 or later and the modules Git::Repository, Image::Size, and +List::SomeUtils, all of which are available from CPAN. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Util.pm b/lib/App/DocKnot/Util.pm new file mode 100644 index 0000000..a72b37a --- /dev/null +++ b/lib/App/DocKnot/Util.pm @@ -0,0 +1,172 @@ +# Shared utility functions for other DocKnot modules. +# +# A collection of random utility functions that are used by more than one +# DocKnot module but don't make sense as App::DocKnot methods. +# +# SPDX-License-Identifier: MIT + +############################################################################## +# Modules and declarations +############################################################################## + +package App::DocKnot::Util 5.00; + +use 5.024; +use autodie; +use warnings; + +use Carp qw(croak); +use Exporter qw(import); +use List::SomeUtils qw(all); + +our @EXPORT_OK = qw(is_newer print_checked print_fh); + +############################################################################## +# Public interface +############################################################################## + +# Check if a file, which may not exist, is newer than another list of files. +# +# $file - File whose timestamp to compare +# @others - Other files to compare against +# +# Returns: True if $file exists and is newer than @others, false otherwise +sub is_newer { + my ($file, @others) = @_; + return if !-e $file; + my $file_mtime = (stat($file))[9]; + my @others_mtimes = map { (stat)[9] } @others; + return all { $file_mtime >= $_ } @others_mtimes; +} + +# print with error checking. autodie unfortunately can't help us because +# print can't be prototyped and hence can't be overridden. +# +# @args - Arguments to print to stdout +# +# Returns: undef +# Throws: Text exception on output failure +sub print_checked { + my (@args) = @_; + print @args or croak('print failed'); + return; +} + +# print with error checking and an explicit file handle. autodie +# unfortunately can't help us because print can't be prototyped and +# hence can't be overridden. +# +# $fh - Output file handle +# $file - File name for error reporting +# @args - Remaining arguments to print +# +# Returns: undef +# Throws: Text exception on output failure +sub print_fh { + my ($fh, $file, @args) = @_; + print {$fh} @args or croak("cannot write to $file: $!"); + return; +} + +############################################################################## +# Module return value and documentation +############################################################################## + +1; +__END__ + +=for stopwords +Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT sublicense FH autodie + +=head1 NAME + +App::DocKnot::Util - Shared utility functions for other DocKnot modules + +=head1 SYNOPSIS + + use App::DocKnot::Util qw(is_newer print_checked print_fh); + + print_checked('some stdout output'); + if (!is_newer('/output', '/input-1', '/input-2')) { + open(my $fh, '>', '/output'); + print_fh($fh, '/output', 'some stuff'); + close($fh); + } + +=head1 REQUIREMENTS + +Perl 5.24 or later and the List::SomeUtils module, available from CPAN. + +=head1 DESCRIPTION + +This module collects utility functions used by other App::DocKnot modules. It +is not really intended for use outside of DocKnot, but these functions can be +used if desired. + +=head1 FUNCTIONS + +=over 4 + +=item is_newer(FILE, SOURCE[, SOURCE ...]) + +Returns a true value if FILE exists and has a last modified time that is newer +or equal to the last modified times of all SOURCE files, and otherwise returns +a false value. Used primarily to determine if a given output file is +up-to-date with respect to its source files. + +=item print_checked(ARG[, ARG ...]) + +The same as print (without a file handle argument), except that it throws a +text exception on failure as if autodie affected print (which it unfortunately +doesn't because print cannot be prototyped). + +=item print_fh(FH, NAME, DATA[, DATA ...]) + +Writes the concatenation of the DATA elements (interpreted as scalar strings) +to the file handle FH. NAME should be the name of the file open as FH, and is +used for error reporting. + +This is mostly equivalent to C but throws a text exception in the +event of a failure. + +=back + +=head1 AUTHOR + +Russ Allbery + +=head1 COPYRIGHT AND LICENSE + +Copyright 1999-2011, 2013, 2021 Russ Allbery + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +=head1 SEE ALSO + +L + +This module is part of the App-DocKnot distribution. The current version of +DocKnot is available from CPAN, or directly from its web site at +L. + +=cut + +# Local Variables: +# copyright-at-end-flag: t +# End: -- cgit v1.2.3 From 9257e00ec67fb1c0ad07d8d91fb2bfbdd1c14949 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Fri, 24 Dec 2021 19:37:05 -0800 Subject: Reformat code Adopt the new -nvc option in Perl::Tidy 20211029 to disable the intrusive vertical alignment formatting. Unfortunately, this breaks all vertical alignment formatting, even when desired, so work around that in a few places with special comments. --- Build.PL | 2 ++ lib/App/DocKnot.pm | 4 ++-- lib/App/DocKnot/Command.pm | 28 ++++++++++++------------ lib/App/DocKnot/Config.pm | 6 +++--- lib/App/DocKnot/Dist.pm | 26 ++++++++++++----------- lib/App/DocKnot/Generate.pm | 25 +++++++++++----------- lib/App/DocKnot/Spin.pm | 40 ++++++++++++++++++---------------- lib/App/DocKnot/Spin/Pointer.pm | 10 ++++++--- lib/App/DocKnot/Spin/RSS.pm | 12 +++++------ lib/App/DocKnot/Spin/Sitemap.pm | 8 ++++--- lib/App/DocKnot/Spin/Thread.pm | 46 +++++++++++++++++++++++----------------- lib/App/DocKnot/Spin/Versions.pm | 6 +++--- lib/App/DocKnot/Update.pm | 8 +++---- lib/App/DocKnot/Util.pm | 2 +- t/cli/generate.t | 8 +++---- t/cli/spin.t | 8 +++---- t/config/basic.t | 6 +++--- t/data/dist/package/Build.PL | 2 ++ t/data/perltidyrc | 4 +++- t/data/regenerate-data | 8 +++---- t/dist/basic.t | 20 ++++++++--------- t/dist/commands.t | 2 +- t/docs/spdx-license.t | 32 +++++++++++++++------------- t/generate/basic.t | 2 +- t/generate/output.t | 4 ++-- t/lib/Test/RRA.pm | 10 ++++----- t/lib/Test/RRA/ModuleVersion.pm | 6 +++--- t/metadata/licenses.t | 6 +++--- t/spin/errors.t | 2 +- t/spin/file.t | 8 +++---- t/spin/markdown.t | 16 +++++++------- t/spin/sitemap.t | 8 +++---- t/spin/thread.t | 12 +++++------ t/spin/tree.t | 22 +++++++++---------- t/spin/versions.t | 18 ++++++++-------- t/style/coverage.t | 4 ++-- t/style/module-version.t | 4 ++-- t/style/strict.t | 2 +- t/update/basic.t | 6 +++--- 39 files changed, 236 insertions(+), 207 deletions(-) diff --git a/Build.PL b/Build.PL index ecb08ac..a2f8640 100644 --- a/Build.PL +++ b/Build.PL @@ -31,6 +31,7 @@ use warnings; use Module::Build; # Basic package configuration. +#<<< my $build = Module::Build->new( dist_abstract => 'Package documentation generator', dist_author => 'Russ Allbery ', @@ -84,6 +85,7 @@ my $build = Module::Build->new( 'File::Copy::Recursive' => 0, }, ); +#>>> # Generate the build script. $build->create_build_script; diff --git a/lib/App/DocKnot.pm b/lib/App/DocKnot.pm index e7d5b65..b92adae 100644 --- a/lib/App/DocKnot.pm +++ b/lib/App/DocKnot.pm @@ -71,9 +71,9 @@ sub load_yaml_file { local $YAML::XS::Boolean = 'JSON::PP'; # Load the metadata and check it against the schema. - my $data_ref = YAML::XS::LoadFile($path); + my $data_ref = YAML::XS::LoadFile($path); my $schema_path = $self->appdata_path('schema', $schema . '.yaml'); - my $schema_ref = YAML::XS::LoadFile($schema_path); + my $schema_ref = YAML::XS::LoadFile($schema_path); eval { validate($schema_ref, $data_ref) }; if ($@) { my $errors = $@; diff --git a/lib/App/DocKnot/Command.pm b/lib/App/DocKnot/Command.pm index 50da1cc..e8fee87 100644 --- a/lib/App/DocKnot/Command.pm +++ b/lib/App/DocKnot/Command.pm @@ -60,47 +60,47 @@ use Pod::Usage qw(pod2usage); # are not set, an error will be thrown. our %COMMANDS = ( dist => { - method => 'make_distribution', - module => 'App::DocKnot::Dist', + method => 'make_distribution', + module => 'App::DocKnot::Dist', options => ['distdir|d=s', 'metadata|m=s', 'pgp-key|p=s'], maximum => 0, }, generate => { - method => 'generate_output', - module => 'App::DocKnot::Generate', + method => 'generate_output', + module => 'App::DocKnot::Generate', options => ['metadata|m=s', 'width|w=i'], maximum => 2, minimum => 1, }, 'generate-all' => { - method => 'generate_all', - module => 'App::DocKnot::Generate', + method => 'generate_all', + module => 'App::DocKnot::Generate', options => ['metadata|m=s', 'width|w=i'], maximum => 0, }, spin => { - method => 'spin', - module => 'App::DocKnot::Spin', + method => 'spin', + module => 'App::DocKnot::Spin', options => ['delete|d', 'exclude|e=s@', 'style-url|s=s'], minimum => 2, maximum => 2, }, 'spin-rss' => { - method => 'generate', - module => 'App::DocKnot::Spin::RSS', + method => 'generate', + module => 'App::DocKnot::Spin::RSS', options => ['base|b=s'], minimum => 1, maximum => 1, }, 'spin-thread' => { - method => 'spin_thread_file', - module => 'App::DocKnot::Spin::Thread', + method => 'spin_thread_file', + module => 'App::DocKnot::Spin::Thread', options => ['style-url|s=s'], maximum => 2, }, update => { - method => 'update', - module => 'App::DocKnot::Update', + method => 'update', + module => 'App::DocKnot::Update', options => ['metadata|m=s', 'output|o=s'], maximum => 0, }, diff --git a/lib/App/DocKnot/Config.pm b/lib/App/DocKnot/Config.pm index f4a118b..d8a7b27 100644 --- a/lib/App/DocKnot/Config.pm +++ b/lib/App/DocKnot/Config.pm @@ -74,14 +74,14 @@ sub config { } # Expand the package license into license text. - my $license = $data_ref->{license}{name}; + my $license = $data_ref->{license}{name}; my $licenses_path = $self->appdata_path('licenses.yaml'); - my $licenses_ref = YAML::XS::LoadFile($licenses_path); + my $licenses_ref = YAML::XS::LoadFile($licenses_path); if (!exists($licenses_ref->{$license})) { die "unknown license $license\n"; } $data_ref->{license}{summary} = $licenses_ref->{$license}{summary}; - $data_ref->{license}{text} = $licenses_ref->{$license}{text}; + $data_ref->{license}{text} = $licenses_ref->{$license}{text}; # Return the resulting configuration. return $data_ref; diff --git a/lib/App/DocKnot/Dist.pm b/lib/App/DocKnot/Dist.pm index 4caa9b5..f9f7a89 100644 --- a/lib/App/DocKnot/Dist.pm +++ b/lib/App/DocKnot/Dist.pm @@ -23,8 +23,8 @@ use Cwd qw(getcwd); use File::Copy qw(move); use File::Find qw(find); use File::Path qw(remove_tree); -use Git::Repository (); -use IO::Compress::Xz (); +use Git::Repository (); +use IO::Compress::Xz (); use IO::Uncompress::Gunzip (); use IPC::Run qw(run); use IPC::System::Simple qw(systemx); @@ -139,7 +139,7 @@ sub _expected_dist_files { # Throws: Text exception if no gzip tarball was found sub _find_gzip_tarball { my ($self, $path, $prefix) = @_; - my @files = $self->_find_matching_tarballs($path, $prefix); + my @files = $self->_find_matching_tarballs($path, $prefix); my $gzip_file = lastval { m{ [.]tar [.]gz \z }xms } @files; if (!defined($gzip_file)) { die "cannot find gzip tarball for $prefix in $path\n"; @@ -175,14 +175,14 @@ sub _generate_compression_formats { my @files = $self->_find_matching_tarballs($path, $prefix); if (!any { m{ [.]tar [.]xz \z }xms } @files) { my $gzip_file = lastval { m{ [.]tar [.]gz \z }xms } @files; - my $xz_file = $gzip_file; + my $xz_file = $gzip_file; $xz_file =~ s{ [.]gz \z }{.xz}xms; my $gzip_path = File::Spec->catfile($path, $gzip_file); - my $xz_path = File::Spec->catfile($path, $xz_file); + my $xz_path = File::Spec->catfile($path, $xz_file); # Open the input and output files. my $gzip_fh = IO::Uncompress::Gunzip->new($gzip_path); - my $xz_fh = IO::Compress::Xz->new($xz_path); + my $xz_fh = IO::Compress::Xz->new($xz_path); # Read from the gzip file and write to the xz-compressed file. my $buffer; @@ -248,7 +248,7 @@ sub _sign_tarballs { for my $file (@files) { my $tarball_path = File::Spec->catdir($path, $file); systemx( - $self->{gpg}, '--detach-sign', '--armor', '-u', + $self->{gpg}, '--detach-sign', '--armor', '-u', $self->{pgp_key}, $tarball_path, ); } @@ -293,6 +293,7 @@ sub new { } # Create and return the object. + #<<< my $self = { config => $config_reader->config(), distdir => $distdir, @@ -300,6 +301,7 @@ sub new { perl => $args_ref->{perl}, pgp_key => $args_ref->{pgp_key} // $global_config_ref->{pgp_key}, }; + #>>> bless($self, $class); return $self; } @@ -318,7 +320,7 @@ sub check_dist { my ($self, $source, $tarball) = @_; my @expected = $self->_expected_dist_files(getcwd()); my %expected = map { $_ => 1 } @expected; - my $archive = Archive::Tar->new($tarball); + my $archive = Archive::Tar->new($tarball); for my $file ($archive->list_files()) { $file =~ s{ \A [^/]* / }{}xms; delete $expected{$file}; @@ -333,8 +335,8 @@ sub check_dist { # Returns: List of commands, each of which is a list of strings representing # a command and its arguments sub commands { - my ($self) = @_; - my $type = $self->{config}{build}{type}; + my ($self) = @_; + my $type = $self->{config}{build}{type}; my @commands = map { [@$_] } $COMMANDS{$type}->@*; # Special-case: If a specific path to Perl was configured, use that path @@ -391,11 +393,11 @@ sub make_distribution { } # Export the Git repository into a new directory. - my $repo = Git::Repository->new(work_tree => $source); + my $repo = Git::Repository->new(work_tree => $source); my @branches = $repo->run( 'for-each-ref' => '--format=%(refname:short)', 'refs/heads/', ); - my $head = first { $_ eq 'main' || $_ eq 'master' } @branches; + my $head = first { $_ eq 'main' || $_ eq 'master' } @branches; my $archive = $repo->command(archive => "--prefix=${prefix}/", $head); run([qw(tar xf -)], '<', $archive->stdout) or die "git archive | tar xf - failed with status $?\n"; diff --git a/lib/App/DocKnot/Generate.pm b/lib/App/DocKnot/Generate.pm index 49b73a3..9d5a8e0 100644 --- a/lib/App/DocKnot/Generate.pm +++ b/lib/App/DocKnot/Generate.pm @@ -25,7 +25,7 @@ use Text::Wrap qw(wrap); # Default output files for specific templates. my %DEFAULT_OUTPUT = ( - 'readme' => 'README', + 'readme' => 'README', 'readme-md' => 'README.md', ); @@ -77,11 +77,11 @@ sub _code_for_copyright { my $notice; for my $copyright ($copyrights_ref->@*) { my $holder = $copyright->{holder}; - my $years = $copyright->{years}; + my $years = $copyright->{years}; # Build the initial notice with the word copyright and the years. my $text = 'Copyright ' . $copyright->{years}; - local $Text::Wrap::columns = $self->{width} + 1; + local $Text::Wrap::columns = $self->{width} + 1; local $Text::Wrap::unexpand = 0; $text = wrap($prefix, $prefix . q{ } x 4, $text); @@ -174,11 +174,12 @@ sub _code_for_to_text { # numeric references, and accumulate the mapping of numbers to URLs in # %urls. Then, add to the end of the paragraph the references and # URLs. - my $ref = 1; + my $ref = 1; my @paragraphs = split(m{ \n\n }xms, $text); for my $para (@paragraphs) { my %urls; - while ($para =~ s{ \[([^\]]+)\] [(] (\S+) [)] }{$1 [$ref]}xms) { + my $regex = qr{ \[([^\]]+)\] [(] (\S+) [)] }xms; + while ($para =~ s{$regex}{$1 [$ref]}xms) { $urls{$ref} = $2; $ref++; } @@ -375,9 +376,9 @@ sub _wrap_paragraph { $para =~ s{ \n(\S) }{ $1}xmsg; # Force locally correct configuration of Text::Wrap. - local $Text::Wrap::break = qr{\s+}xms; - local $Text::Wrap::columns = $self->{width} + 1; - local $Text::Wrap::huge = 'overflow'; + local $Text::Wrap::break = qr{\s+}xms; + local $Text::Wrap::columns = $self->{width} + 1; + local $Text::Wrap::huge = 'overflow'; local $Text::Wrap::unexpand = 0; # Do the wrapping. This modifies @paragraphs in place. @@ -447,7 +448,7 @@ sub new { # Create and return the object. my $self = { config => $config, - width => $args_ref->{width} // 74, + width => $args_ref->{width} // 74, }; bless($self, $class); return $self; @@ -472,10 +473,10 @@ sub generate { my %vars = %{$data_ref}; # Add code references for our defined helper functions. - $vars{center} = $self->_code_for_center; + $vars{center} = $self->_code_for_center; $vars{copyright} = $self->_code_for_copyright($data_ref->{copyrights}); - $vars{indent} = $self->_code_for_indent; - $vars{to_text} = $self->_code_for_to_text; + $vars{indent} = $self->_code_for_indent; + $vars{to_text} = $self->_code_for_to_text; $vars{to_thread} = $self->_code_for_to_thread; # Ensure we were given a valid template. diff --git a/lib/App/DocKnot/Spin.pm b/lib/App/DocKnot/Spin.pm index d1fe6f0..3f6590e 100644 --- a/lib/App/DocKnot/Spin.pm +++ b/lib/App/DocKnot/Spin.pm @@ -28,7 +28,7 @@ use Cwd qw(getcwd realpath); use File::Basename qw(fileparse); use File::Copy qw(copy); use File::Find qw(find finddepth); -use File::Spec (); +use File::Spec (); use Git::Repository (); use IPC::System::Simple qw(capture); use Pod::Thread 3.00 (); @@ -65,7 +65,7 @@ my $URL = 'https://www.eyrie.org/~eagle/software/web/'; # Returns: HTML output sub _footer { my ($self, $source, $out_path, $id, @templates) = @_; - my $output = q{}; + my $output = q{}; my $in_tree = 0; if ($self->{source} && $source =~ m{ \A \Q$self->{source}\E }xms) { $in_tree = 1; @@ -191,7 +191,7 @@ sub _write_converter_output { sub _cl2xhtml { my ($self, $source, $output, $options, $style) = @_; $style ||= $self->{style_url} . 'changelog.css'; - my @page = capture("cl2xhtml $options -s $style $source"); + my @page = capture("cl2xhtml $options -s $style $source"); my $footer = sub { my ($blurb, $id) = @_; if ($blurb) { @@ -220,7 +220,7 @@ sub _cvs2xhtml { $options .= " -s $style"; # Run the converter and write the output. - my @page = capture("(cd $dir && cvs log $name) | cvs2xhtml $options"); + my @page = capture("(cd $dir && cvs log $name) | cvs2xhtml $options"); my $footer = sub { my ($blurb, $id, $file) = @_; if ($blurb) { @@ -238,7 +238,7 @@ sub _cvs2xhtml { sub _faq2html { my ($self, $source, $output, $options, $style) = @_; $style ||= $self->{style_url} . 'faq.css'; - my @page = capture("faq2html $options -s $style $source"); + my @page = capture("faq2html $options -s $style $source"); my $footer = sub { my ($blurb, $id, $file) = @_; if ($blurb) { @@ -316,9 +316,9 @@ sub _read_pointer { # Read the pointer file. open(my $pointer, '<', $file); - my $master = <$pointer>; + my $master = <$pointer>; my $options = <$pointer>; - my $style = <$pointer>; + my $style = <$pointer>; close($pointer); # Clean up the contents. @@ -356,7 +356,7 @@ sub _process_file { return; } } - my $input = $File::Find::name; + my $input = $File::Find::name; my $output = $input; $output =~ s{ \A \Q$self->{source}\E }{$self->{output}}xms or die "input file $file out of tree\n"; @@ -366,12 +366,14 @@ sub _process_file { # Conversion rules for pointers. The key is the extension, the first # value is the name of the command for the purposes of output, and the # second is the name of the method to run. + #<<< my %rules = ( changelog => ['cl2xhtml', '_cl2xhtml'], faq => ['faq2html', '_faq2html'], log => ['cvs2xhtml', '_cvs2xhtml'], rpod => ['pod2thread', '_pod2html'], ); + #>>> # Figure out what to do with the input. if (-d $file) { @@ -387,7 +389,7 @@ sub _process_file { $self->{rss}->generate($rss_path, $file); } } elsif ($file =~ m{ [.] spin \z }xms) { - $output =~ s{ [.] spin \z }{.html}xms; + $output =~ s{ [.] spin \z }{.html}xms; $shortout =~ s{ [.] spin \z }{.html}xms; $self->{generated}{$output} = 1; if ($self->{pointer}->is_out_of_date($input, $output)) { @@ -395,7 +397,7 @@ sub _process_file { $self->{pointer}->spin_pointer($input, $output); } } elsif ($file =~ m{ [.] th \z }xms) { - $output =~ s{ [.] th \z }{.html}xms; + $output =~ s{ [.] th \z }{.html}xms; $shortout =~ s{ [.] th \z }{.html}xms; $self->{generated}{$output} = 1; @@ -417,7 +419,7 @@ sub _process_file { my ($extension) = ($file =~ m{ [.] ([^.]+) \z }xms); if (defined($extension) && $rules{$extension}) { my ($name, $sub) = $rules{$extension}->@*; - $output =~ s{ [.] \Q$extension\E \z }{.html}xms; + $output =~ s{ [.] \Q$extension\E \z }{.html}xms; $shortout =~ s{ [.] \Q$extension\E \z }{.html}xms; $self->{generated}{$output} = 1; my ($source, $options, $style) = $self->_read_pointer($input); @@ -489,12 +491,14 @@ sub new { } # Create and return the object. + #<<< my $self = { delete => $args_ref->{delete}, excludes => [@excludes], rss => App::DocKnot::Spin::RSS->new(), style_url => $style_url, }; + #>>> bless($self, $class); return $self; } @@ -551,6 +555,7 @@ sub spin { } # Create a new thread converter object. + #<<< $self->{thread} = App::DocKnot::Spin::Thread->new( { output => $output, @@ -560,8 +565,10 @@ sub spin { versions => $self->{versions}, }, ); + #>>> # Create the processor for pointers. + #<<< $self->{pointer} = App::DocKnot::Spin::Pointer->new( { output => $output, @@ -569,15 +576,12 @@ sub spin { 'style-url' => $self->{style_url}, }, ); + #>>> # Process the input tree. - find( - { - preprocess => sub { my @files = sort(@_); return @files }, - wanted => sub { $self->_process_file(@_) }, - }, - $input, - ); + my $preprocess = sub { my @files = sort(@_); return @files }; + my $wanted = sub { $self->_process_file(@_) }; + find({ preprocess => $preprocess, wanted => $wanted }, $input); if ($self->{delete}) { finddepth(sub { $self->_delete_files(@_) }, $output); } diff --git a/lib/App/DocKnot/Spin/Pointer.pm b/lib/App/DocKnot/Spin/Pointer.pm index 2e1c67d..63660b5 100644 --- a/lib/App/DocKnot/Spin/Pointer.pm +++ b/lib/App/DocKnot/Spin/Pointer.pm @@ -76,6 +76,7 @@ sub _spin_markdown { if ($data_ref->{style}) { $style = $self->{style_url} . $data_ref->{style}; } + #<<< my %vars = ( docknot_url => $URL, html => decode('utf-8', $html), @@ -86,6 +87,7 @@ sub _spin_markdown { style => $style, title => $title, ); + #>>> # Construct the output page from those template variables. my $result; @@ -118,9 +120,9 @@ sub new { my ($class, $args_ref) = @_; # Get the configured path to pandoc, if any. - my $config_reader = App::DocKnot::Config->new(); + my $config_reader = App::DocKnot::Config->new(); my $global_config_ref = $config_reader->global_config(); - my $pandoc = $global_config_ref->{pandoc} // 'pandoc'; + my $pandoc = $global_config_ref->{pandoc} // 'pandoc'; # Add a trailing slash to the partial URL for style sheets. my $style_url = $args_ref->{'style-url'} // q{}; @@ -129,7 +131,8 @@ sub new { } # Create and return the object. - my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); + my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); + #<<< my $self = { output => $args_ref->{output}, pandoc_path => $pandoc, @@ -137,6 +140,7 @@ sub new { style_url => $style_url, template => $tt, }; + #>>> bless($self, $class); $self->{template_path} = $self->appdata_path('templates', 'html.tmpl'); return $self; diff --git a/lib/App/DocKnot/Spin/RSS.pm b/lib/App/DocKnot/Spin/RSS.pm index be5b105..a2d2c4d 100644 --- a/lib/App/DocKnot/Spin/RSS.pm +++ b/lib/App/DocKnot/Spin/RSS.pm @@ -132,7 +132,7 @@ sub _relative_url { sub _spin_file { my ($self, $file) = @_; my $source = slurp($file); - my $cwd = getcwd(); + my $cwd = getcwd(); my (undef, $dir) = fileparse($file); chdir($dir); my $page = $self->{spin}->spin_thread($source); @@ -152,7 +152,7 @@ sub _spin_file { sub _read_rfc2822_file { my ($self, $file) = @_; my $key; - my @blocks = ({}); + my @blocks = ({}); my $current = $blocks[0]; # Parse the file. $key holds the last key seen, used to append @@ -383,9 +383,9 @@ sub _rss_output { # Determine the current date and latest publication date of all of the # entries, published in the obnoxious format used by RSS. - my $lang = Date::Language->new('English'); + my $lang = Date::Language->new('English'); my $format = '%a, %d %b %Y %H:%M:%S %z'; - my $now = $lang->strftime($format, [localtime()]); + my $now = $lang->strftime($format, [localtime()]); my $latest = $now; if ($entries_ref->@*) { $latest = strftime($format, localtime($entries_ref->[0]{date})); @@ -418,7 +418,7 @@ EOC # Output each entry, formatting the contents of the entry as we go. for my $entry_ref ($entries_ref->@*) { - my $date = $lang->strftime($format, [localtime($entry_ref->{date})]); + my $date = $lang->strftime($format, [localtime($entry_ref->{date})]); my $title = _escape($entry_ref->{title}); my $description; if ($entry_ref->{description}) { @@ -635,7 +635,7 @@ sub _index_output { for my $entry_ref ($entries_ref->@*) { my @time = localtime($entry_ref->{date}); my $date = strftime('%Y-%m-%d %H:%M', @time); - my $day = strftime('%Y-%m-%d', @time); + my $day = strftime('%Y-%m-%d', @time); # Get the text of the entry. my $text; diff --git a/lib/App/DocKnot/Spin/Sitemap.pm b/lib/App/DocKnot/Spin/Sitemap.pm index 1a37964..46e9e0f 100644 --- a/lib/App/DocKnot/Spin/Sitemap.pm +++ b/lib/App/DocKnot/Spin/Sitemap.pm @@ -141,7 +141,7 @@ sub _escape { sub _relative { my ($origin, $dest) = @_; my @origin = split(qr{ / }xms, $origin, -1); - my @dest = split(qr{ / }xms, $dest, -1); + my @dest = split(qr{ / }xms, $dest, -1); # Remove the common prefix. while (@origin && @dest && $origin[0] eq $dest[0]) { @@ -207,11 +207,13 @@ sub new { # links maps partial URLs to a list of other partial URLs (previous, next, # and then the full upwards hierarchy to the top of the site) used for # interpage links. + #<<< my $self = { links => {}, pagedesc => {}, sitemap => [], }; + #>>> bless($self, $class); # Parse the file into the newly-created object. @@ -292,7 +294,7 @@ sub navbar { # Construct the bread crumbs for the page hierarchy. my @breadcrumbs = (" \n"); - my $first = 1; + my $first = 1; for my $parent (reverse(@parents)) { my ($url, $desc) = $parent->@*; my $prefix = q{ } x 4; @@ -334,7 +336,7 @@ sub sitemap { # Open or close

    elements as needed by the indentation. if ($indent > $indents[-1]) { - push(@output, (q{ } x $indent) . "
      \n"); + push(@output, (q{ } x $indent) . "
        \n"); push(@indents, $indent); } else { while ($indent < $indents[-1]) { diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 93f6908..53cabc9 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -19,7 +19,7 @@ use App::DocKnot; use App::DocKnot::Util qw(print_fh); use Cwd qw(getcwd realpath); use File::Basename qw(fileparse); -use File::Spec (); +use File::Spec (); use Git::Repository (); use Image::Size qw(html_imgsize); use Perl6::Slurp qw(slurp); @@ -35,6 +35,7 @@ my $URL = 'https://www.eyrie.org/~eagle/software/web/'; # 1. Number of arguments or -1 to consume as many arguments as it can find. # 2. Name of the method to call with the arguments and (if wanted) format. # 3. Whether to look for a format in parens before the arguments. +#<<< my %COMMANDS = ( # name args method want_format block => [1, '_cmd_block', 1], @@ -81,6 +82,7 @@ my %COMMANDS = ( q{==} => [3, '_define_macro', 0], q{\\} => [0, '_literal', 0], ); +#>>> ############################################################################## # Input and output @@ -240,7 +242,7 @@ sub _paragraph { # Returns: Output to write to start the structure sub _border_start { my ($self, $border, $start, $end) = @_; - my $state = $self->{state}[-1]; + my $state = $self->{state}[-1]; my $output = q{}; # If we're at the top-level block structure or inside a structure other @@ -435,7 +437,7 @@ sub _expand { my ($blocktag, $output) = $self->$handler($format, @args); return ($output, $blocktag, $rest); } else { - my ($rest, @args) = $self->_extract($text, $args); + my ($rest, @args) = $self->_extract($text, $args); my ($blocktag, $output) = $self->$handler(@args); return ($output, $blocktag, $rest); } @@ -562,7 +564,7 @@ sub _parse_context { if ($blocktag) { if ($block && $paragraph ne q{}) { $output .= $border . $self->_paragraph($paragraph); - $border = q{}; + $border = q{}; $paragraph = q{}; } else { $output .= $space; @@ -644,6 +646,7 @@ sub _parse_document { my @input = reverse($self->_split_paragraphs($thread)); # Initialize object state for a new document. + #<<< $self->{input} = [[\@input, $in_path, 1]]; $self->{macro} = {}; $self->{out_fh} = $out_fh; @@ -652,6 +655,7 @@ sub _parse_document { $self->{space} = q{}; $self->{state} = ['BLOCK']; $self->{variable} = {}; + #>>> # Parse the thread file a paragraph at a time. _split_paragraphs takes # care of ensuring that each paragraph contains the complete value of a @@ -720,13 +724,13 @@ sub _split_paragraphs { # Pull paragraphs off the text one by one. while ($text ne q{} && $text =~ s{ \A ( .*? (?: \n\n+ | \s*\z ) )}{}xms) { - my $para = $1; - my $open_count = ($para =~ tr{\[}{}); + my $para = $1; + my $open_count = ($para =~ tr{\[}{}); my $close_count = ($para =~ tr{\]}{}); while ($text ne q{} && $open_count > $close_count) { if ($text =~ s{ \A ( .*? (?: \n\n+ | \s*\z ) )}{}xms) { my $extra = $1; - $open_count += ($extra =~ tr{\[}{}); + $open_count += ($extra =~ tr{\[}{}); $close_count += ($extra =~ tr{\]}{}); $para .= $extra; } else { @@ -769,7 +773,7 @@ sub _block { # Close the tag. The tag may have contained attributes, which aren't # allowed in the closing tag. - $tag =~ s{ [ ] .* }{}xms; + $tag =~ s{ [ ] .* }{}xms; $output =~ s{ \s* \z }{}xms; if ($format ne 'packed') { $output .= "\n"; @@ -915,6 +919,7 @@ sub _literal { return (0, q{\\}) } ############################################################################## # Basic inline commands. +#<<< sub _cmd_break { return (0, '
        ') } sub _cmd_bold { my ($self, @a) = @_; return $self->_inline('b', @a) } sub _cmd_cite { my ($self, @a) = @_; return $self->_inline('cite', @a) } @@ -927,6 +932,7 @@ sub _cmd_strong { my ($self, @a) = @_; return $self->_inline('strong', @a) } sub _cmd_sub { my ($self, @a) = @_; return $self->_inline('sub', @a) } sub _cmd_sup { my ($self, @a) = @_; return $self->_inline('sup', @a) } sub _cmd_under { my ($self, @a) = @_; return $self->_inline('u', @a) } +#>>> # The headings. sub _cmd_h1 { my ($self, @a) = @_; return $self->_heading(1, @a); } @@ -975,8 +981,8 @@ sub _cmd_desc { my ($self, $format, $heading, $text) = @_; $heading = $self->_parse($heading); my $format_attr = $self->_format_attr($format); - my $border = $self->_border_start('desc', "
        \n", "
        \n\n"); - my $initial = $border . "" . $heading . "\n"; + my $border = $self->_border_start('desc', "
        \n", "
        \n\n"); + my $initial = $border . "" . $heading . "\n"; return $self->_block('dd', $initial, $format, $text); } @@ -1084,7 +1090,7 @@ sub _cmd_heading { sub _cmd_image { my ($self, $format, $image, $text) = @_; $image = $self->_parse($image); - $text = $self->_parse($text); + $text = $self->_parse($text); # Determine the size attributes of the image if possible. my $size = -e $image ? q{ } . lc(html_imgsize($image)) : q{}; @@ -1102,7 +1108,7 @@ sub _cmd_include { $file = realpath($self->_parse($file)); # Read the thread, split it on paragraphs, and reverse it to make a stack. - my $thread = $self->_read_file($file); + my $thread = $self->_read_file($file); my @paragraphs = reverse($self->_split_paragraphs($thread)); # Add it to the file stack. @@ -1119,7 +1125,7 @@ sub _cmd_include { # $text - Anchor text sub _cmd_link { my ($self, $format, $url, $text) = @_; - $url = $self->_parse($url); + $url = $self->_parse($url); $text = $self->_parse($text); my $format_attr = $self->_format_attr($format); return (0, qq{$text}); @@ -1149,7 +1155,7 @@ sub _cmd_pre { sub _cmd_quote { my ($self, $format, $quote, $author, $cite) = @_; $author = $self->_parse($author); - $cite = $self->_parse($cite); + $cite = $self->_parse($cite); my $output = $self->_border_end() . q{
        }; # Parse the contents of the quote in a new block context. @@ -1223,7 +1229,7 @@ sub _cmd_release { # directly; the RSS feed information is used later in _cmd_heading. sub _cmd_rss { my ($self, $url, $title) = @_; - $url = $self->_parse($url); + $url = $self->_parse($url); $title = $self->_parse($title); push($self->{rss}->@*, [$url, $title]); return (1, q{}); @@ -1251,7 +1257,7 @@ sub _cmd_signature { } # Figure out the modification dates. Use the Git repository if available. - my $now = strftime('%Y-%m-%d', gmtime()); + my $now = strftime('%Y-%m-%d', gmtime()); my $modified = strftime('%Y-%m-%d', gmtime((stat($source))[9])); if ($self->{repository} && $self->{source}) { my $repository = $self->{repository}; @@ -1291,7 +1297,7 @@ sub _cmd_size { # Format the size using SI units. my @suffixes = qw(K M G T); - my $suffix = q{}; + my $suffix = q{}; while ($size > 1024 && @suffixes) { $size /= 1024; $suffix = shift(@suffixes); @@ -1395,6 +1401,7 @@ sub new { } # Create and return the object. + #<<< my $self = { output => $args_ref->{output}, repository => $repository, @@ -1403,6 +1410,7 @@ sub new { style_url => $style_url, versions => $args_ref->{versions}, }; + #>>> bless($self, $class); return $self; } @@ -1438,12 +1446,12 @@ sub spin_thread_file { # ensure that relative file references resolve properly. if (defined($input)) { my $path = realpath($input) or die "cannot canonicalize $input: $!\n"; - $input = $path; + $input = $path; $thread = slurp($input); my (undef, $input_dir) = fileparse($input); chdir($input_dir); } else { - $input = q{-}; + $input = q{-}; $thread = slurp(\*STDIN); } diff --git a/lib/App/DocKnot/Spin/Versions.pm b/lib/App/DocKnot/Spin/Versions.pm index b804b08..9aa07f2 100644 --- a/lib/App/DocKnot/Spin/Versions.pm +++ b/lib/App/DocKnot/Spin/Versions.pm @@ -84,9 +84,9 @@ sub _read_data { if (!defined($time)) { die "invalid line $. in $path\n"; } - @depends = @files; + @depends = @files; $timestamp = _datetime_to_seconds($date, $time, $path); - $date = strftime('%Y-%m-%d', gmtime($timestamp)); + $date = strftime('%Y-%m-%d', gmtime($timestamp)); $self->{versions}{$package} = [$version, $date]; } @@ -120,7 +120,7 @@ sub new { # Create an empty object. my $self = { - depends => {}, + depends => {}, versions => {}, }; bless($self, $class); diff --git a/lib/App/DocKnot/Update.pm b/lib/App/DocKnot/Update.pm index ad8eb4d..7cb2c1d 100644 --- a/lib/App/DocKnot/Update.pm +++ b/lib/App/DocKnot/Update.pm @@ -136,8 +136,8 @@ sub _config_from_json { eval { $data_ref->{license}{notices} = $self->_load_metadata('notices') }; # Load the standard sections. - $data_ref->{blurb} = $self->_load_metadata('blurb'); - $data_ref->{description} = $self->_load_metadata('description'); + $data_ref->{blurb} = $self->_load_metadata('blurb'); + $data_ref->{description} = $self->_load_metadata('description'); $data_ref->{requirements} = $self->_load_metadata('requirements'); # Load optional information if it exists. @@ -182,7 +182,7 @@ sub new { # Create and return the object. my $self = { metadata => $metadata, - output => $args_ref->{output} // 'docs/docknot.yaml', + output => $args_ref->{output} // 'docs/docknot.yaml', }; bless($self, $class); return $self; @@ -265,7 +265,7 @@ sub update { # Check the schema of the resulting file. my $schema_path = $self->appdata_path('schema/docknot.yaml'); - my $schema_ref = YAML::XS::LoadFile($schema_path); + my $schema_ref = YAML::XS::LoadFile($schema_path); eval { validate($schema_ref, $data_ref) }; if ($@) { my $errors = $@; diff --git a/lib/App/DocKnot/Util.pm b/lib/App/DocKnot/Util.pm index a72b37a..72302b0 100644 --- a/lib/App/DocKnot/Util.pm +++ b/lib/App/DocKnot/Util.pm @@ -34,7 +34,7 @@ our @EXPORT_OK = qw(is_newer print_checked print_fh); sub is_newer { my ($file, @others) = @_; return if !-e $file; - my $file_mtime = (stat($file))[9]; + my $file_mtime = (stat($file))[9]; my @others_mtimes = map { (stat)[9] } @others; return all { $file_mtime >= $_ } @others_mtimes; } diff --git a/t/cli/generate.t b/t/cli/generate.t index 38c8b2e..87c8f68 100755 --- a/t/cli/generate.t +++ b/t/cli/generate.t @@ -39,7 +39,7 @@ my $tempdir = File::Temp->newdir(); # generate/self.t test, but via the command-line parser. Do this in a # separate block so that $tempfile goes out of scope and will be cleaned up. { - my $tempfile = File::Temp->new(DIR => $tempdir); + my $tempfile = File::Temp->new(DIR => $tempdir); my $output_path = $tempfile->filename; $docknot->run('generate', 'readme', $output_path); my $output = slurp($output_path); @@ -48,7 +48,7 @@ my $tempdir = File::Temp->newdir(); # Do the same thing again, but using arguments from @ARGV. { - my $tempfile = File::Temp->new(DIR => $tempdir); + my $tempfile = File::Temp->new(DIR => $tempdir); my $output_path = $tempfile->filename; local @ARGV = ('generate', 'readme-md', "$output_path"); $docknot->run(); @@ -57,9 +57,9 @@ my $tempdir = File::Temp->newdir(); } # Save the paths to various files in the source directory. -my $readme_path = File::Spec->catfile(getcwd(), 'README'); +my $readme_path = File::Spec->catfile(getcwd(), 'README'); my $readme_md_path = File::Spec->catfile(getcwd(), 'README.md'); -my $metadata_path = File::Spec->catfile(getcwd(), 'docs', 'docknot.yaml'); +my $metadata_path = File::Spec->catfile(getcwd(), 'docs', 'docknot.yaml'); # Generate all of the files using generate-all in a new temporary directory. my $tmpdir = File::Temp->newdir(); diff --git a/t/cli/spin.t b/t/cli/spin.t index 674047f..58bf2f7 100755 --- a/t/cli/spin.t +++ b/t/cli/spin.t @@ -39,10 +39,10 @@ isa_ok($docknot, 'App::DocKnot::Command'); my $tempdir = File::Temp->newdir(); # Spin a single file. -my $datadir = File::Spec->catfile('t', 'data', 'spin'); -my $input = File::Spec->catfile($datadir, 'input', 'index.th'); +my $datadir = File::Spec->catfile('t', 'data', 'spin'); +my $input = File::Spec->catfile($datadir, 'input', 'index.th'); my $expected = File::Spec->catfile($datadir, 'output', 'index.html'); -my $output = File::Spec->catfile($tempdir->dirname, 'index.html'); +my $output = File::Spec->catfile($tempdir->dirname, 'index.html'); $docknot->run('spin-thread', '-s', '/~eagle/styles', $input, $output); is_spin_output($output, $expected, 'spin-thread (output specified)'); @@ -63,7 +63,7 @@ $input = File::Spec->catfile($datadir, 'input'); dircopy($input, $indir->dirname) or die "Cannot copy $input to $indir: $!\n"; my $rpod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); -my $rpod_path = File::Spec->catfile( +my $rpod_path = File::Spec->catfile( $indir->dirname, 'software', 'docknot', 'api', 'app-docknot.rpod', ); diff --git a/t/config/basic.t b/t/config/basic.t index 018ece6..87cd0c5 100755 --- a/t/config/basic.t +++ b/t/config/basic.t @@ -35,8 +35,8 @@ my $data_ref = $config->config(); ok($data_ref->{build}{install}, 'build/install defaults to true'); # Check that the license data is expanded correctly. -my $licenses_path = module_file('App::DocKnot', 'licenses.yaml'); -my $licenses_ref = YAML::XS::LoadFile($licenses_path); +my $licenses_path = module_file('App::DocKnot', 'licenses.yaml'); +my $licenses_ref = YAML::XS::LoadFile($licenses_path); my $perl_license_ref = $licenses_ref->{Perl}; is($data_ref->{license}{summary}, $perl_license_ref->{summary}, 'summary'); -is($data_ref->{license}{text}, $perl_license_ref->{text}, 'text'); +is($data_ref->{license}{text}, $perl_license_ref->{text}, 'text'); diff --git a/t/data/dist/package/Build.PL b/t/data/dist/package/Build.PL index b50f458..84edf47 100755 --- a/t/data/dist/package/Build.PL +++ b/t/data/dist/package/Build.PL @@ -14,6 +14,7 @@ use warnings; use Module::Build; +#<<< my $build = Module::Build->new( dist_abstract => 'Empty test module', dist_author => 'Russ Allbery ', @@ -23,4 +24,5 @@ my $build = Module::Build->new( add_to_cleanup => [qw(MANIFEST.bak MYMETA.json.lock cover_db)], configure_requires => { 'Module::Build' => 0.36 }, ); +#>>> $build->create_build_script; diff --git a/t/data/perltidyrc b/t/data/perltidyrc index f5a08b5..62623c9 100644 --- a/t/data/perltidyrc +++ b/t/data/perltidyrc @@ -18,11 +18,13 @@ # SPDX-License-Identifier: FSFAP -bbao # put line breaks before any operator --boc # do not re-break lists, since perltidy is awful at this -nbbc # don't force blank lines before comments (bad for else blocks) +-nbl # keep opening braces on the same line +-boc # do not re-break lists, since perltidy is awful at this -ce # cuddle braces around else -l=79 # usually use 78, but don't want 79-long lines reformatted -pt=2 # don't add extra whitespace around parentheses -sbt=2 # ...or square brackets -sfs # no space before semicolon in for (not that I use this form) +-nvc # disable vertical alignment of = and similar symbols -xci # improve indentation of nested structures diff --git a/t/data/regenerate-data b/t/data/regenerate-data index 9037170..b95b87f 100755 --- a/t/data/regenerate-data +++ b/t/data/regenerate-data @@ -51,9 +51,9 @@ for my $package (@packages) { # The test of spinning a tree of files uses a reference to App::DocKnot's own # POD documentation. Regenerate the expected output in case the POD has # changed. -my $source = File::Spec->catdir('lib', 'App', 'DocKnot.pm'); +my $source = File::Spec->catdir('lib', 'App', 'DocKnot.pm'); my $podthread = Pod::Thread->new(navbar => 1); -my $spin = App::DocKnot::Spin::Thread->new(); +my $spin = App::DocKnot::Spin::Thread->new(); my $thread; $podthread->output_string(\$thread); $podthread->parse_file($source); @@ -68,7 +68,7 @@ my $links = <<'EOD'; EOD my $comment = ''; -my $navbar = <<'EOD'; +my $navbar = <<'EOD';
        @@ -93,7 +93,7 @@ $html =~ s{ () }{$navbar$address$1}xms; # Replace the expected data file. my $output = File::Spec->catdir( - 't', 'data', 'spin', 'output', 'software', 'docknot', + 't', 'data', 'spin', 'output', 'software', 'docknot', 'api', 'app-docknot.html', ); open(my $fh, '>', $output); diff --git a/t/dist/basic.t b/t/dist/basic.t index 319b5cb..6fcf2bc 100755 --- a/t/dist/basic.t +++ b/t/dist/basic.t @@ -28,14 +28,14 @@ local $ENV{XDG_CONFIG_HOME} = '/nonexistent'; local $ENV{XDG_CONFIG_DIRS} = '/nonexistent'; # Find the full path to the test data. -my $cwd = getcwd() or die "$0: cannot get working directory: $!\n"; +my $cwd = getcwd() or die "$0: cannot get working directory: $!\n"; my $dataroot = File::Spec->catfile($cwd, 't', 'data', 'dist', 'package'); my $gpg_path = File::Spec->catfile($cwd, 't', 'data', 'dist', 'fake-gpg'); # Set up a temporary directory. -my $dir = File::Temp->newdir(); +my $dir = File::Temp->newdir(); my $sourcedir = File::Spec->catfile($dir, 'source'); -my $distdir = File::Spec->catfile($dir, 'dist'); +my $distdir = File::Spec->catfile($dir, 'dist'); # Create a new repository, copy all files from the data directory, and commit # them. We have to rename the test while we copy it to avoid having it picked @@ -46,10 +46,10 @@ my $testpath = File::Spec->catfile($sourcedir, 't', 'api', 'empty.t'); rename($testpath . '.in', $testpath); Git::Repository->run('init', { cwd => $sourcedir, quiet => 1 }); my $repo = Git::Repository->new(work_tree => $sourcedir); -$repo->run(config => '--add', 'user.name', 'Test'); +$repo->run(config => '--add', 'user.name', 'Test'); $repo->run(config => '--add', 'user.email', 'test@example.com'); -$repo->run(add => '-A', q{.}); -$repo->run(commit => '-q', '-m', 'Initial commit'); +$repo->run(add => '-A', q{.}); +$repo->run(commit => '-q', '-m', 'Initial commit'); # Check whether we have all the necessary tools to run the test. my $result; @@ -83,9 +83,9 @@ my $dist = App::DocKnot::Dist->new({ distdir => $distdir, perl => $^X }); capture_stdout { eval { $dist->make_distribution() }; }; -ok(-e File::Spec->catfile($distdir, 'Empty-1.00.tar.gz'), 'dist exists'); -ok(-e File::Spec->catfile($distdir, 'Empty-1.00.tar.xz'), 'xz dist exists'); -ok(!-e File::Spec->catfile($distdir, 'Empty-1.00.tar'), 'tarball missing'); +ok(-e File::Spec->catfile($distdir, 'Empty-1.00.tar.gz'), 'dist exists'); +ok(-e File::Spec->catfile($distdir, 'Empty-1.00.tar.xz'), 'xz dist exists'); +ok(!-e File::Spec->catfile($distdir, 'Empty-1.00.tar'), 'tarball missing'); ok(!-e File::Spec->catfile($distdir, 'Empty-1.00.tar.gz.asc'), 'no signature'); ok(!-e File::Spec->catfile($distdir, 'Empty-1.00.tar.xz.asc'), 'no signature'); is($@, q{}, 'no errors'); @@ -145,7 +145,7 @@ $stdout = capture_stdout { eval { $dist->make_distribution() }; }; is($@, "2 files missing from distribution\n", 'correct error for two files'); -like($stdout, qr{ some-file }xms, 'output mentions the first file'); +like($stdout, qr{ some-file }xms, 'output mentions the first file'); like($stdout, qr{ another-file }xms, 'output mentions the other file'); @missing = $dist->check_dist($sourcedir, $tarball); is_deeply(['another-file', 'some-file'], \@missing, 'check_dist matches'); diff --git a/t/dist/commands.t b/t/dist/commands.t index cbd29c3..9ca697c 100755 --- a/t/dist/commands.t +++ b/t/dist/commands.t @@ -119,5 +119,5 @@ $metadata_path $docknot = App::DocKnot::Dist->new({ distdir => q{.}, metadata => $metadata_path }); @expected = (['make', 'dist']); -@seen = $docknot->commands(); +@seen = $docknot->commands(); is_deeply(\@seen, \@expected, 'make'); diff --git a/t/docs/spdx-license.t b/t/docs/spdx-license.t index 4e5b7f9..15ee7e0 100755 --- a/t/docs/spdx-license.t +++ b/t/docs/spdx-license.t @@ -45,8 +45,9 @@ use Test::More; # File name (the file without any directory component) and path patterns to # skip for this check. ## no critic (RegularExpressions::ProhibitFixedStringMatches) +#<<< my @IGNORE = ( - qr{ \A Build ( [.] (?!PL) .* )? \z }ixms, # Generated file from Build.PL + qr{ \A Build ( [.] (?!PL) .* )? \z }ixms, # Generated file from Build.PL qr{ \A LICENSE \z }xms, # Generated file, no license itself qr{ \A (Changes|NEWS|THANKS) \z }xms, # Package license should be fine qr{ \A TODO \z }xms, # Package license should be fine @@ -58,20 +59,21 @@ my @IGNORE = ( qr{ ~ \z }xms, # Backup files ); my @IGNORE_PATHS = ( - qr{ \A [.] / [.] git/ }xms, # Version control files - qr{ \A [.] / [.] pc/ }xms, # quilt metadata files - qr{ \A [.] /_build/ }xms, # Module::Build metadata - qr{ \A [.] /blib/ }xms, # Perl build system artifacts - qr{ \A [.] /cover_db/ }xms, # Artifacts from coverage testing - qr{ \A [.] /debian/ }xms, # Found in debian/* branches - qr{ \A [.] /docs/metadata/ }xms, # Package license should be fine - qr{ \A [.] /README ( [.] .* )? \z }xms, # Package license should be fine - qr{ \A [.] /share/ }xms, # Package license should be fine - qr{ \A [.] /t/data/generate/ }xms, # Test metadata - qr{ \A [.] /t/data/spin/ }xms, # Test metadata - qr{ \A [.] /t/data/update/ }xms, # Test output - qr{ \A [.] /t/data .* [.] json \z }xms, # Test metadata + qr{ \A [.] / [.] git/ }xms, # Version control files + qr{ \A [.] / [.] pc/ }xms, # quilt metadata files + qr{ \A [.] /_build/ }xms, # Module::Build metadata + qr{ \A [.] /blib/ }xms, # Perl build system artifacts + qr{ \A [.] /cover_db/ }xms, # Artifacts from coverage testing + qr{ \A [.] /debian/ }xms, # Found in debian/* branches + qr{ \A [.] /docs/metadata/ }xms, # Package license should be fine + qr{ \A [.] /README ( [.] .* )? \z }xms, # Package license should be fine + qr{ \A [.] /share/ }xms, # Package license should be fine + qr{ \A [.] /t/data/generate/ }xms, # Test metadata + qr{ \A [.] /t/data/spin/ }xms, # Test metadata + qr{ \A [.] /t/data/update/ }xms, # Test output + qr{ \A [.] /t/data .* [.] json \z }xms, # Test metadata ); +#>>> ## use critic # Only run this test during automated testing, since failure doesn't indicate @@ -85,7 +87,7 @@ skip_unless_automated('SPDX identifier tests'); # Returns: undef sub check_file { my $filename = $_; - my $path = $File::Find::name; + my $path = $File::Find::name; # Ignore files in the whitelist and binary files. for my $pattern (@IGNORE) { diff --git a/t/generate/basic.t b/t/generate/basic.t index f553e20..20af8b0 100755 --- a/t/generate/basic.t +++ b/t/generate/basic.t @@ -43,7 +43,7 @@ for my $test (@tests) { # Loop through the possible templates. for my $template (qw(readme readme-md thread)) { - my $got = encode('utf-8', $docknot->generate($template)); + my $got = encode('utf-8', $docknot->generate($template)); my $path = File::Spec->catfile($dataroot, $test, 'output', $template); is_file_contents($got, $path, "$template for $test"); } diff --git a/t/generate/output.t b/t/generate/output.t index c23538e..2a66451 100755 --- a/t/generate/output.t +++ b/t/generate/output.t @@ -34,11 +34,11 @@ my $docknot = App::DocKnot::Generate->new({ metadata => $metadata_path }); isa_ok($docknot, 'App::DocKnot::Generate'); # Save the paths to the real README and README.md files. -my $readme_path = File::Spec->catfile(getcwd(), 'README'); +my $readme_path = File::Spec->catfile(getcwd(), 'README'); my $readme_md_path = File::Spec->catfile(getcwd(), 'README.md'); # Write the README output for the DocKnot package to a temporary file. -my $tmp = File::Temp->new(); +my $tmp = File::Temp->new(); my $tmpname = $tmp->filename; $docknot->generate_output('readme', $tmpname); my $output = slurp($tmpname); diff --git a/t/lib/Test/RRA.pm b/t/lib/Test/RRA.pm index 1a3ceab..56417c4 100644 --- a/t/lib/Test/RRA.pm +++ b/t/lib/Test/RRA.pm @@ -83,11 +83,11 @@ sub is_file_contents { eval { require IPC::System::Simple; - my $tmp = File::Temp->new(); + my $tmp = File::Temp->new(); my $tmpname = $tmp->filename; print {$tmp} $got or BAIL_OUT("Cannot write to $tmpname: $!\n"); my @command = ('diff', '-u', $expected, $tmpname); - my $diff = IPC::System::Simple::capturex([0 .. 1], @command); + my $diff = IPC::System::Simple::capturex([0 .. 1], @command); diag($diff); }; if ($@) { @@ -165,15 +165,15 @@ sub use_prereq { ## no critic (ValuesAndExpressions::ProhibitImplicitNewlines) my ($result, $error, $sigdie); { - local $@ = undef; - local $! = undef; + local $@ = undef; + local $! = undef; local $SIG{__DIE__} = undef; $result = eval qq{ package $package; use $module $version \@imports; 1; }; - $error = $@; + $error = $@; $sigdie = $SIG{__DIE__} || undef; } diff --git a/t/lib/Test/RRA/ModuleVersion.pm b/t/lib/Test/RRA/ModuleVersion.pm index 86bd9f1..18f3ae1 100644 --- a/t/lib/Test/RRA/ModuleVersion.pm +++ b/t/lib/Test/RRA/ModuleVersion.pm @@ -135,7 +135,7 @@ sub _update_module_version { } # Scan for the version and replace it. - open(my $in, q{<}, $file) or die "$0: cannot open $file: $!\n"; + open(my $in, q{<}, $file) or die "$0: cannot open $file: $!\n"; open(my $out, q{>}, "$file.new") or die "$0: cannot create $file.new: $!\n"; SCAN: @@ -151,8 +151,8 @@ sub _update_module_version { # Copy the rest of the input file to the output file. print {$out} <$in> or die "$0: cannot write to $file.new: $!\n"; - close($out) or die "$0: cannot flush $file.new: $!\n"; - close($in) or die "$0: error reading from $file: $!\n"; + close($out) or die "$0: cannot flush $file.new: $!\n"; + close($in) or die "$0: error reading from $file: $!\n"; # All done. Rename the new file over top of the old file. rename("$file.new", $file) diff --git a/t/metadata/licenses.t b/t/metadata/licenses.t index 422dbd3..94e6c50 100755 --- a/t/metadata/licenses.t +++ b/t/metadata/licenses.t @@ -24,8 +24,8 @@ BEGIN { use_ok('App::DocKnot') } # Check the schema of the licenses.yaml file. my $licenses_path = module_file('App::DocKnot', 'licenses.yaml'); -my $licenses_ref = YAML::XS::LoadFile($licenses_path); -my $schema_path = module_file('App::DocKnot', 'schema/licenses.yaml'); -my $schema_ref = YAML::XS::LoadFile($schema_path); +my $licenses_ref = YAML::XS::LoadFile($licenses_path); +my $schema_path = module_file('App::DocKnot', 'schema/licenses.yaml'); +my $schema_ref = YAML::XS::LoadFile($schema_path); eval { validate($schema_ref, $licenses_ref) }; is($@, q{}, 'licenses.yaml fails schema validation'); diff --git a/t/spin/errors.t b/t/spin/errors.t index ae1c308..d4cc565 100755 --- a/t/spin/errors.t +++ b/t/spin/errors.t @@ -36,7 +36,7 @@ require_ok('App::DocKnot::Spin::Thread'); # Spin the errors file with output captured. my $input = File::Spec->catfile('t', 'data', 'spin', 'errors', 'errors.th'); -my $spin = App::DocKnot::Spin::Thread->new(); +my $spin = App::DocKnot::Spin::Thread->new(); my ($stdout, $stderr) = capture { $spin->spin_thread_file($input); }; diff --git a/t/spin/file.t b/t/spin/file.t index 354ec77..2f645e5 100755 --- a/t/spin/file.t +++ b/t/spin/file.t @@ -26,10 +26,10 @@ require_ok('App::DocKnot::Spin::Thread'); # Spin a single file. my $tempfile = File::Temp->new(); -my $datadir = File::Spec->catfile('t', 'data', 'spin'); -my $inputdir = File::Spec->catfile($datadir, 'input'); -my $input = File::Spec->catfile($inputdir, 'index.th'); -my $expected = File::Spec->catfile($datadir, 'output', 'index.html'); +my $datadir = File::Spec->catfile('t', 'data', 'spin'); +my $inputdir = File::Spec->catfile($datadir, 'input'); +my $input = File::Spec->catfile($inputdir, 'index.th'); +my $expected = File::Spec->catfile($datadir, 'output', 'index.html'); my $spin = App::DocKnot::Spin::Thread->new({ 'style-url' => '/~eagle/styles/' }); $spin->spin_thread_file($input, $tempfile->filename); diff --git a/t/spin/markdown.t b/t/spin/markdown.t index 7b098bb..bf8de61 100755 --- a/t/spin/markdown.t +++ b/t/spin/markdown.t @@ -38,19 +38,19 @@ require_ok('App::DocKnot::Spin::Pointer'); # Ensure Devel::Cover has loaded the HTML template before we start changing # the working directory with File::Find. (This is a dumb workaround, but I # can't find a better one; +ignore doesn't work.) -my $pointer = App::DocKnot::Spin::Pointer->new(); +my $pointer = App::DocKnot::Spin::Pointer->new(); my $template = $pointer->appdata_path('templates', 'html.tmpl'); -my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); +my $tt = Template->new({ ABSOLUTE => 1 }) or croak(Template->error()); $tt->process($template, {}, \my $result); # Spin the tree of files and check the result. -my $datadir = File::Spec->catfile('t', 'data', 'spin', 'markdown'); -my $input = File::Spec->catfile($datadir, 'input'); -my $output = File::Temp->newdir(); +my $datadir = File::Spec->catfile('t', 'data', 'spin', 'markdown'); +my $input = File::Spec->catfile($datadir, 'input'); +my $output = File::Temp->newdir(); my $expected = File::Spec->catfile($datadir, 'output'); -my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' }); -my $stdout = capture_stdout { $spin->spin($input, $output->dirname) }; -my $count = is_spin_output_tree($output, $expected, 'spin'); +my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' }); +my $stdout = capture_stdout { $spin->spin($input, $output->dirname) }; +my $count = is_spin_output_tree($output, $expected, 'spin'); # Report the end of testing. done_testing($count + 2); diff --git a/t/spin/sitemap.t b/t/spin/sitemap.t index 0ae949c..59f8fe3 100755 --- a/t/spin/sitemap.t +++ b/t/spin/sitemap.t @@ -21,12 +21,12 @@ require_ok('App::DocKnot::Spin::Sitemap'); # Parse a complex .sitemap file. my $datadir = File::Spec->catfile('t', 'data', 'spin', 'sitemap'); -my $path = File::Spec->catfile($datadir, 'complex'); +my $path = File::Spec->catfile($datadir, 'complex'); my $sitemap = App::DocKnot::Spin::Sitemap->new($path); isa_ok($sitemap, 'App::DocKnot::Spin::Sitemap'); # Check the generated sitemap. -my $output = join(q{}, $sitemap->sitemap()); +my $output = join(q{}, $sitemap->sitemap()); my $expected = File::Spec->catfile($datadir, 'complex.html'); is_file_contents($output, $expected, 'sitemap output'); @@ -46,7 +46,7 @@ my @expected = ( qq{ \n}, ); is_deeply(\@links, \@expected, 'links output'); -@navbar = $sitemap->navbar('/faqs/soundness-inn.html'); +@navbar = $sitemap->navbar('/faqs/soundness-inn.html'); @expected = ( qq{\n}, qq{ \n}, @@ -61,7 +61,7 @@ is_deeply(\@links, \@expected, 'links output'); is_deeply(\@navbar, \@expected, 'navbar output'); # Check links for a page with long adjacent titles to test the wrapping. -@links = $sitemap->links('/notes/cvs/basic-usage.html'); +@links = $sitemap->links('/notes/cvs/basic-usage.html'); @expected = ( qq{ \n}, diff --git a/t/spin/thread.t b/t/spin/thread.t index 8373eba..c18a743 100755 --- a/t/spin/thread.t +++ b/t/spin/thread.t @@ -23,16 +23,16 @@ use Test::More tests => 2; require_ok('App::DocKnot::Spin::Thread'); # Test data file paths. -my $datadir = File::Spec->catfile('t', 'data', 'spin'); -my $inputdir = File::Spec->catfile($datadir, 'input'); -my $input = File::Spec->catfile($inputdir, 'index.th'); -my $expected = File::Spec->catfile($datadir, 'output', 'index.html'); +my $datadir = File::Spec->catfile('t', 'data', 'spin'); +my $inputdir = File::Spec->catfile($datadir, 'input'); +my $input = File::Spec->catfile($inputdir, 'index.th'); +my $expected = File::Spec->catfile($datadir, 'output', 'index.html'); # The expected output is a bit different since we won't add timestamp # information or the filename to the comment, so we have to generate our # expected output file. my $tempfile = File::Temp->new(); -my $output = slurp($expected); +my $output = slurp($expected); $output =~ s{ from [ ] index[.]th [ ] }{}xms; $output =~ s{
        .*
        \n }{}xms; print {$tempfile} $output or die "Cannot write to $tempfile: $!\n"; @@ -43,7 +43,7 @@ $tempfile->flush(); my $spin = App::DocKnot::Spin::Thread->new({ 'style-url' => '/~eagle/styles/' }); my $thread = slurp($input); -my $cwd = getcwd(); +my $cwd = getcwd(); chdir($inputdir); my $html = $spin->spin_thread($thread); chdir($cwd); diff --git a/t/spin/tree.t b/t/spin/tree.t index b3bf302..2a173a7 100755 --- a/t/spin/tree.t +++ b/t/spin/tree.t @@ -72,13 +72,13 @@ require_ok('App::DocKnot::Spin'); # additional thread files. Replace the rpod pointer since it points to a # relative path in the source tree, but change its modification timestamp to # something in the past. -my $tmpdir = File::Temp->newdir(); +my $tmpdir = File::Temp->newdir(); my $datadir = File::Spec->catfile('t', 'data', 'spin'); -my $input = File::Spec->catfile($datadir, 'input'); +my $input = File::Spec->catfile($datadir, 'input'); dircopy($input, $tmpdir->dirname) or die "Cannot copy $input to $tmpdir: $!\n"; my $rpod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); -my $rpod_path = File::Spec->catfile( +my $rpod_path = File::Spec->catfile( $tmpdir->dirname, 'software', 'docknot', 'api', 'app-docknot.rpod', ); @@ -89,18 +89,18 @@ close($fh); my $old_timestamp = time() - 10; # Spin a tree of files. -my $output = File::Temp->newdir(); +my $output = File::Temp->newdir(); my $expected = File::Spec->catfile($datadir, 'output'); -my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' }); -my $stdout = capture_stdout { +my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' }); +my $stdout = capture_stdout { $spin->spin($tmpdir->dirname, $output->dirname); }; my $count = is_spin_output_tree($output, $expected, 'spin'); is($stdout, $EXPECTED_OUTPUT, 'Expected spin output'); # Create a bogus file in the output tree. -my $bogus = File::Spec->catfile($output->dirname, 'bogus'); -my $bogus_file = File::Spec->catfile($bogus, 'some-file'); +my $bogus = File::Spec->catfile($output->dirname, 'bogus'); +my $bogus_file = File::Spec->catfile($bogus, 'some-file'); mkdir($bogus); open($fh, '>', $bogus_file); print {$fh} "Some stuff\n" or die "Cannot write to $bogus_file: $!\n"; @@ -154,7 +154,7 @@ like( qr{ New [ ] Title }xms, 'POD title override worked', ); -like($page, qr{

        New [ ] Title

        }xms, 'POD h1 override worked'); +like($page, qr{

        New [ ] Title

        }xms, 'POD h1 override worked'); like($page, qr{ Table [ ] of [ ] Contents }xms, 'POD table of contents'); # Set the time back so that it won't be generated again. @@ -165,8 +165,8 @@ utime(time() - 5, time() - 5, $rpod_path) # timestamp to ten seconds into the future. This should force regeneration of # only the software/docknot/index.html file. my $versions_path = File::Spec->catfile($tmpdir->dirname, '.versions'); -my $versions = slurp($versions_path); -my $new_date = strftime('%Y-%m-%d %T', localtime(time() + 10)); +my $versions = slurp($versions_path); +my $new_date = strftime('%Y-%m-%d %T', localtime(time() + 10)); $versions =~ s{ \d{4}-\d\d-\d\d [ ] [\d:]+ }{$new_date}xms; chmod(0644, $versions_path); open(my $versions_fh, '>', $versions_path); diff --git a/t/spin/versions.t b/t/spin/versions.t index 03230c8..640e143 100755 --- a/t/spin/versions.t +++ b/t/spin/versions.t @@ -24,12 +24,12 @@ local $ENV{TZ} = 'America/Los_Angeles'; tzset(); # Parse the file. -my $path = File::Spec->catfile('t', 'data', 'spin', 'input', '.versions'); +my $path = File::Spec->catfile('t', 'data', 'spin', 'input', '.versions'); my $versions = App::DocKnot::Spin::Versions->new($path); isa_ok($versions, 'App::DocKnot::Spin::Versions'); # Check the resulting information. -is($versions->version('docknot'), '4.01', 'docknot version'); +is($versions->version('docknot'), '4.01', 'docknot version'); is($versions->release_date('docknot'), '2021-02-27', 'docknot release date'); is( $versions->latest_release('software/docknot/index.th'), 1614460092, @@ -37,17 +37,17 @@ is( ); # Unknown products or files. -is($versions->version('unknown'), undef, 'unknown version'); -is($versions->release_date('unknown'), undef, 'unknown release date'); -is($versions->latest_release('index.th'), 0, 'unknown file index.th'); +is($versions->version('unknown'), undef, 'unknown version'); +is($versions->release_date('unknown'), undef, 'unknown release date'); +is($versions->latest_release('index.th'), 0, 'unknown file index.th'); # Check continuation handling and a line without dependencies. my $inputdir = File::Spec->catfile('t', 'data', 'spin', 'versions'); -$path = File::Spec->catfile($inputdir, 'continuation'); +$path = File::Spec->catfile($inputdir, 'continuation'); $versions = App::DocKnot::Spin::Versions->new($path); -is($versions->version('docknot'), '4.01', 'docknot version'); -is($versions->release_date('docknot'), '2021-02-27', 'docknot release date'); -is($versions->version('other-package'), '1.00', 'other-package version'); +is($versions->version('docknot'), '4.01', 'docknot version'); +is($versions->release_date('docknot'), '2021-02-27', 'docknot release date'); +is($versions->version('other-package'), '1.00', 'other-package version'); is( $versions->release_date('other-package'), '2021-09-07', 'other-package release date', diff --git a/t/style/coverage.t b/t/style/coverage.t index 6cb4c22..ae709fb 100755 --- a/t/style/coverage.t +++ b/t/style/coverage.t @@ -54,9 +54,9 @@ use_prereq('Test::Strict'); # Build a list of test directories to use for coverage. my %ignore = map { $_ => 1 } qw(config data docs lib style), @COVERAGE_SKIP_TESTS; -opendir(my $testdir, 't') or BAIL_OUT("cannot open t: $!"); +opendir(my $testdir, 't') or BAIL_OUT("cannot open t: $!"); my @t_dirs = readdir($testdir) or BAIL_OUT("cannot read t: $!"); -closedir($testdir) or BAIL_OUT("cannot close t: $!"); +closedir($testdir) or BAIL_OUT("cannot close t: $!"); # Filter out ignored and system directories. @t_dirs = grep { !$ignore{$_} } File::Spec->no_upwards(@t_dirs); diff --git a/t/style/module-version.t b/t/style/module-version.t index 0d78c3d..8339da5 100755 --- a/t/style/module-version.t +++ b/t/style/module-version.t @@ -42,9 +42,9 @@ if (@ARGV) { # Throws: Text exception if MYMETA.json is not found or doesn't contain a # version sub dist_version { - my $json = JSON::PP->new->utf8(1); + my $json = JSON::PP->new->utf8(1); my $metadata = $json->decode(scalar(slurp('MYMETA.json'))); - my $version = $metadata->{version}; + my $version = $metadata->{version}; if (!defined($version)) { die "$0: cannot find version number in MYMETA.json\n"; } diff --git a/t/style/strict.t b/t/style/strict.t index b83d348..8b92fb5 100755 --- a/t/style/strict.t +++ b/t/style/strict.t @@ -59,7 +59,7 @@ my %EXCLUDE = map { $_ => 1 } qw(.git blib); # Returns: 1 if it should be checked, undef otherwise. sub should_check { my ($file) = @_; - return if $EXCLUDE{$file}; + return if $EXCLUDE{$file}; return 1 if -d $file; return 1 if $file =~ m{ [.] PL \z }xms; return; diff --git a/t/update/basic.t b/t/update/basic.t index a21343f..5dc2be1 100755 --- a/t/update/basic.t +++ b/t/update/basic.t @@ -39,11 +39,11 @@ my $tempdir = File::Temp->newdir(); for my $test (@tests) { my $metadata_path = File::Spec->catfile($dataroot, $test, 'old'); my $expected_path = File::Spec->catfile($dataroot, $test, 'docknot.yaml'); - my $output_path = File::Spec->catfile($tempdir, "$test.yaml"); - my $docknot = App::DocKnot::Update->new( + my $output_path = File::Spec->catfile($tempdir, "$test.yaml"); + my $docknot = App::DocKnot::Update->new( { metadata => $metadata_path, - output => $output_path, + output => $output_path, }, ); isa_ok($docknot, 'App::DocKnot::Update', "for $test"); -- cgit v1.2.3 From 84b08d2f67f6a49b6bbfaa720d347e0dd4ba5185 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 11:12:12 -0800 Subject: Update to rra-c-util 10.1 --- t/data/perltidyrc | 1 - t/docs/changes.t | 2 +- t/docs/pod-coverage.t | 4 ++-- t/docs/pod-spelling.t | 2 +- t/docs/pod.t | 2 +- t/docs/synopsis.t | 4 ++-- t/lib/Test/RRA.pm | 4 ++-- t/lib/Test/RRA/Config.pm | 8 ++++---- t/lib/Test/RRA/ModuleVersion.pm | 2 +- t/style/coverage.t | 2 +- t/style/critic.t | 2 +- t/style/minimum-version.t | 4 ++-- t/style/module-version.t | 4 ++-- t/style/strict.t | 4 ++-- 14 files changed, 22 insertions(+), 23 deletions(-) diff --git a/t/data/perltidyrc b/t/data/perltidyrc index 62623c9..431c311 100644 --- a/t/data/perltidyrc +++ b/t/data/perltidyrc @@ -19,7 +19,6 @@ -bbao # put line breaks before any operator -nbbc # don't force blank lines before comments (bad for else blocks) --nbl # keep opening braces on the same line -boc # do not re-break lists, since perltidy is awful at this -ce # cuddle braces around else -l=79 # usually use 78, but don't want 79-long lines reformatted diff --git a/t/docs/changes.t b/t/docs/changes.t index 16bf212..94b8000 100755 --- a/t/docs/changes.t +++ b/t/docs/changes.t @@ -27,7 +27,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/docs/pod-coverage.t b/t/docs/pod-coverage.t index 198f4e7..c499af3 100755 --- a/t/docs/pod-coverage.t +++ b/t/docs/pod-coverage.t @@ -6,7 +6,7 @@ # which can be found at . # # Written by Russ Allbery -# Copyright 2019 Russ Allbery +# Copyright 2019, 2021 Russ Allbery # Copyright 2013-2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/docs/pod-spelling.t b/t/docs/pod-spelling.t index 491f932..497dce3 100755 --- a/t/docs/pod-spelling.t +++ b/t/docs/pod-spelling.t @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/docs/pod.t b/t/docs/pod.t index 1c88ed1..85974d8 100755 --- a/t/docs/pod.t +++ b/t/docs/pod.t @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/docs/synopsis.t b/t/docs/synopsis.t index 1a2fbf1..b19b4dd 100755 --- a/t/docs/synopsis.t +++ b/t/docs/synopsis.t @@ -6,7 +6,7 @@ # which can be found at . # # Written by Russ Allbery -# Copyright 2019 Russ Allbery +# Copyright 2019, 2021 Russ Allbery # Copyright 2013-2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/lib/Test/RRA.pm b/t/lib/Test/RRA.pm index 56417c4..c432d0c 100644 --- a/t/lib/Test/RRA.pm +++ b/t/lib/Test/RRA.pm @@ -10,7 +10,7 @@ package Test::RRA; -use 5.008; +use 5.010; use base qw(Exporter); use strict; use warnings; @@ -52,7 +52,7 @@ BEGIN { # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '9.01'; + $VERSION = '10.01'; } # Compare a string to the contents of a file, similar to the standard is() diff --git a/t/lib/Test/RRA/Config.pm b/t/lib/Test/RRA/Config.pm index 0bc1b25..75419ea 100644 --- a/t/lib/Test/RRA/Config.pm +++ b/t/lib/Test/RRA/Config.pm @@ -9,7 +9,7 @@ package Test::RRA::Config; -use 5.008; +use 5.010; use base qw(Exporter); use strict; use warnings; @@ -32,7 +32,7 @@ BEGIN { # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '9.01'; + $VERSION = '10.01'; } # If C_TAP_BUILD or C_TAP_SOURCE are set in the environment, look for @@ -58,7 +58,7 @@ our $COVERAGE_LEVEL = 100; our @COVERAGE_SKIP_TESTS; our @CRITIC_IGNORE; our $LIBRARY_PATH; -our $MINIMUM_VERSION = '5.008'; +our $MINIMUM_VERSION = '5.010'; our %MINIMUM_VERSION; our @MODULE_VERSION_IGNORE; our @POD_COVERAGE_EXCLUDE; @@ -135,7 +135,7 @@ that Perl scripts can pass a syntax check. =item $MINIMUM_VERSION Default minimum version requirement for included Perl scripts. If not given, -defaults to 5.008. +defaults to 5.010. =item %MINIMUM_VERSION diff --git a/t/lib/Test/RRA/ModuleVersion.pm b/t/lib/Test/RRA/ModuleVersion.pm index 18f3ae1..d01c14b 100644 --- a/t/lib/Test/RRA/ModuleVersion.pm +++ b/t/lib/Test/RRA/ModuleVersion.pm @@ -29,7 +29,7 @@ BEGIN { # This version should match the corresponding rra-c-util release, but with # two digits for the minor version, including a leading zero if necessary, # so that it will sort properly. - $VERSION = '9.01'; + $VERSION = '10.01'; } # A regular expression matching the version string for a module using the diff --git a/t/style/coverage.t b/t/style/coverage.t index ae709fb..57222d5 100755 --- a/t/style/coverage.t +++ b/t/style/coverage.t @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/style/critic.t b/t/style/critic.t index 9794b39..d515221 100755 --- a/t/style/critic.t +++ b/t/style/critic.t @@ -31,7 +31,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/style/minimum-version.t b/t/style/minimum-version.t index 861367d..6a5aa89 100755 --- a/t/style/minimum-version.t +++ b/t/style/minimum-version.t @@ -6,7 +6,7 @@ # which can be found at . # # Written by Russ Allbery -# Copyright 2019 Russ Allbery +# Copyright 2019, 2021 Russ Allbery # Copyright 2013-2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; diff --git a/t/style/module-version.t b/t/style/module-version.t index 8339da5..2601f81 100755 --- a/t/style/module-version.t +++ b/t/style/module-version.t @@ -11,7 +11,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; @@ -121,7 +121,7 @@ Russ Allbery =head1 COPYRIGHT AND LICENSE -Copyright 2014-2016, 2019-2020 Russ Allbery +Copyright 2014-2016, 2019-2021 Russ Allbery Copyright 2013-2014 The Board of Trustees of the Leland Stanford Junior University diff --git a/t/style/strict.t b/t/style/strict.t index 8b92fb5..a2f5b99 100755 --- a/t/style/strict.t +++ b/t/style/strict.t @@ -6,7 +6,7 @@ # which can be found at . # # Written by Russ Allbery -# Copyright 2016, 2018-2020 Russ Allbery +# Copyright 2016, 2018-2021 Russ Allbery # Copyright 2013-2014 # The Board of Trustees of the Leland Stanford Junior University # @@ -30,7 +30,7 @@ # # SPDX-License-Identifier: MIT -use 5.008; +use 5.010; use strict; use warnings; -- cgit v1.2.3 From ce6ac799915595b1ef572eb8aa607a700e7deef0 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 15:59:35 -0800 Subject: Support POD conversion via *.spin pointers 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. --- Build.PL | 1 + Changes | 10 ++ README | 1 + README.md | 1 + cpanfile | 1 + docs/docknot.yaml | 1 + lib/App/DocKnot/Command.pm | 4 +- lib/App/DocKnot/Spin.pm | 8 +- lib/App/DocKnot/Spin/Pointer.pm | 100 +++++++++++++++++--- lib/App/DocKnot/Spin/Thread.pm | 103 ++++++++++++++++----- share/schema/pointer.yaml | 8 ++ t/cli/spin.t | 24 +++-- t/data/generate/docknot/output/thread | 1 + t/data/perlcriticrc | 6 ++ t/data/regenerate-data | 5 +- .../input/software/docknot/api/app-docknot.rpod | 1 - .../input/software/docknot/api/app-docknot.spin | 2 + .../output/software/docknot/api/app-docknot.html | 2 +- t/spin/tree.t | 38 ++++---- 19 files changed, 246 insertions(+), 71 deletions(-) delete mode 100644 t/data/spin/input/software/docknot/api/app-docknot.rpod create mode 100644 t/data/spin/input/software/docknot/api/app-docknot.spin diff --git a/Build.PL b/Build.PL index a2f8640..1304468 100644 --- a/Build.PL +++ b/Build.PL @@ -74,6 +74,7 @@ my $build = Module::Build->new( 'JSON::MaybeXS' => 0, 'Kwalify' => 0, 'List::SomeUtils' => '0.07', + 'Path::Tiny' => 0, 'Perl6::Slurp' => 0, 'Pod::Thread' => '3.00', 'Template' => 0, diff --git a/Changes b/Changes index 4de1bc4..cf11728 100644 --- a/Changes +++ b/Changes @@ -8,6 +8,16 @@ 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. diff --git a/README b/README index ba04a75..2058879 100644 --- a/README +++ b/README @@ -64,6 +64,7 @@ REQUIREMENTS * JSON::MaybeXS * Kwalify * List::SomeUtils 0.07 or later + * Path::Tiny * Perl6::Slurp * Pod::Thread 3.00 or later * Template (part of Template Toolkit) diff --git a/README.md b/README.md index 8d1342e..f430882 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ The following additional Perl modules are required to use it: * JSON::MaybeXS * Kwalify * List::SomeUtils 0.07 or later +* Path::Tiny * Perl6::Slurp * Pod::Thread 3.00 or later * Template (part of Template Toolkit) diff --git a/cpanfile b/cpanfile index 8c79578..22a0136 100644 --- a/cpanfile +++ b/cpanfile @@ -12,6 +12,7 @@ requires 'IPC::System::Simple'; requires 'JSON::MaybeXS'; requires 'Kwalify'; requires 'List::SomeUtils', '0.07'; +requires 'Path::Tiny'; requires 'Perl6::Slurp'; requires 'Pod::Thread', '3.00'; requires 'Template'; diff --git a/docs/docknot.yaml b/docs/docknot.yaml index 12b9eb7..aa92b1c 100644 --- a/docs/docknot.yaml +++ b/docs/docknot.yaml @@ -137,6 +137,7 @@ requirements: | * JSON::MaybeXS * Kwalify * List::SomeUtils 0.07 or later + * Path::Tiny * Perl6::Slurp * Pod::Thread 3.00 or later * Template (part of Template Toolkit) diff --git a/lib/App/DocKnot/Command.pm b/lib/App/DocKnot/Command.pm index e8fee87..750bb64 100644 --- a/lib/App/DocKnot/Command.pm +++ b/lib/App/DocKnot/Command.pm @@ -297,8 +297,8 @@ Perl 5.24 or later and the modules Date::Language, Date::Parse (both part of TimeDate), File::BaseDir, File::ShareDir, Git::Repository, Image::Size, IO::Compress::Xz (part of IO-Compress-Lzma), IO::Uncompress::Gunzip (part of IO-Compress), IPC::Run, IPC::System::Simple, JSON::MaybeXS, Kwalify, -List::SomeUtils, Perl6::Slurp, Template (part of Template Toolkit), and -YAML::XS, all of which are available from CPAN. +List::SomeUtils, Path::Tiny, Perl6::Slurp, Template (part of Template +Toolkit), and YAML::XS, all of which are available from CPAN. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin.pm b/lib/App/DocKnot/Spin.pm index 3f6590e..80da8b8 100644 --- a/lib/App/DocKnot/Spin.pm +++ b/lib/App/DocKnot/Spin.pm @@ -574,6 +574,7 @@ sub spin { output => $output, sitemap => $self->{sitemap}, 'style-url' => $self->{style_url}, + thread => $self->{thread}, }, ); #>>> @@ -613,9 +614,10 @@ App::DocKnot::Spin - Static site builder supporting thread macro language =head1 REQUIREMENTS Perl 5.24 or later and the modules Git::Repository, Image::Size, -List::SomeUtils, and Pod::Thread, all of which are available from CPAN. Also -expects to find B, B, and B on the user's PATH -to convert certain types of files. +List::SomeUtils, Path::Tiny, Pod::Thread, Template (part of Template Toolkit), +and YAML::XS, all of which are available from CPAN. Also expects to find +B, B, and B on the user's PATH to convert +certain types of files. =head1 DESCRIPTION diff --git a/lib/App/DocKnot/Spin/Pointer.pm b/lib/App/DocKnot/Spin/Pointer.pm index 63660b5..6cfa0a5 100644 --- a/lib/App/DocKnot/Spin/Pointer.pm +++ b/lib/App/DocKnot/Spin/Pointer.pm @@ -39,7 +39,8 @@ my $URL = 'https://www.eyrie.org/~eagle/software/web/'; # Convert a Markdown file to HTML. # # $data_ref - Data from the pointer file -# path - Path to the Markdown file to convert +# path - Path to the Markdown file to convert +# style - Style sheet to use # $output - Path to the output file # # Throws: Text exception on conversion failure @@ -101,6 +102,48 @@ sub _spin_markdown { return; } +# Convert a POD file to HTML. +# +# $data_ref - Data from the pointer file +# options - Hash of conversion options +# contents - Whether to add a table of contents +# navbar - Whether to add a navigation bar +# path - Path to the POD file to convert +# style - Style sheet to use +# $output - Path to the output file +# +# Throws: Text exception on conversion failure +sub _spin_pod { + my ($self, $data_ref, $output) = @_; + my $source = $data_ref->{path}; + + # Construct the Pod::Thread formatter object. + #<<< + my %options = ( + contents => $data_ref->{options}{contents}, + style => $data_ref->{style} // 'pod', + ); + #<<< + if (exists($data_ref->{options}{navbar})) { + $options{navbar} = $data_ref->{options}{navbar}; + } else { + $options{navbar} = 1; + } + if (exists($data_ref->{title})) { + $options{title} = $data_ref->{title}; + } + my $podthread = Pod::Thread->new(%options); + + # Convert the POD to thread. + my $data; + $podthread->output_string(\$data); + $podthread->parse_file($source); + + # Spin that page into HTML. + $self->{thread}->spin_thread_output($data, $source, 'POD', $output); + return; +} + ############################################################################## # Public interface ############################################################################## @@ -109,10 +152,10 @@ sub _spin_markdown { # reused for all pointer conversions done while spinning a tree of files. # # $args - Anonymous hash of arguments with the following keys: -# docknot-url - URL to DocKnot itself for use in page footers -# output - Root of the output tree -# sitemap - App::DocKnot::Spin::Sitemap object -# style-url - Partial URL to style sheets +# output - Root of the output tree +# sitemap - App::DocKnot::Spin::Sitemap object +# style-url - Partial URL to style sheets +# thread - App::DocKnot::Spin::Thread object # # Returns: Newly created object # Throws: Text exception on failure to initialize Template Toolkit @@ -139,6 +182,7 @@ sub new { sitemap => $args_ref->{sitemap}, style_url => $style_url, template => $tt, + thread => $args_ref->{thread}, }; #>>> bless($self, $class); @@ -175,10 +219,13 @@ sub is_out_of_date { sub spin_pointer { my ($self, $pointer, $output, $options_ref) = @_; my $data_ref = $self->load_yaml_file($pointer, 'pointer'); + $data_ref->{options} //= {}; # Dispatch to the appropriate conversion function. if ($data_ref->{format} eq 'markdown') { $self->_spin_markdown($data_ref, $output); + } elsif ($data_ref->{format} eq 'pod') { + $self->_spin_pod($data_ref, $output); } else { die "$pointer: unknown output format $data_ref->{format}\n"; } @@ -195,6 +242,7 @@ __END__ =for stopwords Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT Kwalify sublicense unstyled +navbar =head1 NAME @@ -215,7 +263,7 @@ App::DocKnot::Spin::Pointer - Generate HTML from a pointer to an external file =head1 REQUIREMENTS Perl 5.24 or later and the modules File::ShareDir, Kwalify, List::SomeUtils, -and YAML::XS, all of which are available from CPAN. +Pod::Thread, and YAML::XS, all of which are available from CPAN. =head1 DESCRIPTION @@ -258,6 +306,12 @@ be considered to be relative to this URL and this URL will be prepended to it. If this option is not given, the name of the style sheet will be used verbatim as its URL, except with C<.css> appended. +=item thread + +An App::DocKnot::Spin::Thread object, used for converting POD into HTML. It +should be configured with the same App::DocKnot::Spin::Sitemap object as the +C argument. + =back =back @@ -288,7 +342,7 @@ conversion. The valid keys for a pointer file are: =item format -The format of the source file. The only valid value currently is C. +The format of the source file. Supported values are C and C. Required. =item path @@ -296,17 +350,41 @@ Required. The path to the source file. It may be relative, in which case it's relative to the pointer file. Required. +=item options + +Additional options that control the conversion to HTML. These will be +different for each supported format. + +C has no supported options. + +The supported options for a format of C are: + +=over 4 + +=item contents + +Boolean saying whether to generate a table of contents. The default is false. + +=item navbar + +Boolean saying whether to generate a navigation bar at the top of the page. +The default is true. + +=back + =item style -The style sheet to use for the converted output. Optional. If not set, the -converted output may be unstyled or may use a default style sheet appropriate -to the input format. +The style sheet to use for the converted output. Optional. If not set, +converted C output will be unstyled and converted C output will +use a style sheet named C. =item title The title of the converted page. Optional. If not set, the title will be taken from the converted file in a format-specific way. For Markdown, the -title will be the contents of the first top-level heading. +title will be the contents of the first top-level heading. For POD, the title +will be taken from a NAME section formatted according to the conventions for +manual pages. =back diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index 53cabc9..cc8aea6 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -22,6 +22,7 @@ use File::Basename qw(fileparse); use File::Spec (); use Git::Repository (); use Image::Size qw(html_imgsize); +use Path::Tiny qw(path); use Perl6::Slurp qw(slurp); use POSIX qw(strftime); use Text::Balanced qw(extract_bracketed); @@ -635,26 +636,28 @@ sub _parse { # since thread may contain relative paths to files that the spinning process # needs to access. # -# $thread - Thread to spin -# $in_path - Input file path if any, used for error reporting -# $out_fh - Output file handle to which to write the HTML -# $out_path - Optional output file path for error reporting and page links +# $thread - Thread to spin +# $in_path - Input file path if any, used for error reporting +# $out_fh - Output file handle to which to write the HTML +# $out_path - Optional output file path for error reporting and page links +# $input_type - Optional one-word description of input type sub _parse_document { - my ($self, $thread, $in_path, $out_fh, $out_path) = @_; + my ($self, $thread, $in_path, $out_fh, $out_path, $input_type) = @_; # Parse the thread into paragraphs and reverse them to form a stack. my @input = reverse($self->_split_paragraphs($thread)); # Initialize object state for a new document. #<<< - $self->{input} = [[\@input, $in_path, 1]]; - $self->{macro} = {}; - $self->{out_fh} = $out_fh; - $self->{out_path} = $out_path // q{-}; - $self->{rss} = []; - $self->{space} = q{}; - $self->{state} = ['BLOCK']; - $self->{variable} = {}; + $self->{input} = [[\@input, $in_path, 1]]; + $self->{input_type} = $input_type // 'thread'; + $self->{macro} = {}; + $self->{out_fh} = $out_fh; + $self->{out_path} = $out_path // q{-}; + $self->{rss} = []; + $self->{space} = q{}; + $self->{state} = ['BLOCK']; + $self->{variable} = {}; #>>> # Parse the thread file a paragraph at a time. _split_paragraphs takes @@ -1242,9 +1245,9 @@ sub _cmd_signature { my $source = $self->{input}[-1][1]; my $output = $self->_border_end(); - # If we're spinning from standard input, don't add any of the standard - # footer, just close the HTML tags. - if ($self->{input}[-1][1] eq q{-}) { + # If we're spinning from standard input to standard output, don't add any + # of the standard footer, just close the HTML tags. + if ($source eq q{-} && $self->{out_path} eq q{-}) { $output .= "\n\n"; return (1, $output); } @@ -1258,12 +1261,17 @@ sub _cmd_signature { # Figure out the modification dates. Use the Git repository if available. my $now = strftime('%Y-%m-%d', gmtime()); - my $modified = strftime('%Y-%m-%d', gmtime((stat($source))[9])); + my $modified = $now; + if ($source ne q{-}) { + $modified = strftime('%Y-%m-%d', gmtime((stat($source))[9])); + } if ($self->{repository} && $self->{source}) { - my $repository = $self->{repository}; - $modified = $repository->run('log', '-1', '--format=%ct', $source); - if ($modified) { - $modified = strftime('%Y-%m-%d', gmtime($modified)); + if (path($self->{source})->subsumes(path($source))) { + my $repository = $self->{repository}; + $modified = $repository->run('log', '-1', '--format=%ct', $source); + if ($modified) { + $modified = strftime('%Y-%m-%d', gmtime($modified)); + } } } @@ -1273,7 +1281,8 @@ sub _cmd_signature { if ($modified eq $now) { $output .= " Last modified and\n $link $modified\n"; } else { - $output .= " Last $link\n $now from thread modified $modified\n"; + $output .= " Last $link\n"; + $output .= " $now from $self->{input_type} modified $modified\n"; } # Close out the document. @@ -1475,6 +1484,39 @@ sub spin_thread_file { return; } +# Convert thread to HTML and write it to the given output file. This is used +# when the thread isn't part of the input tree but instead is intermediate +# output from some other conversion process. +# +# $thread - Thread to spin +# $input - Original input file (for modification timestamps) +# $input_type - One-word description of input type for the page footer +# $output - Output file +# +# Returns: Resulting HTML +sub spin_thread_output { + my ($self, $thread, $input, $input_type, $output) = @_; + + # Open the output file. + my $out_fh; + if (defined($output)) { + my $path = realpath($output) + or die "cannot canonicalize $output: $!\n"; + $output = $path; + open($out_fh, '>', $output); + } else { + $output = q{-}; + open($out_fh, '>&', 'STDOUT'); + } + + # Do the work. + $self->_parse_document($thread, $input, $out_fh, $output, $input_type); + + # Clean up and restore the working directory. + close($out_fh); + return; +} + ############################################################################## # Module return value and documentation ############################################################################## @@ -1510,11 +1552,14 @@ App::DocKnot::Spin::Thread - Generate HTML from the macro language thread versions => $versions, }); $thread->spin_thread_file('/input/file.th', '/output/file.html'); + $thread->spin_thread_output( + $input, '/path/to/file.pod', 'POD', '/output/file.html' + ); =head1 REQUIREMENTS -Perl 5.24 or later and the modules Git::Repository, Image::Size, and -List::SomeUtils, all of which are available from CPAN. +Perl 5.24 or later and the modules Git::Repository, Image::Size, +List::SomeUtils, and Path::Tiny, all of which are available from CPAN. =head1 DESCRIPTION @@ -1595,6 +1640,16 @@ If OUTPUT is omitted, App::DocKnot::Spin::Thread will not be able to obtain sitemap information even if a sitemap was provided and therefore will not add inter-page links. +=item spin_thread_output(THREAD, INPUT, TYPE[, OUTPUT]) + +Convert the given thread to HTML, writing the result to OUTPUT. If OUTPUT is +not given, write the results to standard output. This is like spin_thread() +but does use sitemap information and adds inter-page links. It should be used +when the thread input is the result of an intermediate conversion step of a +known input file. INPUT should be the full path to the original source file, +used for modification time information. TYPE should be set to a one-word +description of the format of the input file and is used for the page footer. + =back =head1 THREAD LANGUAGE diff --git a/share/schema/pointer.yaml b/share/schema/pointer.yaml index fc8232d..92fba45 100644 --- a/share/schema/pointer.yaml +++ b/share/schema/pointer.yaml @@ -11,9 +11,17 @@ mapping: required: true enum: - markdown + - pod path: type: text required: true + options: + type: map + mapping: + contents: + type: bool + navbar: + type: bool style: type: text title: diff --git a/t/cli/spin.t b/t/cli/spin.t index 58bf2f7..ac7894f 100755 --- a/t/cli/spin.t +++ b/t/cli/spin.t @@ -23,8 +23,11 @@ use Test::DocKnot::Spin qw(is_spin_output is_spin_output_tree); use Test::More; -# Load the module. -BEGIN { use_ok('App::DocKnot::Command') } +# Load the modules. +BEGIN { + use_ok('App::DocKnot::Command'); + use_ok('App::DocKnot::Util', qw(print_fh)); +} # Force the C locale because some of the output intentionally uses localized # month names and we have to force those to English for comparison of test @@ -56,20 +59,21 @@ close($output_fh); is_spin_output($output, $expected, 'spin-thread (standard output)'); # Copy the input tree to a new temporary directory since .rss files generate -# additional thread files. Replace the rpod pointer since it points to a +# additional thread files. Replace the .spin pointer since it points to a # relative path in the source tree. my $indir = File::Temp->newdir(); $input = File::Spec->catfile($datadir, 'input'); dircopy($input, $indir->dirname) or die "Cannot copy $input to $indir: $!\n"; -my $rpod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); -my $rpod_path = File::Spec->catfile( +my $pod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); +my $pointer_path = File::Spec->catfile( $indir->dirname, 'software', 'docknot', 'api', - 'app-docknot.rpod', + 'app-docknot.spin', ); -chmod(0644, $rpod_path); -open(my $fh, '>', $rpod_path); -print {$fh} "$rpod_source\n" or die "Cannot write to $rpod_path: $!\n"; +chmod(0644, $pointer_path); +open(my $fh, '>', $pointer_path); +print_fh($fh, $pointer_path, "format: pod\n"); +print_fh($fh, $pointer_path, "path: $pod_source\n"); close($fh); # Spin a tree of files. @@ -95,4 +99,4 @@ like( ); # Report the end of testing. -done_testing($count + 5); +done_testing($count + 6); diff --git a/t/data/generate/docknot/output/thread b/t/data/generate/docknot/output/thread index 6806bbf..51e76d0 100644 --- a/t/data/generate/docknot/output/thread +++ b/t/data/generate/docknot/output/thread @@ -117,6 +117,7 @@ The following additional Perl modules are required to use it: \bullet(packed)[JSON::MaybeXS] \bullet(packed)[Kwalify] \bullet(packed)[List::SomeUtils 0.07 or later] +\bullet(packed)[Path::Tiny] \bullet(packed)[Perl6::Slurp] \bullet(packed)[Pod::Thread 3.00 or later] \bullet(packed)[Template (part of Template Toolkit)] diff --git a/t/data/perlcriticrc b/t/data/perlcriticrc index ff23461..88b3619 100644 --- a/t/data/perlcriticrc +++ b/t/data/perlcriticrc @@ -93,6 +93,12 @@ allow = unless # Perl 5.20). See https://github.com/Perl-Critic/Perl-Critic/issues/578. [-References::ProhibitDoubleSigils] +# Five arguments to a method has seemed reasonable at least once: a pair of +# input file data and path, a pair of output file descriptor and path, and +# a dict of additional arguments. +[Subroutines::ProhibitManyArgs] +skip_object = 1 + # I generally don't want to require Readonly as a prerequisite for all my Perl # modules. [-ValuesAndExpressions::ProhibitConstantPragma] diff --git a/t/data/regenerate-data b/t/data/regenerate-data index b95b87f..87ee82d 100755 --- a/t/data/regenerate-data +++ b/t/data/regenerate-data @@ -67,7 +67,7 @@ my $links = <<'EOD'; EOD -my $comment = ''; +my $comment = ''; my $navbar = <<'EOD';
        @@ -78,7 +78,6 @@ my $navbar = <<'EOD';
        App::DocKnot::Command >
        - EOD my $address = <<'EOD';
        @@ -89,7 +88,7 @@ EOD $html =~ s{ () }{$links$1}xms; $html =~ s{ }{$comment}xms; $html =~ s{ ( \n) }{$1$navbar}xms; -$html =~ s{ () }{$navbar$address$1}xms; +$html =~ s{ () }{$navbar\n$address$1}xms; # Replace the expected data file. my $output = File::Spec->catdir( diff --git a/t/data/spin/input/software/docknot/api/app-docknot.rpod b/t/data/spin/input/software/docknot/api/app-docknot.rpod deleted file mode 100644 index 5075ec0..0000000 --- a/t/data/spin/input/software/docknot/api/app-docknot.rpod +++ /dev/null @@ -1 +0,0 @@ -../../../../../../../lib/App/DocKnot.pm diff --git a/t/data/spin/input/software/docknot/api/app-docknot.spin b/t/data/spin/input/software/docknot/api/app-docknot.spin new file mode 100644 index 0000000..a3ea9e8 --- /dev/null +++ b/t/data/spin/input/software/docknot/api/app-docknot.spin @@ -0,0 +1,2 @@ +format: pod +path: ../../../../../../../lib/App/DocKnot.pm diff --git a/t/data/spin/output/software/docknot/api/app-docknot.html b/t/data/spin/output/software/docknot/api/app-docknot.html index 944c09c..85f242f 100644 --- a/t/data/spin/output/software/docknot/api/app-docknot.html +++ b/t/data/spin/output/software/docknot/api/app-docknot.html @@ -14,7 +14,7 @@ - + diff --git a/t/spin/tree.t b/t/spin/tree.t index 2a173a7..d2daab1 100755 --- a/t/spin/tree.t +++ b/t/spin/tree.t @@ -56,7 +56,7 @@ Spinning .../software/index.html Creating .../software/docknot Spinning .../software/docknot/index.html Creating .../software/docknot/api -Running pod2thread for .../software/docknot/api/app-docknot.html +Converting .../software/docknot/api/app-docknot.html Creating .../usefor Spinning .../usefor/index.html Creating .../usefor/drafts @@ -66,10 +66,12 @@ Updating .../usefor/drafts/draft-ietf-usefor-useage-01.txt Updating .../usefor/drafts/draft-lindsey-usefor-signed-01.txt OUTPUT +BEGIN { use_ok('App::DocKnot::Util', qw(print_fh)) } + require_ok('App::DocKnot::Spin'); # Copy the input tree to a new temporary directory since .rss files generate -# additional thread files. Replace the rpod pointer since it points to a +# additional thread files. Replace the POD pointer since it points to a # relative path in the source tree, but change its modification timestamp to # something in the past. my $tmpdir = File::Temp->newdir(); @@ -77,14 +79,15 @@ my $datadir = File::Spec->catfile('t', 'data', 'spin'); my $input = File::Spec->catfile($datadir, 'input'); dircopy($input, $tmpdir->dirname) or die "Cannot copy $input to $tmpdir: $!\n"; -my $rpod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); -my $rpod_path = File::Spec->catfile( +my $pod_source = File::Spec->catfile(getcwd(), 'lib', 'App', 'DocKnot.pm'); +my $pointer_path = File::Spec->catfile( $tmpdir->dirname, 'software', 'docknot', 'api', - 'app-docknot.rpod', + 'app-docknot.spin', ); -chmod(0644, $rpod_path); -open(my $fh, '>', $rpod_path); -print {$fh} "$rpod_source\n" or die "Cannot write to $rpod_path: $!\n"; +chmod(0644, $pointer_path); +open(my $fh, '>', $pointer_path); +print_fh($fh, $pointer_path, "format: pod\n"); +print_fh($fh, $pointer_path, "path: $pod_source\n"); close($fh); my $old_timestamp = time() - 10; @@ -132,17 +135,20 @@ ok(!-e $bogus, 'Stray file and directory was deleted'); # Override the title of the POD document and request a contents section. Set # the modification timestamp in the future to force a repsin. -open($fh, '>>', $rpod_path); -print {$fh} "-c -t 'New Title'\n" or die "Cannot write to $rpod_path: $!\n"; +open($fh, '>>', $pointer_path); +print_fh($fh, $pointer_path, "format: pod\n"); +print_fh($fh, $pointer_path, "path: $pod_source\n"); +print_fh($fh, $pointer_path, "options:\n contents: true\n navbar: false\n"); +print_fh($fh, $pointer_path, "title: 'New Title'\n"); close($fh); -utime(time() + 5, time() + 5, $rpod_path) - or die "Cannot reset timestamps of $rpod_path: $!\n"; +utime(time() + 5, time() + 5, $pointer_path) + or die "Cannot reset timestamps of $pointer_path: $!\n"; $stdout = capture_stdout { $spin->spin($tmpdir->dirname, $output->dirname); }; is( $stdout, - "Running pod2thread for .../software/docknot/api/app-docknot.html\n", + "Converting .../software/docknot/api/app-docknot.html\n", 'Spinning again regenerates the App::DocKnot page', ); my $output_path = File::Spec->catfile( @@ -158,8 +164,8 @@ like($page, qr{

        New [ ] Title

        }xms, 'POD h1 override worked'); like($page, qr{ Table [ ] of [ ] Contents }xms, 'POD table of contents'); # Set the time back so that it won't be generated again. -utime(time() - 5, time() - 5, $rpod_path) - or die "Cannot reset timestamps of $rpod_path: $!\n"; +utime(time() - 5, time() - 5, $pointer_path) + or die "Cannot reset timestamps of $pointer_path: $!\n"; # Now, update the .versions file at the top of the input tree to change the # timestamp to ten seconds into the future. This should force regeneration of @@ -182,4 +188,4 @@ is( ); # Report the end of testing. -done_testing($count + 11); +done_testing($count + 12); -- cgit v1.2.3 From e106de4f9db6e577c550d58367c46de097d0546a Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 16:39:54 -0800 Subject: Update MANIFEST --- MANIFEST | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/MANIFEST b/MANIFEST index 8256e4a..5acfdc6 100644 --- a/MANIFEST +++ b/MANIFEST @@ -12,11 +12,13 @@ lib/App/DocKnot/Config.pm lib/App/DocKnot/Dist.pm lib/App/DocKnot/Generate.pm lib/App/DocKnot/Spin.pm +lib/App/DocKnot/Spin/Pointer.pm lib/App/DocKnot/Spin/RSS.pm lib/App/DocKnot/Spin/Sitemap.pm lib/App/DocKnot/Spin/Thread.pm lib/App/DocKnot/Spin/Versions.pm lib/App/DocKnot/Update.pm +lib/App/DocKnot/Util.pm LICENSE MANIFEST This list of files MANIFEST.SKIP @@ -26,6 +28,8 @@ share/licenses.yaml share/schema/config.yaml share/schema/docknot.yaml share/schema/licenses.yaml +share/schema/pointer.yaml +share/templates/html.tmpl share/templates/readme-md.tmpl share/templates/readme.tmpl share/templates/thread.tmpl @@ -98,7 +102,7 @@ t/data/spin/input/names.png t/data/spin/input/random.th t/data/spin/input/reviews/books/.macros t/data/spin/input/reviews/books/0-385-49362-2.th -t/data/spin/input/software/docknot/api/app-docknot.rpod +t/data/spin/input/software/docknot/api/app-docknot.spin t/data/spin/input/software/docknot/index.th t/data/spin/input/software/index.th t/data/spin/input/usefor/drafts/draft-ietf-usefor-message-id-01.txt @@ -106,6 +110,12 @@ t/data/spin/input/usefor/drafts/draft-ietf-usefor-posted-mailed-01.txt t/data/spin/input/usefor/drafts/draft-ietf-usefor-useage-01.txt t/data/spin/input/usefor/drafts/draft-lindsey-usefor-signed-01.txt t/data/spin/input/usefor/index.th +t/data/spin/markdown/input/.sitemap +t/data/spin/markdown/input/other.spin +t/data/spin/markdown/input/test.spin +t/data/spin/markdown/output/other.html +t/data/spin/markdown/output/test.html +t/data/spin/markdown/test.md t/data/spin/output/changes.html t/data/spin/output/changes.rss t/data/spin/output/index.html @@ -227,6 +237,7 @@ t/lib/Test/RRA/ModuleVersion.pm t/metadata/licenses.t t/spin/errors.t t/spin/file.t +t/spin/markdown.t t/spin/sitemap.t t/spin/thread.t t/spin/tree.t -- cgit v1.2.3 From e6684184ae636e1ed7fc941ee25992f32cf09307 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 16:45:22 -0800 Subject: Release 6.00 --- LICENSE | 1 - README | 2 +- docs/docknot.yaml | 2 +- lib/App/DocKnot.pm | 2 +- lib/App/DocKnot/Command.pm | 2 +- lib/App/DocKnot/Config.pm | 2 +- lib/App/DocKnot/Dist.pm | 2 +- lib/App/DocKnot/Generate.pm | 2 +- lib/App/DocKnot/Spin.pm | 2 +- lib/App/DocKnot/Spin/Pointer.pm | 2 +- lib/App/DocKnot/Spin/RSS.pm | 2 +- lib/App/DocKnot/Spin/Sitemap.pm | 2 +- lib/App/DocKnot/Spin/Thread.pm | 2 +- lib/App/DocKnot/Spin/Versions.pm | 2 +- lib/App/DocKnot/Update.pm | 2 +- lib/App/DocKnot/Util.pm | 2 +- 16 files changed, 15 insertions(+), 16 deletions(-) diff --git a/LICENSE b/LICENSE index 9849929..5aa6925 100644 --- a/LICENSE +++ b/LICENSE @@ -40,4 +40,3 @@ License: all-permissive permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty. - diff --git a/README b/README index 2058879..cf25bbe 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ - DocKnot 5.00 + DocKnot 6.00 (Static web site and documentation generator) Maintained by Russ Allbery diff --git a/docs/docknot.yaml b/docs/docknot.yaml index aa92b1c..abe65d6 100644 --- a/docs/docknot.yaml +++ b/docs/docknot.yaml @@ -15,7 +15,7 @@ format: v1 name: DocKnot maintainer: Russ Allbery -version: '5.00' +version: '6.00' synopsis: Static web site and documentation generator license: diff --git a/lib/App/DocKnot.pm b/lib/App/DocKnot.pm index b92adae..721bb30 100644 --- a/lib/App/DocKnot.pm +++ b/lib/App/DocKnot.pm @@ -11,7 +11,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot 5.00; +package App::DocKnot 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Command.pm b/lib/App/DocKnot/Command.pm index 750bb64..7ef45e5 100644 --- a/lib/App/DocKnot/Command.pm +++ b/lib/App/DocKnot/Command.pm @@ -10,7 +10,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Command 5.00; +package App::DocKnot::Command 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Config.pm b/lib/App/DocKnot/Config.pm index d8a7b27..2eebe32 100644 --- a/lib/App/DocKnot/Config.pm +++ b/lib/App/DocKnot/Config.pm @@ -9,7 +9,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Config 5.00; +package App::DocKnot::Config 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Dist.pm b/lib/App/DocKnot/Dist.pm index f9f7a89..50d3b9b 100644 --- a/lib/App/DocKnot/Dist.pm +++ b/lib/App/DocKnot/Dist.pm @@ -10,7 +10,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Dist 5.00; +package App::DocKnot::Dist 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Generate.pm b/lib/App/DocKnot/Generate.pm index 9d5a8e0..8caa7a8 100644 --- a/lib/App/DocKnot/Generate.pm +++ b/lib/App/DocKnot/Generate.pm @@ -10,7 +10,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Generate 5.00; +package App::DocKnot::Generate 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin.pm b/lib/App/DocKnot/Spin.pm index 80da8b8..73666e0 100644 --- a/lib/App/DocKnot/Spin.pm +++ b/lib/App/DocKnot/Spin.pm @@ -11,7 +11,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin 5.00; +package App::DocKnot::Spin 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin/Pointer.pm b/lib/App/DocKnot/Spin/Pointer.pm index 6cfa0a5..05aa9ac 100644 --- a/lib/App/DocKnot/Spin/Pointer.pm +++ b/lib/App/DocKnot/Spin/Pointer.pm @@ -10,7 +10,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin::Pointer 5.00; +package App::DocKnot::Spin::Pointer 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin/RSS.pm b/lib/App/DocKnot/Spin/RSS.pm index a2d2c4d..2a7460a 100644 --- a/lib/App/DocKnot/Spin/RSS.pm +++ b/lib/App/DocKnot/Spin/RSS.pm @@ -9,7 +9,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin::RSS 5.00; +package App::DocKnot::Spin::RSS 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin/Sitemap.pm b/lib/App/DocKnot/Spin/Sitemap.pm index 46e9e0f..22fbdd5 100644 --- a/lib/App/DocKnot/Spin/Sitemap.pm +++ b/lib/App/DocKnot/Spin/Sitemap.pm @@ -12,7 +12,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin::Sitemap 5.00; +package App::DocKnot::Spin::Sitemap 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin/Thread.pm b/lib/App/DocKnot/Spin/Thread.pm index cc8aea6..bf58dc0 100644 --- a/lib/App/DocKnot/Spin/Thread.pm +++ b/lib/App/DocKnot/Spin/Thread.pm @@ -9,7 +9,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin::Thread 5.00; +package App::DocKnot::Spin::Thread 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Spin/Versions.pm b/lib/App/DocKnot/Spin/Versions.pm index 9aa07f2..679b368 100644 --- a/lib/App/DocKnot/Spin/Versions.pm +++ b/lib/App/DocKnot/Spin/Versions.pm @@ -12,7 +12,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Spin::Versions 5.00; +package App::DocKnot::Spin::Versions 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Update.pm b/lib/App/DocKnot/Update.pm index 7cb2c1d..5c6a999 100644 --- a/lib/App/DocKnot/Update.pm +++ b/lib/App/DocKnot/Update.pm @@ -9,7 +9,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Update 5.00; +package App::DocKnot::Update 6.00; use 5.024; use autodie; diff --git a/lib/App/DocKnot/Util.pm b/lib/App/DocKnot/Util.pm index 72302b0..203d3d3 100644 --- a/lib/App/DocKnot/Util.pm +++ b/lib/App/DocKnot/Util.pm @@ -9,7 +9,7 @@ # Modules and declarations ############################################################################## -package App::DocKnot::Util 5.00; +package App::DocKnot::Util 6.00; use 5.024; use autodie; -- cgit v1.2.3 From 29f8820d091914329dcaa4292ac6b76d78c54677 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 17:10:42 -0800 Subject: Add new modules to the documentation links --- docs/docknot.yaml | 4 ++++ t/data/generate/docknot/output/thread | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/docknot.yaml b/docs/docknot.yaml index abe65d6..becc165 100644 --- a/docs/docknot.yaml +++ b/docs/docknot.yaml @@ -67,6 +67,8 @@ docs: title: App::DocKnot::Generate - name: api/app-docknot-spin title: App::DocKnot::Spin + - name: api/app-docknot-spin-pointer + title: App::DocKnot::Spin::Pointer - name: api/app-docknot-spin-rss title: App::DocKnot::Spin::RSS - name: api/app-docknot-spin-sitemap @@ -77,6 +79,8 @@ docs: title: App::DocKnot::Spin::Versions - name: api/app-docknot-update title: App::DocKnot::Update + - name: api/app-docknot-util + title: App::DocKnot::Util developer: - name: todo title: To-do list diff --git a/t/data/generate/docknot/output/thread b/t/data/generate/docknot/output/thread index 51e76d0..63e79c3 100644 --- a/t/data/generate/docknot/output/thread +++ b/t/data/generate/docknot/output/thread @@ -181,11 +181,13 @@ development source]. \doc[api/app-docknot-dist.html][App::DocKnot::Dist] \doc[api/app-docknot-generate.html][App::DocKnot::Generate] \doc[api/app-docknot-spin.html][App::DocKnot::Spin] + \doc[api/app-docknot-spin-pointer.html][App::DocKnot::Spin::Pointer] \doc[api/app-docknot-spin-rss.html][App::DocKnot::Spin::RSS] \doc[api/app-docknot-spin-sitemap.html][App::DocKnot::Spin::Sitemap] \doc[api/app-docknot-spin-thread.html][App::DocKnot::Spin::Thread] \doc[api/app-docknot-spin-versions.html][App::DocKnot::Spin::Versions] \doc[api/app-docknot-update.html][App::DocKnot::Update] + \doc[api/app-docknot-util.html][App::DocKnot::Util] ] \h2(after)[License] -- cgit v1.2.3 From d47e0c931855cf0efbe72291f67ebbbd964f096f Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sat, 25 Dec 2021 17:13:04 -0800 Subject: Set release date for 6.00 --- Changes | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Changes b/Changes index cf11728..cddeb0f 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ Revision history for DocKnot -6.00 - Not Released +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 -- cgit v1.2.3