App::DocKnot::Spin::Thread(3pm) | User Contributed Perl Documentation | App::DocKnot::Spin::Thread(3pm) |
App::DocKnot::Spin::Thread - Generate HTML from the macro language thread
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' );
Perl 5.24 or later and the modules Git::Repository, Image::Size, List::SomeUtils, and Path::Tiny, all of which are available from 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 "THREAD LANGUAGE" below.
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.
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.
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 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).
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.
\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.
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.
For this command to behave properly, it must be given before "\heading".
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.
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.
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.
The feed links are included in the page header output by "\heading", so this command must be given before "\heading" to be effective.
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.
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)] ]
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.
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 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:
\class(red)[A style sheet can make this text red.]
and then use a style sheet that changes the text color for class "red".
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.
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>".
Russ Allbery <rra@cpan.org>
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.
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/>.
2022-01-20 | perl v5.32.1 |