App-DocKnot
view release on metacpan or search on metacpan
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
# Generate HTML from the macro language thread.
#
# Thread is a macro language designed for producing HTML pages. This module
# parses thread and generates the corresponding HTML.
#
# SPDX-License-Identifier: MIT
##############################################################################
# Modules and declarations
##############################################################################
package App::DocKnot::Spin::Thread v8.0.1;
use 5.024;
use autodie;
use warnings FATAL => 'utf8';
use App::DocKnot;
use App::DocKnot::Util qw(print_fh);
use Encode qw(decode);
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);
# 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/docknot/';
# The table of available commands. The columns are:
#
# 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],
bold => [1, '_cmd_bold', 1],
break => [0, '_cmd_break', 0],
bullet => [1, '_cmd_bullet', 1],
class => [1, '_cmd_class', 1],
cite => [1, '_cmd_cite', 1],
code => [1, '_cmd_code', 1],
desc => [2, '_cmd_desc', 1],
div => [1, '_cmd_div', 1],
emph => [1, '_cmd_emph', 1],
entity => [1, '_cmd_entity', 0],
h1 => [1, '_cmd_h1', 1],
h2 => [1, '_cmd_h2', 1],
h3 => [1, '_cmd_h3', 1],
h4 => [1, '_cmd_h4', 1],
h5 => [1, '_cmd_h5', 1],
h6 => [1, '_cmd_h6', 1],
heading => [2, '_cmd_heading', 0],
image => [2, '_cmd_image', 1],
include => [1, '_cmd_include', 0],
italic => [1, '_cmd_italic', 1],
link => [2, '_cmd_link', 1],
number => [1, '_cmd_number', 1],
pre => [1, '_cmd_pre', 1],
quote => [3, '_cmd_quote', 1],
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
# $text - The remaining unparsed text
# @args - $count arguments (undef if the argument wasn't found)
sub _extract {
my ($self, $text, $count, $want_format) = @_;
my $format = q{};
my @args;
# Extract the format string if requested.
if ($want_format) {
$format = extract_bracketed($text, '()') // q{};
if ($format) {
$format = substr($format, 1, -1);
}
}
# Extract the desired number of arguments, or all arguments present if
# $count was negative.
if ($count >= 0) {
for my $i (1 .. $count) {
my $arg = extract_bracketed($text, '[]');
if (defined($arg)) {
$arg = substr($arg, 1, -1);
} else {
$self->_warning("cannot find argument $i: $@");
$arg = q{};
}
push(@args, $arg);
}
} else {
while (defined(my $arg = extract_bracketed($text, '[]'))) {
push(@args, substr($arg, 1, -1));
}
}
# Return the results.
return $want_format ? ($format, $text, @args) : ($text, @args);
}
# Expand a macro invocation.
#
# $definition - Definition of the macro
# $block - True if currently in block context
# @args - The arguments to the macro
#
# Returns: List with the macro expansion and the block context flag
sub _macro {
my ($self, $definition, $block, @args) = @_;
# The function that expands a macro substitution marker. If the number of
# the marker is higher than the number of arguments of the macro, leave it
# as-is. (We will have already warned about this when defining the
# macro.)
my $expand = sub {
my ($n) = @_;
return ($n > scalar(@args)) ? "\\\\$n" : $args[$n - 1];
};
# Replace the substitution markers in the macro definition.
$definition =~ s{ \\(\d+) }{ $expand->($1) }xmsge;
# Now parse the result as if it were input thread and return the results.
return $self->_parse_context($definition, $block);
}
# Expand a given command into its representation. This function is mutually
# recursive with _parse_context and _macro.
#
# $command - Name of the command
# $text - Input text following the command
# $block - True if currently in block context (if so, and if the command
# doesn't generate its own container, it will need to be wrapped
# in <p>
#
# Returns: List with the following elements:
# $output - Output from expanding the command
# $block - Whether the output is block context
# $text - Remaining unparsed text
sub _expand {
my ($self, $command, $text, $block) = @_;
# Special handling for expanding variables. These references look like
# \=NAME and expand to the value of the variable "NAME".
if ($command =~ m{ \A = \w }xms) {
my $variable = substr($command, 1);
if (exists($self->{variable}{$variable})) {
return ($self->{variable}{$variable}, 0, $text);
} else {
$self->_warning("unknown variable \\=$variable");
return (q{}, 0, $text);
}
}
# Special handling for macros. Macros shadow commands of the same name.
if (exists($self->{macro}{$command})) {
my ($args, $definition) = $self->{macro}{$command}->@*;
# Extract the macro arguments, if any were requested.
my @args;
if ($args != 0) {
($text, @args) = $self->_extract($text, $args, 0);
}
# The macro runs in a block context if we're currently in block
# context and there is no remaining non-whitespace text. Otherwise,
# use an inline context.
$block &&= $text =~ m{ \A \s* \z }xms;
# Expand the macro.
my ($result, $blocktag) = $self->_macro($definition, $block, @args);
# We have now double-counted all of the lines in the macro body
# itself, so we need to subtract the line count in the macro
# definition from the line number.
#
# This unfortunately means that the line number of errors that happen
# inside macro arguments will be somewhat off if the macro definition
# itself contains newlines. I don't see a way to avoid that without
# much more complex parsing and state tracking.
$self->{input}[-1][2] -= $definition =~ tr{\n}{};
# Return the macro results.
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
} elsif ($block) {
if ($paragraph eq q{}) {
$border = $self->_border_end();
}
$paragraph .= $space . $result;
$nonblock = 1;
} else {
$output .= $result;
$nonblock = 1;
}
$space = q{};
}
# If the next bit of unparsed text starts with a newline, extract it
# and any following whitespace now.
if ($text =~ s{ \A \n (\s*) }{}xms) {
my $spaces = $1;
# Update the line number.
$self->{input}[-1][2] += 1 + $spaces =~ tr{\n}{};
# Add it to our paragraph if we're accumulating one; otherwise,
# add it to the output, but only add the newline if we saw inline
# elements or there is remaining text. This suppresses some
# useless black lines.
if ($paragraph ne q{}) {
$paragraph .= "\n$spaces";
} else {
if ($text ne q{} || $nonblock) {
$output .= "\n";
}
$output .= $spaces;
}
}
}
# If there is any remaining paragraph text, wrap it in tags and append it
# to the output. If we were at block level, our output is always suitable
# for block level. Otherwise, it's suitable for block level only if all
# of our output was from block commands.
if ($paragraph ne q{}) {
$output .= $border . $self->_paragraph($paragraph);
}
return ($output, $block || !$nonblock);
}
## use critic
# A wrapper around parse_context for callers who don't care about the block
# level of the results.
#
# $text - Input text to parse
# $block - True if the parse is done in a block context
#
# Returns: HTML output corresponding to $text
sub _parse {
my ($self, $text, $block) = @_;
my ($output) = $self->_parse_context($text, $block);
return $output;
}
# The top-level function for parsing a thread document. Be aware that the
# working directory from which this function is run matters a great deal,
# since thread may contain relative paths to files that the spinning process
# needs to access.
#
# $thread - Thread to spin
# $in_path - Input file path as a Path::Tiny object, or undef
# $out_fh - Output file handle to which to write the HTML
# $out_path - Output file path as a Path::Tiny object, or undef
# $input_type - Optional one-word description of input type
sub _parse_document {
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->{input_type} = $input_type // 'thread';
$self->{macro} = {};
$self->{out_fh} = $out_fh;
$self->{out_path} = $out_path;
$self->{rss} = [];
$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
# command argument.
#
# The stack of parsed input is maintained in $self->{input} and the file
# being parsed at any given point is $self->{input}[-1]. _cmd_include
# will push new file information into this stack, and we pop off the top
# element of the stack when we exhaust its paragraphs.
while ($self->{input}->@*) {
while (defined(my $para = pop($self->{input}[-1][0]->@*))) {
my $result = $self->_parse(_escape($para), 1);
$result =~ s{ \A (?:\s*\n)+ }{}xms;
if ($result !~ m{ \A \s* \z }xms) {
$self->_output($result);
}
}
pop($self->{input}->@*);
}
# Close open tags and print any deferred whitespace.
print_fh($out_fh, $out_path, $self->_block_end(), $self->{space});
return;
}
##############################################################################
# Supporting functions
##############################################################################
# Generate the format attributes for an HTML tag.
#
# $format - Format argument to the command
#
# Returns: String suitable for interpolating into the tag, which means it
# starts with a space if non-empty
sub _format_attr {
my ($self, $format) = @_;
return q{} if !$format;
# Formats starting with # become id tags. Otherwise, it is a class.
if ($format =~ s{ \A \# }{}xms) {
if ($format =~ m{ \s }xms) {
$self->_warning(qq(space in anchor "#$format"));
}
return qq{ id="$format"};
} else {
return qq{ class="$format"};
}
}
# Split a block of text apart at paired newlines so that it can be reparsed as
# paragraphs, but combine a paragraph with the next one if it has an
# unbalanced number of open brackets. Used to parse the top-level structure
# of a file and by containiners like \block that can contain multiple
# paragraphs.
#
# $text - Text to split
#
# Returns: List of paragraphs
sub _split_paragraphs {
my ($self, $text) = @_;
my @paragraphs;
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
$output .= qq{ href="$url"\n};
$output .= qq{ title="$rss_title" />\n};
}
# Add <link> tags based on the sitemap.
if ($self->{sitemap} && defined($page)) {
my @links = $self->{sitemap}->links($page);
if (@links) {
$output .= join(q{}, @links);
}
}
# End of the header.
$output .= "</head>\n\n";
# Add some generator comments.
my $date = strftime('%Y-%m-%d %T -0000', gmtime());
my $input_path = $self->{input}[-1][1];
my $from = defined($input_path) ? ' from ' . $input_path->basename() : q{};
my $version = $App::DocKnot::VERSION;
$output .= "<!-- Spun$from by DocKnot $version on $date -->\n";
# Add the <body> tag and the navbar (if we have a sitemap).
$output .= "\n<body>\n";
if ($self->{sitemap} && defined($page)) {
my @navbar = $self->{sitemap}->navbar($page);
if (@navbar) {
$output .= join(q{}, @navbar);
}
}
return (1, $output);
}
# Include an image. The size is added to the HTML tag automatically.
#
# $format - Format string
# $image - Path to the image (may be relative or an absolute URL)
# $alt - Alt text of image
sub _cmd_image {
my ($self, $format, $image, $text) = @_;
$image = $self->_parse($image);
$text = $self->_parse($text);
# Determine the size attributes of the image if possible.
my $path = $self->_file_path($image);
my $size = $path->exists() ? q{ } . lc(html_imgsize("$path")) : q{};
# Generate the tag.
my $output = qq{<img src="$image" alt="$text"$size};
$output .= $self->_format_attr($format) . ' />';
return (1, $output);
}
# Include a file. Note that this includes a file after the current paragraph,
# not immediately, which may be a bit surprising.
sub _cmd_include {
my ($self, $file) = @_;
$file = $self->_file_path($self->_parse($file));
# Read the thread, split it on paragraphs, and reverse it to make a stack.
my $thread = $self->_read_file($file);
my @paragraphs = reverse($self->_split_paragraphs($thread));
# Add it to the file stack.
push($self->{input}->@*, [\@paragraphs, $file, 1]);
# Expand into empty output.
return (1, q{});
}
# A link to a URL or partial URL.
#
# $format - Format string
# $url - Target URL
# $text - Anchor text
sub _cmd_link {
my ($self, $format, $url, $text) = @_;
$url = $self->_parse($url);
$text = $self->_parse($text);
my $format_attr = $self->_format_attr($format);
return (0, qq{<a href="$url"$format_attr>$text</a>});
}
# Preformatted text. This does not use _block because we don't want to split
# the contained text into paragraphs and we want to parse it all in inline
# context always.
sub _cmd_pre {
my ($self, $format, $text) = @_;
my $output = $self->_border_end();
$output .= '<pre' . $self->_format_attr($format) . '>';
$output .= $self->_parse($text);
$output .= "</pre>\n";
return (1, $output);
}
# Used for the leading quotes that I have on many of my pages. If the format
# is "broken", adds line breaks at the end of each line.
#
# $format - Format string, used as the format for the main <p> tag inside the
# <blockquote>. Values broken and short trigger special handling,
# such as adding line breaks or changing the attribution class.
# $quote - Text of the quote
# $author - Author of the quote
# $cite - Attribution of the quote
sub _cmd_quote {
my ($self, $format, $quote, $author, $cite) = @_;
$author = $self->_parse($author);
$cite = $self->_parse($cite);
my $output = $self->_border_end() . q{<blockquote class="quote">};
# Parse the contents of the quote in a new block context.
$self->_block_start();
my @paragraphs = $self->_split_paragraphs($quote);
$quote = join(q{}, map { $self->_parse($_, 1) } @paragraphs);
$quote .= $self->_block_end();
# Remove trailing newlines.
$quote =~ s{ \n+ \z }{}xms;
# If this is a broken quote, add line breaks to each line.
if ($format eq 'broken') {
$quote =~ s{ ( \S [ ]* ) ( \n\s* (?!</p>)\S )}{$1<br />$2}xmsg;
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
return (1, q{});
}
my $sitemap = join(q{}, $self->{sitemap}->sitemap());
return (1, $self->_border_end() . $sitemap);
}
# Start a table. Takes any additional HTML attributes to set for the table
# (this is ugly, but <table> takes so many attributes for which there is no
# style sheet equivalent that it's unavoidable) and the body of the table
# (which should consist of \tablehead and \tablerow lines).
sub _cmd_table {
my ($self, $format, $options, $body) = @_;
my $tag = $options ? "table $options" : 'table';
return $self->_block($tag, q{}, $format, $body);
}
# A heading of a table. Takes the contents of the cells in that heading.
sub _cmd_tablehead {
my ($self, $format, @cells) = @_;
my $output = ' <tr' . $self->_format_attr($format) . ">\n";
for (@cells) {
my $text = $self->_parse($_) . $self->_border_end();
$output .= (q{ } x 4) . $self->_enclose('th', $text) . "\n";
}
$output .= " </tr>\n";
return (1, $output);
}
# A data line of a table. Takes the contents of the cells in that row.
sub _cmd_tablerow {
my ($self, $format, @cells) = @_;
my $output = ' <tr' . $self->_format_attr($format) . ">\n";
for (@cells) {
my $text = $self->_parse($_) . $self->_border_end();
$output .= (q{ } x 4) . $self->_enclose('td', $text) . "\n";
}
$output .= " </tr>\n";
return (1, $output);
}
# Given the name of a package, return the version number of its latest
# release.
sub _cmd_version {
my ($self, $package) = @_;
if (!$self->{versions}) {
$self->_warning('no package version information available');
return (0, q{});
}
my $version = $self->{versions}->version($package);
if (!defined($version)) {
$self->_warning(qq(no version known for "$package"));
return (0, q{});
}
return (0, $version);
}
##############################################################################
# Public interface
##############################################################################
# Create a new thread to HTML converter. This object can (and should) be
# reused for all thread conversions done while spinning a tree of files.
#
# $args - Anonymous hash of arguments with the following keys:
# output - Root of the output tree
# sitemap - App::DocKnot::Spin::Sitemap object
# source - Root of the source tree
# style-url - Partial URL to style sheets
# versions - App::DocKnot::Spin::Versions object
#
# Returns: Newly created object
sub new {
my ($class, $args_ref) = @_;
my $output;
if (defined($args_ref->{output})) {
$output = path($args_ref->{output});
}
# 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;
}
# Use a Git::Repository object to get modification timestamps if a source
# tree was specified and it appears to be a git repository.
my ($source, $repository);
if (defined($args_ref->{source})) {
$source = path($args_ref->{source});
if ($source->child('.git')->is_dir()) {
$repository = Git::Repository->new(work_tree => "$source");
}
}
# Create and return the object.
my $self = {
output => $output,
repository => $repository,
sitemap => $args_ref->{sitemap},
source => $source,
style_url => $style_url,
versions => $args_ref->{versions},
};
bless($self, $class);
return $self;
}
# Convert thread to HTML and return the output as a string. The working
# directory still matters for file references in the thread.
#
# $thread - Thread to spin
# $input - Optional input file path (for relative path and timestamps)
#
# Returns: Resulting HTML
sub spin_thread {
my ($self, $thread, $input) = @_;
my $result;
open(my $out_fh, '>:raw:encoding(utf-8)', \$result);
$self->_parse_document($thread, $input, $out_fh, undef);
close($out_fh);
return decode('utf-8', $result);
}
# Spin a single file of thread to HTML.
#
# $input - Input file (if not given, assumes standard input)
# $output - Output file (if not given, assumes standard output)
#
# Raises: Text exception on processing error
sub spin_thread_file {
my ($self, $input, $output) = @_;
my $out_fh;
my $thread;
# Read the input file.
if (defined($input)) {
$input = path($input)->realpath();
$thread = $input->slurp_utf8();
} else {
$thread = slurp(\*STDIN);
}
# Open the output file.
if (defined($output)) {
$output = path($output)->absolute();
$out_fh = $output->openw_utf8();
} else {
open($out_fh, '>&:raw:encoding(utf-8)', 'STDOUT');
}
# Do the work.
$self->_parse_document($thread, $input, $out_fh, $output);
# Clean up.
close($out_fh);
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 path (for relative path and 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) = @_;
$input = path($input);
# Open the output file.
my $out_fh;
if (defined($output)) {
$output = path($output)->absolute();
$out_fh = $output->openw_utf8();
} else {
open($out_fh, '>&:raw:encoding(utf-8)', '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
##############################################################################
1;
__END__
=for stopwords
Allbery DocKnot MERCHANTABILITY NONINFRINGEMENT sublicense NARGS RCS RSS
preformatted respun
=head1 NAME
App::DocKnot::Spin::Thread - Generate HTML from the macro language thread
=head1 SYNOPSIS
use App::DocKnot::Spin::Thread;
my $input = 'some thread';
my $thread = App::DocKnot::Spin::Thread->new();
my $output = $thread->spin_thread($input);
use App::DocKnot::Spin::Sitemap;
use App::DocKnot::Spin::Versions;
my $sitemap = App::DocKnot::Spin::Sitemap->new('/input/.sitemap');
my $versions = App::DocKnot::Spin::Versions->new('/input/.versions');
$thread = App::DocKnot::Spin::Thread->new({
source => '/input',
output => '/output',
sitemap => $sitemap,
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,
List::SomeUtils, and Path::Tiny, all of which are available from CPAN.
=head1 DESCRIPTION
This component of DocKnot implements the macro language thread, which is
designed for writing simple HTML pages using somewhat nicer syntax, catering
to my personal taste, and supporting variables and macros to make writing
pages less tedious.
For the details of the thread language, see L<THREAD LANGUAGE> below.
=head1 CLASS METHODS
=over 4
=item new(ARGS)
Create a new App::DocKnot::Spin::Thread object. A single converter object
can be used repeatedly to convert a tree of files, or can convert a single
file. 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<sitemap> argument. If C<sitemap> 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 and implement the C<\sitemap> command. For inter-page links, the
C<output> argument must also be provided.
=item source
The path to the root of the input tree. If given, and if the input tree
appears to be a Git repository, C<git log> will be used to get more accurate
last modification timestamps for files, which in turn are used to add last
modified dates to the footer of the generated page.
=item style-url
The base URL for style sheets. A style sheet specified in a C<\heading>
command 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.
=item versions
An App::DocKnot::Spin::Versions object. This will be used as the source of
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
A thread file is Unicode text with a blank line between paragraphs.
There is no need to explicitly mark paragraphs; paragraph boundaries will be
inferred from the blank line between them and the appropriate C<< <p> >> tags
will be added to the HTML output.
There is no need to escape any character except C<\> (which should be written
as C<\\>) and an unbalanced C<[> or C<]> (which should be written as
C<\entity[91]> or C<\entity[93]> respectively). Escaping C<[> or C<]> is not
necessary if the brackets are balanced within the paragraph, and therefore is
only rarely needed.
Commands begin with C<\>. For example, the command to insert a line break
(corresponding to the C<< <br> >> tag in HTML) is C<\break>. If the command
takes arguments, they are enclosed in square brackets after the command. If
there are multiple arguments, they are each enclosed in square brackets and
follow each other. Any amount of whitespace (but nothing else) is allowed
between the command and the arguments, or between the arguments. So, for
example, all of the following are entirely equivalent:
\link[index.html][Main page]
\link [index.html] [Main page]
\link[index.html]
[Main page]
\link
[index.html]
[Main page]
(C<\link> is a command that takes two arguments.)
Command arguments may contain paragraphs of text, other commands, and so
forth, nested arbitrarily (although this may not make sense for all arguments
of all commands, of course).
Some commands take an additional optional formatting instruction argument.
That argument is enclosed in parentheses and placed before any other
arguments. It specifies the C<class> attribute for that HTML tag, for use
with style sheets, or the C<id> attribute, for use with style sheets or as an
anchor. If the argument begins with C<#>, it will be taken to be an C<id>.
Otherwise, it will be taken as a C<class>.
For example, a first-level heading is normally written as:
\h1[Heading]
(with one argument). Either of the following will add a class attribute of
C<header> to that HTML container that can be referred to in style sheets:
\h1(header)[Heading]
\h1 (header) [Heading]
and the following would add an id attribute of C<intro> to the heading so that
it could be referred to with the anchor C<#intro>:
\h1(#intro)[Introduction]
Note that the heading commands have special handling for C<id> attributes; see
below for more details.
=head2 Basic Format
There are two commands that are required to occur in every document.
The first is C<\heading>, which must occur before any regular page text. It
takes two arguments: the page title (the title that shows up in the window
title bar for the browser and is the default text for bookmarks, not anything
that's displayed as part of the body of the page), and the style sheet to use.
If there is no style sheet for this page, the second argument is still
required but should be empty (C<[]>).
The second required command is C<\signature>, which must be the last command
in the file. C<\signature> will take care of appending the signature,
appending navigation links, closing any open blocks, and any other cleanup
that has to happen at the end of a generated HTML page.
You can include other files with the C<\include> command, although it has a
few restrictions. The C<\include> command must appear either at the beginning
of the file or after a blank line, and should be followed by a blank line. Be
careful not to include the same file recursively as there is no current
protection against infinite loops.
Thread files will not be automatically respun when included files change, so
you will need touch the thread file to force the corresponding output file to
be regenerated.
All further thread commands are divided into block commands and inline
commands. These roughly correspond to HTML 5's "flow content" and "phrasing
content" respectively.
=head2 Block Commands
Block commands are commands that should occur in a paragraph by themselves,
not contained in a paragraph with other text. They indicate high-level
structural elements of the page. C<\heading> and C<\include> were already
discussed above, but here is a complete list. Any argument of TEXT can be
multiple paragraphs and contain other embedded block commands (so you can nest
a list inside another list, for example).
=over 4
=item \block[TEXT]
Put TEXT in an indented block, equivalent to C<< <blockquote> >> in HTML.
Used primarily for quotations or license statements embedded in regular text.
=item \bullet[TEXT]
TEXT is formatted as an item in a bullet list. This is like C<< <li> >>
inside C<< <ul> >> in HTML, but the surrounding list tags are inferred
automatically and handled correctly when multiple C<\bullet> commands are used
in a row.
Normally, TEXT is treated like a paragraph. If used with a formatting
instruction of C<packed>, such as:
\bullet(packed)[First item]
then the TEXT argument will not be treated as a paragraph and will not be
surrounded in C<< <p> >>. No block commands should be used inside this type
of C<\bullet> command. This variation will, on most browsers, not put any
additional whitespace around the line, which will produce better formatting
for bullet lists where each item is a single line.
=item \desc[HEADING][TEXT]
An element in a description list, where each item has a tag HEADING and an
associated body text of TEXT, like C<< <dt> >> and C<< <dd> >> in HTML. As
with C<\bullet>, the C<< <dl> >> tags are inferred automatically.
=item \div[TEXT]
Does nothing except wrap TEXT in an HTML C<< <div> >> tag. The only purpose
of this command is to use it with a formatting instruction to generate an HTML
C<class> attribute on the C<< <div> >> tag.
=item \h1[HEADING] .. \h6[HEADING]
Level one through level six headings, just like C<< <h1> >> .. C<< <h6> >> in
HTML. If given an C<id> formatting instruction, such as:
\h1(#anchor)[Heading]
then not only will an id attribute be added to the C<< <h1> >> container but
the text of the heading will also be enclosed in an C<< <a name> >> container
to ensure that C<#anchor> can be used as an anchor in a link in older browsers
that don't understand C<id> attributes. This is special handling that only
lib/App/DocKnot/Spin/Thread.pm view on Meta::CPAN
=over 4
=item \break
A forced line break, C<< <br> >> in HTML.
=item \class[TEXT]
Does nothing except wrap TEXT in an HTML C<< <span> >> tag. The only purpose
of this command is to use it with a formatting instruction to generate an HTML
C<class> attribute on the C<< <span> >> tag. For example, you might write:
\class(red)[A style sheet can make this text red.]
and then use a style sheet that changes the text color for class C<red>.
=item \entity[CODE]
An HTML entity with code CODE. This normally becomes C<&CODE;> or C<&#CODE;>
in the generated HTML, depending on whether CODE is entirely numeric.
Use C<\entity[91]> and C<\entity[93]> for unbalanced C<[> and C<]> characters,
respectively.
Thread source is UTF-8, so this command is normally only necessary to escape
unbalanced square brackets.
=item \image[URL][TEXT]
Insert an inline image. TEXT is the alt text for the image (which will be
displayed on non-graphical browsers). Height and width tags are added
automatically if the URL is a relative path name and the corresponding file
exists and is supported by the Perl module Image::Size.
=item \link[URL][TEXT]
Create a link to URL with link text TEXT. Equivalent to C<< <a href> >>.
=item \release[PACKAGE]
If the C<versions> argument was provided, replaced with the latest release
date of PACKAGE. The date will be in the UTC time zone, not the local time
zone.
=item \size[FILE]
Replaced with the size of FILE in B, KB, MB, GB, or TB as is most appropriate,
without decimal places. The next largest unit is used if the value is larger
than 1024. 1024 is used as the scaling factor, not 1000.
=item \version[PACKAGE]
If the C<versions> argument was provided, replaced with the latest version of
PACKAGE.
=back
=head2 Defining Variables and Macros
One of the reasons to use thread instead of HTML is the ability to define new
macros on the fly. If there are constructs that are used more than once in
the page, you can define a macro at the top of that page and then use it
throughout the page.
A variable can be defined with the command:
\=[VARIABLE][VALUE]
where VARIABLE is the name that will be used (can only be alphanumerics plus
underscore) and VALUE is the value that string will expand into. Any later
occurrence of \=VARIABLE in the file will be replaced with <value>. For
example:
\=[FOO][some string]
will cause any later occurrences of C<\=FOO> in the file to be replaced with
the text C<some string>. Consider using this to collect external URLs for
links at the top of a page for easy updating.
A macro can be defined with the command:
\==[NAME][NARGS][DEFINITION]
where NAME is the name of the macro (again consisting only of alphanumerics or
underscore), NARGS is the number of arguments that it takes, and DEFINITION is
the definition of the macro.
When the macro is expanded, any occurrence of C<\1> in the definition is
replaced with the first argument, any occurrence of C<\2> with the second
argument, and so forth, and then the definition with those substitutions is
parsed as thread, as if it were written directly in the source page.
For example:
\==[bolddesc] [2] [\desc[\bold[\1]][\2]]
defines a macro C<\bolddesc> that takes the same arguments as the regular
C<\desc> command but always wraps the first argument, the heading, in C<<
<strong> >>.
=head1 AUTHOR
Russ Allbery <rra@cpan.org>
=head1 COPYRIGHT AND LICENSE
Copyright 1999-2011, 2013, 2021-2023 Russ Allbery <rra@cpan.org>
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<docknot(1)>, L<App::DocKnot::Spin>, L<App::DocKnot::Spin::Sitemap>,
L<App::DocKnot::Spin::Versions>
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<https://www.eyrie.org/~eagle/software/docknot/>.
=cut
# Local Variables:
# copyright-at-end-flag: t
# End:
( run in 1.506 second using v1.01-cache-2.11-cpan-39bf76dae61 )