Ubuntu Manpage: App::DocKnot::Spin::Thread - Generate HTML from the macro language thread

NAME

       App::DocKnot::Spin::Thread - Generate HTML from the macro language thread

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'
           );

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.

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 "THREAD LANGUAGE" below.

CLASS METHODS

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:

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 "sitemap"
argument. If "sitemap" is given, this option should also always be given.

sitemap
An App::DocKnot::Spin::Sitemap object. This will be used to create inter-page links and
implement the "\sitemap" command. For inter-page links, the "output" argument must also be
provided.

source
The path to the root of the input tree. If given, and if the input tree appears to be a Git
repository, "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.

style-url
The base URL for style sheets. A style sheet specified in a "\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 ".css"
appended.

versions
An App::DocKnot::Spin::Versions object. This will be used as the source of data for the
"\release" and "\version" commands.

INSTANCE METHODS

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.

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.

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.

THREAD LANGUAGE

   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 "<p>" tags will be added to the HTML output.

       There  is  no need to escape any character except "\" (which should be written as "\\") and an unbalanced
       "[" or "]" (which should be written as "\entity[91]" or "\entity[93]" respectively).  Escaping "[" or "]"
       is not necessary if the brackets are balanced within the paragraph, and therefore is only rarely needed.

       Commands begin with "\".  For example, the command to insert a line break (corresponding  to  the  "<br>"
       tag in HTML) is "\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]

       ("\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 "class" attribute for that HTML tag,
       for  use  with  style  sheets,  or the "id" attribute, for use with style sheets or as an anchor.  If the
       argument begins with "#", it will be taken to be an "id".  Otherwise, it will be taken as a "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  "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 "intro" to the heading so that it could be referred to
       with the anchor "#intro":

           \h1(#intro)[Introduction]

       Note that the heading commands have special handling for "id" attributes; see below for more details.

   Basic Format
       There are two commands that are required to occur in every document.

       The first is "\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
       ("[]").

       The  second  required  command is "\signature", which must be the last command in the file.  "\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  "\include"  command, although it has a few restrictions.  The
       "\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.

   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.  "\heading" and "\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).

       \block[TEXT]
           Put TEXT in an indented block, equivalent to "<blockquote>" in HTML.  Used primarily  for  quotations
           or license statements embedded in regular text.

       \bullet[TEXT]
           TEXT  is  formatted  as an item in a bullet list.  This is like "<li>" inside "<ul>" in HTML, but the
           surrounding list tags are inferred  automatically  and  handled  correctly  when  multiple  "\bullet"
           commands are used in a row.

           Normally,  TEXT is treated like a paragraph.  If used with a formatting instruction of "packed", such
           as:

               \bullet(packed)[First item]

           then the TEXT argument will not be treated as a paragraph and will not be surrounded  in  "<p>".   No
           block  commands  should  be used inside this type of "\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.

       \desc[HEADING][TEXT]
           An element in a description list, where each item has a tag HEADING and an associated  body  text  of
           TEXT, like "<dt>" and "<dd>" in HTML.  As with "\bullet", the "<dl>" tags are inferred automatically.

       \div[TEXT]
           Does  nothing except wrap TEXT in an HTML "<div>" tag.  The only purpose of this command is to use it
           with a formatting instruction to generate an HTML "class" attribute on the "<div>" tag.

       \h1[HEADING] .. \h6[HEADING]
           Level one through level six headings, just  like  "<h1>"  ..  "<h6>"  in  HTML.   If  given  an  "id"
           formatting instruction, such as:

               \h1(#anchor)[Heading]

           then  not only will an id attribute be added to the "<h1>" container but the text of the heading will
           also be enclosed in an "<a name>" container to ensure that "#anchor" can be used as an  anchor  in  a
           link  in  older  browsers  that don't understand "id" attributes.  This is special handling that only
           works with "\h1" through "\h6", not with other commands.

       \heading[TITLE][STYLE]
           Set the page title to TITLE and the style sheet to STYLE  and  emit  the  HTML  page  header.   If  a
           "style-url"  argument  was  given,  that  base URL will be prepended to STYLE to form the URL for the
           style sheet; otherwise, STYLE will be used verbatim as a URL except with ".css" appended.

           This command must come after any "\id" or "\rss" commands and may  come  after  commands  that  don't
           produce  any  output  (such  as  macro definitions or "\include" of files that produce no output) but
           otherwise must be the first command of the file.

       \id[ID]
           Sets the Subversion, CVS, or RCS revision number and time.  ID should be  the  string  "$Id$",  which
           will  be  expanded  by Subversion, CVS, and RCS.  This string is embedded verbatim in an HTML comment
           near the beginning of the generated output, and is used to determine last  modified  information  for
           the file (used by the "\signature" command).

           For this command to behave properly, it must be given before "\heading".

       \include[FILE]
           Include  FILE  after  the  current  paragraph.  If multiple files are included in the same paragraph,
           they're included in reverse order, but this behavior may change in later versions and should  not  be
           relied  on.   It's  strongly  recommended  to always put the "\include" command in its own paragraph.
           Don't put "\heading" or "\signature" into an included file; the results won't be correct.

       \number[TEXT]
           TEXT is formatted as an item in a numbered  list,  like  "<li>"  inside  "<ol>"  in  HTML.   As  with
           "\bullet" and "\desc", the surrounding tags are inferred automatically.

           As  with "\bullet", a formatting instruction of "packed" will omit the paragraph tags around TEXT for
           better formatting with a list  of  short  items.   See  the  description  under  "\bullet"  for  more
           information.

       \pre[TEXT]
           Insert  TEXT  preformatted,  preserving spacing and line breaks.  This uses the HTML "<pre>" tag, and
           therefore is normally also shown in a fixed-width font by the browser.

           When using "\pre" inside indented  blocks  or  lists,  some  care  must  be  taken  with  indentation
           whitespace.  Normally, the browser indents text inside "\pre" relative to the enclosing block, so you
           should  only  put  as  much  whitespace  before each line in "\pre" as those lines should be indented
           relative to the enclosing text.  However lynx, unfortunately, indents relative to the left margin, so
           it's difficult to use indentation that looks correct in both lynx and other browsers.

       \quote[TEXT][AUTHOR][CITATION]
           Used for quotes at the top of a web page.

           The whole text will be enclosed in a "<blockquote>" tag with class "quote" for  style  sheets.   TEXT
           may  be  multiple  paragraphs.   Any  formatting  instruction  given  to "\quote" will be used as the
           formatting instruction for each paragraph in TEXT (so an "id" is normally not appropriate).

           If the formatting instruction is "broken", line breaks in TEXT will be honored  by  inserting  "<br>"
           tags at the end of each line.  Use this for poetry or other cases where line breaks are significant.

           A  final  paragraph  will  then  be  added  with class "attribution" if the formatting instruction is
           "broken" or "short" and class "long-attrib" otherwise.  This paragraph will  contain  the  AUTHOR,  a
           comma, and then CITATION.  CITATION will be omitted if empty.

       \rss[URL][TITLE]
           Indicates  that  this  page  has  a corresponding RSS feed at the URL URL.  The title of the RSS feed
           (particularly important if a page has more than one feed) is given by TITLE.

           The feed links are included in the page header output by "\heading", so this command  must  be  given
           before "\heading" to be effective.

       \rule
           A horizontal rule, "<hr>" in HTML.

       \sitemap
           Inserts a bullet list showing the structure of the whole site.  A "sitemap" argument must be provided
           to  the  constructor  to use this command.  (If invoked via App::DocKnot::Spin, this means a .sitemap
           file must be present at the root of the source directory.)

           Be aware that spin doesn't know whether a file contains a "\sitemap" command and hence won't know  to
           regenerate  a  file when the .sitemap file has changed.  You will need touch the source file to force
           it to be respun.

       \table[OPTIONS][BODY]
           Creates a table.

           The OPTIONS text is added verbatim to the <table> tag in the generated HTML, so it can be used to set
           various HTML attributes like "cellpadding" that aren't easily accessible in a portable  fashion  from
           style sheets.

           BODY  is  the  body  of  the  table,  which  should generally consist exclusively of "\tablehead" and
           "\tablerow" commands.

           An example table:

               \table[rules="cols" borders="1"][
                   \tablehead [Older Versions]     [Webauth v3]
                   \tablerow  [suauthSidentSrvtab] [WebAuthKeytab]
                   \tablerow  [suauthFailAction]   [WebAuthLoginURL]
                   \tablerow  [suauthDebug]        [WebAuthDebug]
                   \tablerow  [suauthProxyHeader]  [(use mod_headers)]
               ]

       \tablehead[CELL][CELL] ...
           A heading row in a table.  "\tablehead" takes any number of CELL  arguments,  wraps  them  all  in  a
           "<tr>" table row tag, and puts each cell inside "<th>".

           If  a  cell  should  have  a class attribute, use a "\class" command around the CELL text.  The class
           attribute will be "lifted" up to become an attribute of the enclosing "<th>" tag.

       \tablerow[CELL][CELL] ...
           A regular row in a table.  "\tablerow" takes any number of CELL arguments, wraps them all in a "<tr>"
           table row tag, and puts each cell inside "<td>".

           If a cell should have a class attribute, use a "\class" command around  the  CELL  text.   The  class
           attribute will be "lifted" up to become an attribute of the enclosing "<td>" tag.

   Inline Commands
       Inline  commands  can  be used in the middle of a paragraph intermixed with other text.  Most of them are
       simple analogs to their HTML counterparts.  All of the following take a  single  argument  (the  enclosed
       text), an optional formatting instruction, and map to simple HTML tags:

           \bold       <b></b>                 (usually use \strong)
           \cite       <cite></cite>
           \code       <code></code>
           \emph       <em></em>
           \italic     <i></i>                 (usually use \emph)
           \strike     <strike></strike>       (should use styles)
           \strong     <strong></strong>
           \sub        <sub></sub>
           \sup        <sup></sup>
           \under      <u></u>                 (should use styles)

       Here are the other inline commands:

       \break
           A forced line break, "<br>" in HTML.

       \class[TEXT]
           Does nothing except wrap TEXT in an HTML "<span>" tag.  The only purpose of this command is to use it
           with  a  formatting  instruction  to  generate  an  HTML  "class" attribute on the "<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 "red".

       \entity[CODE]
           An HTML entity with code CODE.  This normally becomes "&CODE;" or "&#CODE;" in  the  generated  HTML,
           depending on whether CODE is entirely numeric.

           Use "\entity[91]" and "\entity[93]" for unbalanced "[" and "]" characters, respectively.

           Thread  source  is  UTF-8,  so  this  command  is normally only necessary to escape unbalanced square
           brackets.

       \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.

       \link[URL][TEXT]
           Create a link to URL with link text TEXT.  Equivalent to "<a href>".

       \release[PACKAGE]
           If  the "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.

       \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.

       \version[PACKAGE]
           If the "versions" argument was provided, replaced with the latest version of PACKAGE.

   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  "\=FOO" in the file to be replaced with the text "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 "\1" in the definition is replaced with the first argument,
       any  occurrence  of  "\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 "\bolddesc" that takes the same arguments as the regular "\desc" command but always wraps
       the first argument, the heading, in "<strong>".

AUTHOR

       Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

       Copyright 1999-2011, 2013, 2021-2022 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.