SBLG(1) | General Commands Manual | SBLG(1) |
sblg
— static blog
utility
sblg |
[-acjlLrV ] [-C
file] [-o
file] [-s
sort] [-t
template] file ... |
The sblg
utility merges XML articles and
templates in a number of ways.
-c
) merges a single article's
content and metadata into a template. For example, "sblg -o- -c
foo.xml" merges foo.xml into the template
article-template.xml.-C
) links multiple articles'
content and metadata in standalone style. For example, "sblg -o- -C
bar.xml baz.xml" will show content for only
bar.xml, but metadata for both inputs. The similar
-L
flags runs the process for each input file
without reparsing.-a
) merges multiple articles into an
Atom feed template.-j
) merges all articles into a JSON
feed.By default, sblg
operates in blog mode
with template blog-template.xml. Its arguments are
as follows:
-a
-c
-l
-r
to have tag-major order and
-j
for JSON output. Specify
-l
twice to show matches (tags for article-major,
articles for tag-major) all on one tab-separated line, instead of one per
line.-r
-l
tag listing in
“tag-major” order wherein the first column is the tag and
the second column is the article. If the -j
flag
is specified, this is JSON formatted.-j
-l
is specified, the tag
listing will be displayed in JSON instead. See
JSON Schema for details.-C
file-c
, but creating a blog with a single
<article data-sblg-article="1">
for the file while using the remaining arguments are
other files used in <nav
data-sblg-nav="1">
.-L
-C
, but acting on all input files,
translating the input to output files such as in
-c
without -o
. If there
are multiple articles in an output file, the output is recreated for each
(so only the last will remain). So running with “article0.xml
article1.xml” will produce “article0.html
article1.html” as if -C
were seperately
specified for both. This avoids needing to parse all inputs for each
input.-o
file.html
appended to the input file name, unless the
input file extension is .xml
, in which case the
.xml
is replaced by .html
.
If multiple input files are specified, -o
is
ignored. If unspecified for the blog, blog.html is
used by default. If unspecified for the Atom feed or JSON,
atom.xml or blog.json,
respectively, is used by default. Use -o
- for standard output.-s
sort-t
template-c
,
atom-template.xml for -a
,
and blog-template.xml otherwise.sblg-xx.yy.zz
and exits.-c
, input XML
files are merged with a template into an output file. Otherwise, multiple
input files are merged into a single blog.All input must be well-formed XML. (Element names and attributes
are case-sensitive.) HTML is assumed only with the default suffix re-write
rule for -c
without -o
.
Input articles may be XML fragments or full documents: only the
<article data-sblg-article="1">
tree
within the article is considered.
Article input files consist of XML fragments or whole documents. They usually consist of the following within the document:
<article data-sblg-article="1"> <header> <h1>Article Name</h1> <address>Author Name</address> <time datetime="2013-06-29">29 June, 2013</time> </header> <aside> This is used as the feed <b>abstract</b>. </aside> <p> Some text in the <b>content</b>. <img src="foo.jpg" alt="An image for the feed" /> </p> </article>
When processed with sblg
, all data outside
of the <article
data-sblg-article="1">
element is discarded. Then the
article is scanned for the following:
<hn>
(header
1–4);<time>
(which must be a date,
YYYY-MM-DD, or time, YYYY-MM-DDTHH:MM:SSZ) interpreted in UTC;<address>
;<aside>
is used for the feed
abstract; and<img>
is associated as the
article's image.These are all set once: subsequent invocations will not override
prior setting. See data-sblg-aside
,
data-sblg-author
,
data-sblg-datetime
,
data-sblg-img
, and
data-sblg-title
for explicitly setting or overriding
these values.
If unspecified, the default article title text (and mark-up) is "Untitled article", the default author text (and mark-up) is the "Unknown author", the publication time is set to the document's file-system creation time, the abstract is left empty, and the image is empty.
All content is recorded in case the
data-sblg-content
Boolean value is used in an Atom
feed.
There are a number of special attributes that are recognised in the input file.
data-sblg-aside=string
<aside>
element. It overrides the previously
set aside. The alternative data-sblg-const-aside
only sets the aside if it has not yet been set.<address>
element. It overrides the
previously set author. The alternative
data-sblg-const-author
only sets the author if it
has not yet been set.data-sblg-datetime=datetime
<time>
element. This
must be YYYY-MM-DD or YYYY-MM-DDTH:MM:SSZ. It overrides the previously set
date. The alternative data-sblg-const-datetime
only sets the date if it has not yet been set.data-sblg-img=url
data-sblg-const-img
only
sets the image if it has not yet been set.data-sblg-lang=string
<article>
and
specifies one or more space-separated languages for the document. You can
escape spaces with a backslash (“\”) if you have spaces in
the tag name, e.g., “foo\ bar”. These languages are removed
in the “stripping” operations for the
Tag Symbols.data-sblg-set-xxx=string
data-sblg-set-foo="bar"
sets
the foo
keyword to bar
. If
specified multiple times for the same key, only the last value is used.
These may be retrieved with ${sblg-get}
or queried
with ${sblg-has}
of the
Tag Symbols.data-sblg-sort=first|last
<article>
element and
overrides the article's position relative to other articles. This can be
either first
or last
. If
multiple articles have the same sort override, they are ordered in the
natural way.data-sblg-source=file
data-sblg-title=string
<hN>
element. It overrides the previously
set title. The alternative data-sblg-const-title
only sets the title if it has not yet been set.The standalone template file must be a well-formed XML file where
the first <article
data-sblg-article="1">
element is replaced by the
article text. All of this element's children are removed.
<body> <header>This consists of a single blog entry.</header> <article>This is kept.</article> <article data-sblg-article="1">This is removed.</article> <footer>Something.</footer> </body>
Article templates may contain the following attributes:
data-sblg-article=boolean
data-sblg-ign-once=boolean
<article
data-sblg-article="1">
element contains this set to
true, the element is not processed as an article and the
data-sblg-ign-once
attribute is removed.See Tag Symbols for a list of symbols that will be replaced if found in attribute value or textual contexts. These may occur anywhere in the template document.
The blog template file must also be a well-formed XML file where
each <article data-sblg-article="1">
element is replaced by ordered (by default, newest to oldest) article
contents. If there aren't enough articles, the element is removed.
Furthermore, <nav data-sblg-nav="1">
elements are replaced by the same list of articles within an unordered
list.
Usually, the <article>
tags are used
for displaying full articles, while <nav>
tags
are used for displaying navigation to articles, such as just their titles,
dates, and links.
<body> <header>This consists of two blog entries.</header> <nav data-sblg-nav="1" /> <article data-sblg-article="1" /> <article data-sblg-article="1" /> <footer>Something.</footer> </body>
Article templates may contain several attributes.
data-sblg-article=boolean
data-sblg-articletag=string
<article
data-sblg-article="1">
element contains this, limit
displayed articles to those matching the space-separated tags or
${sblg-get|xxx}
when in -L
or -C
mode. This scans for tags from the current
article in the list of articles.data-sblg-ign-once=boolean
<article
data-sblg-article="1">
element contains this set to
true, the element is not processed as an article and the
data-sblg-ign-once
attribute is removed.data-sblg-permlink=boolean
<article
data-sblg-article="1">
element contains this set to
true, a permanent link to the article's input filename is emitted after
the <article
data-sblg-article="1">
within a
<div data-sblg-permlink="1">
element.The navigation element may contain several attributes.
<nav>
within an unordered list item for each
article shown, replacing Tag Symbols
for the current article. If not true, sblg
populates an unordered list with article title text in a link and the
publication date.-s
.
Uses the same names. If the search name is not recognised, the attribute
is silently ignored and the global search order used.<nav>
element contains this attribute
with a positive integer, it is used to limit the number of navigation
entries.data-sblg-navtag="foo bar"
will search
for foo or bar. Tags to be matched against are extracted from the
space-separated data-sblg-tags
element of each
article's topmost <article>
element. Escape
spaces with a backslash (“\”) if you have spaces in the tag
name, e.g., “foo\ bar”. Use
${sblg-get|xxx}
or (for multi-word values)
${sblg-get-escaped|xxx}
when in
-C
or -L
mode to use the
current article's set data as part of a string, e.g.,
location-${sblg-get|location}
.data-sblg-navcontent
, but without the
surrounding list elements. The data-sblg-navxml
attribute does not print any additional
<nav>
, <ul>
,
or <li>
HTML tags and can be used to
generate custom XML files, such as sitemaps.This is identical to the Blog
Template except that a single article is noted with
-C
, and this is the only article displayed in the
article stub. Furthermore, like in standalone mode,
Tag Symbols may be used anywhere in
the document template and refer to the current article unless within a
navigation element, in which case the symbol resolves to the
currently-printed article. In the given example,
<body> <header>This consists of two blog entries.</header> <nav data-sblg-nav="1" /> <article data-sblg-article="1" /> <article data-sblg-article="1" /> <footer>Something.</footer> </body>
the navigation would be populated by all articles, but only the first article stub would be filled in with the specified article. The second would be removed.
This follows the usual rules of
data-sblg-articletag
, so if the article you specify
with -C
doesn't have the correct tag, it won't
inline the article.
The Atom template file must be a well-formed XML file where each
<entry>
element with a Boolean
data-sblg-entry
attribute is replaced by ordered
(newest to oldest) article information. If there aren't enough articles, the
element is removed. The template may contain pre-existing entries.
The following is a minimal template: anything less will not conform to the Atom specification:
<?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <link href="http://example.org" /> <title>A Title Here</title> <updated /> <id /> <entry data-sblg-entry="1" data-sblg-forall="1" /> </feed>
The recognised elements are as follows. Un-recognised elements are printed verbatim.
<entry
data-sblg-entry="1">
<id>
<link [rel="alternate"]>
, which
must exist. Otherwise, the value is copied and used for subsequent feed
entries.<link
[rel="alternate"]>
<id>
is provided, the
href
attribute must be a full URL, e.g.,
<link
href="https://kristaps.bsd.lv/">
. Otherwise, it may be
a relative path. This element
must be
first.<updated>
There are a number of special attributes that may be given to the above elements.
data-sblg-altlink=boolean
<entry data-sblg-entry="1">
element contains this set to true, the alternate
<link>
is printed.data-sblg-altlink-fmt=string
data-sblg-entry
and
data-sblg-altlink
are true for an
<entry>
, the value is used as the link
address. Accepts Tag Symbols, most
commonly being ${sblg-base}
.data-sblg-atomcontent=boolean
<entry data-sblg-entry="1">
contains this set to true, the contents are printed directly and the
Tag Symbols are processed. This
overrides data-sblg-altlink
and
data-sblg-content
.data-sblg-content=boolean
<entry data-sblg-entry="1">
contains this set to true, the article's contents (everything within the
<article data-sblg-article="1">
)
are inlined within the <content>
element
with type html
.
Tag Symbols are processed.data-sblg-entry=boolean
<entry>
element with this is filled in
with article content.data-sblg-forall=boolean
<entry data-sblg-entry="1">
element contains this set to true, it is used for all remaining articles.
Any <entry data-sblg-entry="1">
following this are discarded.If not using data-sblg-atomcontent
,
entries are filled in with a <title>
,
<id>
, <author>
,
HTML <content>
(specified in the article as an
<aside>
), and alternate
<link>
. The <id>
is constructed by appending the source filename, hash print, and date
following the feed's <id>
or
<link>
element.
When filling in HTML content, sblg
will
strip away HTML attributes that do not fit into a white-list. This
white-list is defined by the W3C's Feed Validator.
sblg
can produce JSON with the
-j
flag. The schema is documented in
/usr/local/share/sblg/schema.json. If
-l
is specified, the output schema is simply an
array as follows. Let source1.xml and
source2.xml be input files with a variety of
tags.
[ {"src": "source1.xml", "tags": ["tag1","tag2"]}, {"src": "source2.xml", "tags": ["tag1"]} ]
If, however, -r
is also specified, the
reverse format is used:
[ {"tag": "tag1", "srcs": ["source1.xml","source2.xml"]}, {"tag": "tag2", "srcs": ["source1.xml"]} ]
Within the template for -c
or
-C
, or in any article contents written (either into
an article or navigation entry), the following special strings are replaced.
These symbols concern the current article being processed: in a navigation
entry, or as article contents. In the event of the positional
“next” and “prev” symbols, these refer to the
article's position within the input articles. Obviously,
-c
has only a single article.
In general, these must be considered strict values, e.g.,
${sblg-aside}
and not ${ sblg-aside
}
. Some symbols accept optional arguments, which have the format
${sblg-tags[|argument]}
. Here,
|argument
may be omitted.
${sblg-abscount}
<nav data-sblg-nav="1">
, otherwise
it always prints 1. See also ${sblg-count}
and
${sblg-setcount}
.${sblg-abspos}
<nav
data-sblg-nav="1">
context, otherwise it always prints
1. See also ${sblg-pos}
.${sblg-aside}
${sblg-asidetext}
${sblg-realbase}
${sblg-base}
, and having the same sub-types,
except deriving from ${sblg-real}
.${sblg-base}
${sblg-source}
but with the last suffix
part chopped off. For example, foo/bar.xml becomes
foo/bar. The
${sblg-stripbase}
variant will strip off the
directory part and any sufix. For example,
foo/bar.xml becomes bar.
The ${sblg-striplangbase}
variant will also strip
the language. For example, if “en” language was specified on
the article, foo/bar.en.xml becomes
bar.${sblg-count}
<nav
data-sblg-nav="1">
, it's the total number within the
navigation. See also ${sblg-abscount}
and
${sblg-setcount}
.${sblg-date}
${sblg-datetime}
${sblg-datetime-fmt[|fmt]}
%x
) or date-time (%c
) is
printed.${sblg-img}
${sblg-first-base}
${sblg-first-stripbase}
and
${sblg-first-striplangbase}
variants. See
${sblg-base}
.${sblg-last-base}
${sblg-last-stripbase}
and
${sblg-last-striplangbase}
variants. See
${sblg-base}
.${sblg-next-base}
${sblg-next-stripbase}
and
${sblg-next-striplangbase}
variants. See
${sblg-base}
.${sblg-next-has}
sblg-next-has
if there exists a next
article in the ordered set, otherwise prints nothing.${sblg-pos}
<nav>
context), it shows the position in
the input files. Within a <nav>
context, it
shows the position within the navigation.${sblg-pos-frac}
${sblg-pos}/$(sblg-count}
.${sblg-pos-pct}
${sblg-pos-frac}
.${sblg-prev-base}
${sblg-prev-stripbase}
and
${sblg-prev-striplangbase}
variants. See
${sblg-base}
.${sblg-prev-has}
sblg-prev-has
if there exists a previous
article in the ordered set, otherwise prints nothing.${sblg-get[|key]}
key
assigned in
data-sblg-set-key
. If unspecified or the key was
not found, this is ignored and omitted from output. The lookup is case
sensitive.${sblg-get-escaped[|key]}
${sblg-get[|key]}
, but escapes the value of
the key so that it may be used for
data-sblg-navtag
or
data-sblg-articletag
attribute values for
multi-word tags.${sblg-has[|key]}
${sblg-get[|key]}
, but queries with the
key
exists. If it is specified and it does exist,
then the string sblg-has-key
is printed. This is
useful in class
attributes to test whether a given
key has been specified.${sblg-setcount}
${sblg-count}
, but only the articles matching
the requested tags. See also ${sblg-count}
and
${sblg-abscount}
.${sblg-real}
${sblg-source}
for an overridable source
indicator.${sblg-source}
tagspec
. If the prefix is not
specified, all tags. Each tag (e.g., TAG) is listed as
<span
class="sblg-tag">TAG</span>
. If no tags were
found, a single <span
class="sblg-tags-notfound"></span>
is
emitted.${sblg-title}
${sblg-titletext}
${sblg-url}
${sblg-version}
sblg
version as
xx.yy.zz
.Be careful in using these: the contents are copied directly, so if specifying a value within an HTML attribute that has a double-quote, the attribute will be prematurely closed.
-c
.-a
.The sblg
utility exits 0 on
success, and >0 if an error occurs.
First, create standalone HTML5 files (filled-in
<article data-sblg-article="1">
)
from article fragments. An article-template.xml file
is assumed to exist. This will create article1.html
and article2.html from the re-write rule for the XML
suffix.
% sblg -c article1.xml
article2.xml
Next, merge formatted files into a front page. A blog-template.xml file is assumed to exist.
% sblg -o index.html article1.html
article2.html
This will create index.html with filled-in
<article data-sblg-article="1">
and
<nav data-sblg-nav="1">
elements.
Combining the above two examples, we can specify a single article to be displayed along with a full navigation as follows:
% sblg -o article1.html -C
article1.xml article1.xml article2.xml
This will fill the contents of
article1.xml into the <article
data-sblg-article="1">
but use both (along with any
others) in the <nav
data-sblg-nav="1">
.
If we want to make an output article as in the above example for
each element of the input, we could either run -C
for each input element, or use -L
to avoid
re-running sblg
for each input article, which can be
costly for many articles!
% sblg -L article1.xml
article2.xml
This re-writes the suffixes and fills in the
<article data-sblg-article="1">
for
article1.xml in
article1.html, and so on. For each of these, it will
fill in <nav data-sblg-nav="1">
.
Input files and templates must be properly-formed XML files. Output files are guranteed to be XML as well. The Atom file template must be well-formed; output is guaranteed to satisfy the Atom 1.0 and Tag ID standards.
The sblg
utility was written by
Kristaps Dzonsons,
kristaps@bsd.lv.
Boolean XML values must have an attribute specified. In other
words, <foo bar="1">
is valid, while
<foo bar>
is not.
Since input is recognised as XML and
not HTML5, special
characters must be specified as unicode code-point numbers and not HTML
element names. For example, you must use …
instead of …
.
March 7, 2021 | OpenBSD 6.7 |