SBLG(1)

NAME
sblg - simple off-line blog utility

SYNOPSIS
sblg [-C file] [-o file] [-s sort] [-t template] [-ac] file ...

DESCRIPTION
The sblg utility knits together XML articles and templates in four ways.

•   Standalone mode (-c) links single articles with a template with an article stub, which is filled in with the article. For example, "sblg -c foo.xml bar.xml" creates foo.html and bar.html from a template populated by the foo.xml and bar.xml article contents, respectively.

•   Blog amalgamation mode links multiple articles with a template consisting of articles and navigation stubs. For example, "sblg -o foo.html bar.html baz.html" links bar.html and baz.html into foo.html from a template.

•   Atom amalgamation mode (-a) link multiple articles with an Atom feed template.

•   Standalone amalgamation mode (-C) links multiple articles in standalone style, i.e., multiple navigation stubs, a single article stub. For example, "sblg -o foo.html -C bar.html baz.html bar.html" will show only bar.html in the article list of foo.html, but both bar.html and baz.html in its navigation.

By default, sblg operates as blog amalgamation mode, specifically as if "sblg -o blog.html -t blog-template.xml ..." were specified. Its arguments are as follows:

-C file
    Like -c, but creating a blog amalgamation. In effect, an amalgamation with a single <article data-sblg-article="1">. Ignored when used with -a or -c.

-o file
    Output file. If unspecified, standalone articles have .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 amalgamation, blog.html is used by default. If unspecified for the Atom feed amalgamation, atom.xml is used by default. Use -o - for standard output.

-s sort
    Change how articles are sorted before being written into navigation or article entries. The default is date, which sorts newest-oldest by date. You can also specify filename, which sorts in increasing A-Z alphabetical order of the source filename. Lastly, cmdline does not sort and uses the command-line order.

-t template
    Template for standalone or amalgamation files. If unspecified, defaults to article-template.xml for -c, atom-template.xml for -a, and blog-template.xml otherwise.

-a  Creates an Atom feed amalgamation from its input files.

-c  Create standalone articles instead of merging together articles into an amalgamation.

file ...
    Input files. In standalone mode with -c, input XML files are merged with a template into an output file. Otherwise, multiple input files are merged into a single amalgamation.

All input and output must be well-formed XML. 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
Article input files consist of XML fragments or whole documents. They must at least 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>content</b>.
      </aside>
      <p>Some text.</p>
    </article>

When processed with sblg, all data outside of the <article data-sblg-article="1"> element is discarded. Then the article title (both as text data only and inclusive of markup) is extracted from the first <hn> (header 1–4), article publication date is extracted from the datetime attribute of the first <time> (which must be a date, YYYY-MM-DD, or time, YYYY-MM-DDTHH:MM:SSZ), and author (both as text data only and inclusive of markup) from the first <address>.

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, and no tags.

The first <aside>, if provided, is used for the feed content. 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.

data-sblg-lang
    This tag may only be specified on the article element and specifies one or more space-separated languages for the document. These languages are removed in the “stripping” operations for the Tag Symbols.

data-sblg-sort
    Override 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-tags
    This tag may be specified on any element within the article and consists of space-separated tag names. These tags are extracted for navigation tag operation.

There may be be multiple articles within a single document, for example,

    <articles>
      <article data-sblg-article="1"></article>
      <article data-sblg-article="1"></article>
      <article data-sblg-article="1"></article>
    </articles>

The element(s) containing the articles is ignored. If you have multiple articles and are using -c, only the first article is compiled.

  Standalone Template
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>

See Tag Symbols for a list of symbols that will be replaced if found in attribute value or textual contexts.

  Blog Amalgamation Template
The amalgamation 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>

Each <article> will be followed by a (permanent link) anchor within a <div> with the custom class "data-sblg-permlink". Note: the permanent link is set to the article name, so if you specify an XML file, it will be to an XML file!

The navigation element may contain several attributes. The Boolean data-sbgl-navcontent attribute makes the mark-up content of the <nav> be processed as specified in Tag Symbols. If not specified, sblg populates the list with article title text in a link and the publication date. If the <nav> element contains a positive integer data-sblg-navsz attribute, this is used to limit the number of navigation entries. Finally, if the data-sblg-navtag is specified, only articles with matching tags are shown. You can specify multiple space-separated tags, for instance, 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. Lastly, the data-sblg-navstart attribute specifies how many articles will skip being displayed (so if you have tags, it will only account for articles that would meet those tags) before showing the first navigation entry. This starts at one (a value of zero is the same as a value of one).

