| < App::DocKnot::Spin::Text | Russ Allbery > Software > DocKnot | App::DocKnot::Spin::Versions > |
(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.
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:
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.
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.
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.
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.
An App::DocKnot::Spin::Versions object. This will be used as the source of
data for the \release and \version commands.
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.
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.
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.
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).
Put TEXT in an indented block, equivalent to <blockquote> in HTML.
Used primarily for quotations or license statements embedded in regular 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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
A horizontal rule, <hr> in HTML.
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.
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)]
]
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.
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 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:
A forced line break, <br> in HTML.
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.
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.
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.
Create a link to URL with link text TEXT. Equivalent to <a href>.
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.
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.
If the versions argument was provided, replaced with the latest version of
PACKAGE.
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-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.
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/>.
| < App::DocKnot::Spin::Text | Russ Allbery > Software > DocKnot | App::DocKnot::Spin::Versions > |