App-DocKnot
view release on metacpan or search on metacpan
lib/App/DocKnot/Generate.pm view on Meta::CPAN
use parent qw(App::DocKnot);
use warnings;
use App::DocKnot::Config;
use Carp qw(croak);
use Path::Tiny qw(path);
use Template;
use Text::Wrap qw(wrap);
# Default output files for specific templates.
my %DEFAULT_OUTPUT = (
'readme' => 'README',
'readme-md' => 'README.md',
);
##############################################################################
# Generator functions
##############################################################################
# The internal helper object methods in this section are generators. They
# return code references intended to be passed into Template Toolkit as code
lib/App/DocKnot/Generate.pm view on Meta::CPAN
# Generate all package documentation from the package metadata. Only
# generates the output for templates with a default output file.
#
# Returns: undef
# Throws: autodie exception on failure to read metadata or write the output
# Text exception on Template Toolkit failures
# Text exception on inconsistencies in the package data
sub generate_all {
my ($self) = @_;
for my $template (keys(%DEFAULT_OUTPUT)) {
$self->generate_output($template);
}
return;
}
# Generate a documentation file from the package metadata.
#
# $template - Name of the documentation template
# $output - Output file name (undef to use the default)
#
# Returns: undef
# Throws: autodie exception on failure to read metadata or write the output
# Text exception on Template Toolkit failures
# Text exception on inconsistencies in the package data
sub generate_output {
my ($self, $template, $output) = @_;
$output //= $DEFAULT_OUTPUT{$template};
# If the template doesn't have a default output file, $output is required.
if (!defined($output)) {
croak('missing required output argument');
}
# Generate the output.
my $data = $self->generate($template);
path($output)->spew_utf8($data);
return;
lib/App/DocKnot/Generate.pm view on Meta::CPAN
template itself will be loaded from the App::DocKnot configuration path as
described in L<DESCRIPTION>. Returns the generated documentation file as a
string.
=item generate_all()
Generate all of the documentation files for a package. This is currently
defined as the C<readme> and C<readme-md> templates. The output will be
written to the default output locations, as described under generate_output().
=item generate_output(TEMPLATE [, OUTPUT])
The same as generate() except that rather than returning the generated
documentation file as a string, it will be written to the file named by
OUTPUT. If that argument isn't given, a default based on the TEMPLATE
argument is chosen as follows:
readme -> README
readme-md -> README.md
If TEMPLATE isn't one of the templates listed above, the OUTPUT argument is
required.
=back
=head1 AUTHOR
Russ Allbery <rra@cpan.org>
=head1 COPYRIGHT AND LICENSE
lib/App/DocKnot/Spin.pm view on Meta::CPAN
will be used verbatim as its URL, except with C<.css> appended.
=back
=back
=head1 INSTANCE METHODS
=over 4
=item spin(INPUT, OUTPUT)
Build the source tree rooted at INPUT into an HTML static site, storing it
in the directory OUTPUT. If OUTPUT does not exist, it will be created.
=back
=head1 AUTHOR
Russ Allbery <rra@cpan.org>
=head1 COPYRIGHT AND LICENSE
Copyright 1999-2011, 2013, 2021-2023 Russ Allbery <rra@cpan.org>
lib/App/DocKnot/Spin/Pointer.pm view on Meta::CPAN
C<sitemap> argument.
=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.
Both paths must be Path::Tiny objects.
=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. Both paths must
be Path::Tiny objects.
=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:
lib/App/DocKnot/Spin/RSS.pm view on Meta::CPAN
Output files are only regenerated if they are older than the input feed
description file.
App::DocKnot::Spin::RSS is designed for use with App::DocKnot::Spin. It
relies on App::DocKnot::Spin::Thread to convert thread to HTML, both for
inclusion in RSS feeds and for post-processing of generated thread files.
App::DocKnot::Spin::RSS is invoked automatically by App::DocKnot::Spin when it
encounters an F<.rss> file in a directory it is processing.
See L<INPUT LANGUAGE> for the details of the language in which F<.rss> files
are written.
=head1 CLASS METHODS
=over 4
=item new(ARGS)
Create a new App::DocKnot::Spin::RSS object. ARGS should be a hash reference
with one or more of the following keys, all of which are optional:
lib/App/DocKnot/Spin/RSS.pm view on Meta::CPAN
=item generate(FILE[, BASE])
Parse the input file FILE and generate the output files that it specifies.
BASE, if given, specifies the root directory for output files specified with
relative paths, and overrides any C<base> argument given to new(). Both FILE
and BASE may be strings or Path::Tiny objects.
=back
=head1 INPUT LANGUAGE
The input for App::DocKnot::Spin::RSS is normally a F<.rss> file in a tree
being processed by App::DocKnot::Spin. The file consists of one or more
blocks of RFC-2822-style fields with values, each separated by a blank line.
Each field and value looks like an e-mail header field, including possible
continuation lines:
Field: value
continuation of value
lib/App/DocKnot/Spin/Text.pm view on Meta::CPAN
the document (only the HTML C<< <title> >> attribute).
=back
=back
=head1 INSTANCE METHODS
=over 4
=item spin_text_file([INPUT[, OUTPUT]])
Convert a single text file to HTML. INPUT is the path of the input file and
OUTPUT is the path of the output file. OUTPUT or both INPUT and OUTPUT may be
omitted, in which case standard input or standard output, respectively, will
be used.
If OUTPUT is omitted, App::DocKnot::Spin::Text will not be able to obtain
sitemap information even if a sitemap was provided, and therefore will not add
inter-page links.
=back
=head1 NOTES
I wrote this program because every other text to HTML converter that I've seen
made specific assumptions about the document format and wanted you to write
like it wanted you to write rather than like the way you wanted to write.
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
data for the C<\release> and C<\version> commands.
=back
=back
=head1 INSTANCE METHODS
=over 4
=item spin_thread(THREAD[, INPUT])
Convert the given thread to HTML, returning the result. When run via this
API, 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.
INPUT, if given, is the full path to the original source file, used for
relative paths and modification time information.
=item spin_thread_file([INPUT[, OUTPUT]])
Convert a single thread file to HTML. INPUT is the path of the thread file
and OUTPUT is the path of the output file. OUTPUT or both INPUT and OUTPUT
may be omitted, in which case standard input or standard output, respectively,
will be used.
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 relative paths and 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
=head2 Basic Syntax
t/data/generate/remctl/docknot.yaml view on Meta::CPAN
indicate the install prefix, include directory, or library directory.
remctl will automatically build with PCRE support if pcre-config or the
PCRE library are found. You can pass `--with-pcre` to configure to
specify the root directory where PCRE is installed, or set the include and
library directories separately with `--with-pcre-include` and
`--with-pcre-lib`. You can also set `PCRE_CONFIG` to point to a different
pcre-config script, or do similar things as with `PATH_KRB5_CONFIG`
described below.
remctl will automatically build with GPUT support if the GPUT header and
library are found. You can pass `--with-gput` to configure to specify the
root directory where GPUT is installed, or set the include and library
directories separately with `--with-gput-include` and `--with-gput-lib`.
reduced_depends: true
type: Autoconf
distribution:
packaging:
debian:
package: remctl
summary: |
Debian packages are available from Debian as of Debian 3.1
(sarge). For Debian 4.0 (etch) and later, install remctl-server
t/data/generate/remctl/output/readme view on Meta::CPAN
prefix, include directory, or library directory.
remctl will automatically build with PCRE support if pcre-config or the
PCRE library are found. You can pass --with-pcre to configure to
specify the root directory where PCRE is installed, or set the include
and library directories separately with --with-pcre-include and
--with-pcre-lib. You can also set PCRE_CONFIG to point to a different
pcre-config script, or do similar things as with PATH_KRB5_CONFIG
described below.
remctl will automatically build with GPUT support if the GPUT header and
library are found. You can pass --with-gput to configure to specify the
root directory where GPUT is installed, or set the include and library
directories separately with --with-gput-include and --with-gput-lib.
Normally, configure will use krb5-config to determine the flags to use
to compile with your Kerberos libraries. To specify a particular
krb5-config script to use, either set the PATH_KRB5_CONFIG environment
variable or pass it to configure like:
./configure PATH_KRB5_CONFIG=/path/to/krb5-config
If krb5-config isn't found, configure will look for the standard
t/data/generate/remctl/output/readme-md view on Meta::CPAN
indicate the install prefix, include directory, or library directory.
remctl will automatically build with PCRE support if pcre-config or the
PCRE library are found. You can pass `--with-pcre` to configure to
specify the root directory where PCRE is installed, or set the include and
library directories separately with `--with-pcre-include` and
`--with-pcre-lib`. You can also set `PCRE_CONFIG` to point to a different
pcre-config script, or do similar things as with `PATH_KRB5_CONFIG`
described below.
remctl will automatically build with GPUT support if the GPUT header and
library are found. You can pass `--with-gput` to configure to specify the
root directory where GPUT is installed, or set the include and library
directories separately with `--with-gput-include` and `--with-gput-lib`.
Normally, configure will use `krb5-config` to determine the flags to use
to compile with your Kerberos libraries. To specify a particular
`krb5-config` script to use, either set the `PATH_KRB5_CONFIG` environment
variable or pass it to configure like:
```
./configure PATH_KRB5_CONFIG=/path/to/krb5-config
```
t/data/update/remctl/docknot.yaml view on Meta::CPAN
indicate the install prefix, include directory, or library directory.
remctl will automatically build with PCRE support if pcre-config or the
PCRE library are found. You can pass `--with-pcre` to configure to
specify the root directory where PCRE is installed, or set the include and
library directories separately with `--with-pcre-include` and
`--with-pcre-lib`. You can also set `PCRE_CONFIG` to point to a different
pcre-config script, or do similar things as with `PATH_KRB5_CONFIG`
described below.
remctl will automatically build with GPUT support if the GPUT header and
library are found. You can pass `--with-gput` to configure to specify the
root directory where GPUT is installed, or set the include and library
directories separately with `--with-gput-include` and `--with-gput-lib`.
reduced_depends: true
type: Autoconf
copyrights:
- holder: Russ Allbery <eagle@eyrie.org>
years: 2015-2016, 2018
- holder: The Board of Trustees of the Leland Stanford Junior University
years: 2002-2014
description: |
remctl is a client/server application that supports remote execution of
t/data/update/remctl/old/build/middle view on Meta::CPAN
indicate the install prefix, include directory, or library directory.
remctl will automatically build with PCRE support if pcre-config or the
PCRE library are found. You can pass `--with-pcre` to configure to
specify the root directory where PCRE is installed, or set the include and
library directories separately with `--with-pcre-include` and
`--with-pcre-lib`. You can also set `PCRE_CONFIG` to point to a different
pcre-config script, or do similar things as with `PATH_KRB5_CONFIG`
described below.
remctl will automatically build with GPUT support if the GPUT header and
library are found. You can pass `--with-gput` to configure to specify the
root directory where GPUT is installed, or set the include and library
directories separately with `--with-gput-include` and `--with-gput-lib`.
t/lib/Test/DocKnot/Spin.pm view on Meta::CPAN
=over 4
=item fix_pointers(TREE, BASE)
Find all F<*.spin> pointer files in TREE, treat any relative paths found in
those pointer files as if they were relative to BASE, convert them to absolute
paths, and write out the modified pointer file. This is intended to be used
after copying an input tree for App::DocKnot::Spin to a temporary directory,
which would otherwise break any relative paths in pointer files.
=item is_spin_output(OUTPUT, EXPECTED, MESSAGE)
Given OUTPUT, which should be a Path::Tiny object pointing to the output from
App::DocKnot::Spin, compare it to the expected output in the file named
EXPECTED (also a Path::Tiny object). MESSAGE is the message to print with the
test results for easy identification.
=item is_spin_output_tree(OUTPUT, EXPECTED, MESSAGE)
Compare the output tree at OUTPUT with the expected output tree at EXPECTED
(both Path::Tiny objects), using the same comparison algorithm as
is_spin_output() for HTML and RSS files and a straight content comparison for
all other files. MESSAGE with the message to print with the test results for
easy identification.
=back
=head1 AUTHOR
Russ Allbery <rra@cpan.org>
t/spin/tree.t view on Meta::CPAN
use Test::DocKnot::Spin qw(fix_pointers 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
Generating RSS file .../changes.rss
Generating index file .../journal/index.th
Generating RSS file .../journal/index.rss
Generating RSS file .../journal/debian.rss
Generating RSS file .../journal/reviews.rss
Updating .../changes.rss
Spinning .../changes.html
Spinning .../index.html
Creating .../journal
t/spin/tree.t view on Meta::CPAN
Spinning .../reviews/books/0-385-49362-2.html
Creating .../software/docknot/api
Converting .../software/docknot/changes.html
Spinning .../software/docknot/index.html
Converting .../software/docknot/readme.html
Updating .../usefor/drafts/draft-ietf-usefor-message-id-01.txt
Updating .../usefor/drafts/draft-ietf-usefor-posted-mailed-01.txt
Updating .../usefor/drafts/draft-ietf-usefor-useage-01.txt
Updating .../usefor/drafts/draft-lindsey-usefor-signed-01.txt
Converting .../software/docknot/api/app-docknot.html
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.
my $tmpdir = Path::Tiny->tempdir();
my $datadir = path('t', 'data', 'spin');
my $input = $datadir->child('input');
dircopy($input, $tmpdir) or die "Cannot copy $input to $tmpdir: $!\n";
fix_pointers($tmpdir, $input);
# Spin a tree of files.
my $output = Path::Tiny->tempdir();
my $expected = $datadir->child('output');
my $spin = App::DocKnot::Spin->new({ 'style-url' => '/~eagle/styles/' });
my $stdout = capture_stdout { $spin->spin($tmpdir, $output) };
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 = $output->child('bogus');
$bogus->mkpath();
$bogus->child('some-file')->spew_utf8("Some stuff\n");
# Spinning the same tree of files again should do nothing because of the
# modification timestamps.
$stdout = capture_stdout { $spin->spin($tmpdir, $output) };
is($stdout, q{}, 'Spinning again does nothing');
( run in 0.661 second using v1.01-cache-2.11-cpan-4e96b696675 )