Provided by: docknot_7.01-1_all bug

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.

SEE ALSO

       docknot(1), App::DocKnot::Spin, App::DocKnot::Spin::Sitemap, 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
       <https://www.eyrie.org/~eagle/software/docknot/>.