The article element may contain only the data-sblg-articletag attribute. This is similar in function to the data-sblg-navtag attribute in limiting displayed articles to those matching the space-separated tags. You may also set a Boolean data-sblg-permlink attribute that stipulates whether the permanent link is specified.

  Standalone Amalgamation Template
This is identical to the Blog Amalgamation Template except that a single article is noted with -C, and this is the only article displayed in the article stub. 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.

Note: 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.

  Atom Amalgamation Template
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.

    <?xml version="1.0" encoding="utf-8"?>
    <feed xmlns="http://www.w3.org/2005/Atom">
      <title>Example Feed</title>
      <link href="http://example.org/feed/" rel="self" />
      <link href="http://example.org/" />
      <updated data-sblg-updated="1" />
      <id data-sblg-id="1" />
      <entry data-sblg-entry="1" />
      <entry data-sblg-entry="1" />
      <entry data-sblg-entry="1" />
    </feed>

The <updated> element with a Boolean data-sblg-updated attribute is replaced with the newest article date (or the current date, if no articles are listed). The <id> element with a Boolean data-sblg-id attributed is replaced with an identifier in the form of tag:domain,2013:path, where the domain is initialised to the current domain or extracted from the <link> to the self. The path is also extracted from the self <link>, initialised to the root path ‘/’.

Each <entry> element with a Boolean data-sblg-entry attribute is filled in with a <title>, <id> (in tag format), <author>, HTML <content> (specified in the article as an <aside>), and alternate <link>. If the entry element contains a false data-sblg-altlink Boolean attribute, the alternate <link> is not printed. Furthermore, if a true data-sblg-content Boolean attribute exists, the article's contents (everything within the <article data-sblg-article="1">) are inlined within the <content> element with type html.

No Tag Symbols are processed.

  Tag Symbols
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.

${sblg-aside}
    The article's first aside with markup.

${sblg-asidetext}
    The article's first aside, textual parts only.

${sblg-author}
    The article's author with markup.

${sblg-authortext}
    The article's author, textual parts only

${sblg-base}
    The full filename (including directory) 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-date}
    The publication date.

${sblg-first-base}
    The first (newest) base name in the list of articles. There are also ${sblg-first-stripbase} and ${sblg-first-striplangbase} variants. (See ${sblg-base}).

${sblg-last-base}
    The last (oldest) base name in the list of articles. There are also ${sblg-last-stripbase} and ${sblg-last-striplangbase} variants. (See ${sblg-base}).

${sblg-next-base}
    The next base name when chronologically ordered from newest to oldest, wrapping back to the beginning for the last. There are also ${sblg-next-stripbase} and ${sblg-next-striplangbase} variants. (See ${sblg-base}).

${sblg-prev-base}
    The previous base name when chronologically ordered from newest to oldest, wrapping back to the beginning for the last. There are also ${sblg-prev-stripbase} and ${sblg-prev-striplangbase} variants. (See ${sblg-base}).

${sblg-source}
    The source file when passed for parsing.

${sblg-title}
    The article title with markup.

${sblg-titletext}
    The article title, textual parts only.

${sblg-url}
    The output filename, which is empty for standard output.

${sblg-pos}
    The position (from 1) of the articles actually shown. (So if data-sblg-navstart is used, this will still show 1.) This is only valid in a <nav data-sblg-nav="1"> context.

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.

FILES

article-template.xml
    Default template for creating articles with -c.

atom-template.xml
    Default template for creating atom feeds with -a.

blog-template.xml
    Default template for creating a front page.

EXIT STATUS

EXAMPLES
First, create standalone HTML5 files from article fragments. An article-template.xml file is assumed to exist.

    % 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

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

AUTHORS
The sblg utility was written by Kristaps Dzonsons, kristaps@bsd.lv.

CAVEATS
Boolean XML values must have an attribute specified. In other words, <foo bar="1"> is valid, while <foo bar> is not.