view release on metacpan or  search on metacpan

lib/App/DocKnot/Spin/Thread.pm  view on Meta::CPAN

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: