NAME

ii - Infernal Icecube, a command-line weblog tool.


SYNOPSIS

ii [flags] blog command [argument]

ii markup [filename] [--markup-output=filename]


DESCRIPTION

Infernal Icecube (as the name clearly suggests) is a program which allows you to manage one or more weblogs from a Unix command line.

It can also be used as a standalone HTML generator.

Features include:

Additionally, it is guaranteed not to turn you into a fourteen-year-old girl.


BLOGGING OVERVIEW

Before you start, you will need to have rcs and tar installed on your system. rcs is freely available and tar is standard on all Unix-like operating systems. You will also (obviously) need a reasonably recent version of Perl. (I use Perl 5.8.3 but any 5.6.x version should work although you may need to install your own Net::FTP module.)

Initialization

We start by creating a blog:

ii myblog create

This creates an empty blog named myblog as well as the blog directory IIBlog and the file .iirc in your home directory. (Actually, those last two are created by the first nontrivial command you try, excepting markup).

You may want to look at the file .iirc to see if the default settings are reasonable. If rcs or tar are installed off the path or with nonstandard names, you can set the paths to them in this file. You can also set your preferred text editor here.

Setting the Template

Now, we set a template.

To get a list of available templates, type:

ii myblog templates

Currently, there is very little to choose from, but it is reasonably simple to make your own. See below for details.

We set the template like this:

ii myblog template purplehaze

You can now preview your blog if you want. The command is:

ii myblog preview

This will open your preferred web browser on the generated front page. Since there's no content, however, it won't look particularly good.

Hint: you can use the --no-browser option to refresh the blog without launching another browser:

ii myblog preview --no-browser

If you use a graphical web browser and already have it open on the blog, you can then just hit its refresh button to see the updated blog.

Adding Entries

To add an entry, type:

ii myblog add

This will launch your preferred text editor.

Entries are structured to look like USENET posts (or email messages, fine). You will probably want to change the text after the ``Subject:'' line to something appropriate and your content goes after the the first blank line.

The text markup ii uses is modeled after the conventions used in USENET and text-based email. It is described in more detail below.

Once you have typed in your text, saved and quit the editor, your post will now be in the system.

ii will print out the article's ID number:

    Entry stored with ID 1

Publishing

New entries are not actually posted until you explicitly mark them as published. This lets you keep an article in the CMS while you work on it, all without affecting the blog's visible contents. To mark a blog as published, use the publish command:

ii myblog publish 1

The last argument, ``1'' in this case, is the article ID.

If you preview your blog now, you'll see the new entry.

Listing articles

You can get a list of available articles with the list command:

ii myblog list

This will list all unpublished articles.

To list all articles, use the --all flag:

ii myblog list --all

Articles marked with an asterisk (``*'') are published.

Blog Configuration

Next, we configure the blog. Type this:

ii myblog config

It will bring up your preferred text editor on the blog's configuration file. Edit the fields as necessary. The comments should make this self-explanatory.

If you intend to publish your blog on a website, you will need to set the fields ServerName, ServerUID, ServerPasswd and ServerWebDir. Your web server will need to be accessible by FTP. If you are behind a firewall, you may also need to set UsePassive to 1.

Besides upload parameters, you can also set various formatting parameters here, including the blog's title, copyright message and permanent links to other websites.

Uploading

Now that you have content and have (hopefully) set the server parameters correctly, it's time to broadcast your teen angst and bad poetry to the world.

Before you do this for the first time, you will need to log onto your web server with your preferred FTP client and create the destination directory for your blog. This is a feature. If it can't find the destination directory, ii assumes that your config information is wrong and punts rather than risking accidentally ``cleaning up'' a directory full of valuable files.

Once the destination directory exists, uploading is as simple as typing:

ii myblog upload

Assuming everything is correctly configured, this should do it.

Enabling RSS

If you wish to enable RSS syndication, edit the config file by typing

ii myblog config

Set the option Syndication to 1 and set the option SiteURL to the base URL of your website. Then, upload the site again. Your site will now have an RSS file named rss-feed.xml.

Note that ii syndicates using RSS 2.0. No other syndication format is supported.


USING II AS AN HTML GENERATOR

If you are not interested in blogging but wish to use ii as a tool to generate HTML from marked-up text (see MARKUP, below), you can do this with the markup command, like this:

ii markup filename

Output goes to stdout. If the filename is ``-'', input is taken from stdin.

Note that the resulting HTML is suitable for inserting between the <BODY> and </BODY> tags of an HTML document and is not by itself a complete HTML document. This is a feature. It lets you add headers, footers, style sheets and so on:

cat header.txt > mydoc.html

ii markup mydoc.txt >> mydoc.html

cat footer.txt >> mydoc.html

Unlike other commands, markup does not create or modify any of the usual ii configuration or content files or directories.


COMMANDS AND OPTIONS

The ii command line takes the form:

ii blog-name command [options] [arguments]

blog-name must consist of ``word'' characters (alpha-numeric plus underscore) except that the first character must be alphabetical.

It is an error if the named blog does not exist unless the command is markup or create.

command is one of the commands listed below.

options is one of the options listed below with the commands. Any option may be used with any command but it is likely to be ignored unless otherwise documented. The options --help and --version are valid for all commands (or, indeed, no command at all). Options may appear anywhere in the command line.

arguments is the list of arguments needed by the command.

Only one instance of ii can access the CMS directory (typically ~/IIBlog/) at once. If you perform an ii command before the previous one has finished, ii will wait for it to finish before continuing. Note that this applies to all blogs in the directory--ii will wait even if the previous command is being performed on another blog.

Commands:

add

Creates a blank blog entry, starts up your editor on it and puts the resulting file into the blog, printing out the new article's ID. The intermediate file is called ~/.ii.article and is left behind in case you need to recover its contents after a crash of some kind.

If the file is unchanged, the operation is cancelled and no changes are made to the blog.

config

Starts up your preferred editor on the named blog's configuration file.

create

Creates the named blog if it does not already exist.

edit article-id

Edit the existing entry with the given article-id.

list [--all] [count]

List blog entries. If --all is given, lists all blog entries (with published entries marked with an asterisk (``*'')). Otherwise, only lists unpublished entries.

If count is given and is a positive integer, it restricts the output to that many of the most recent items.

Items are listed by article ID, not publication date.

markup [--markup-output=output-file] filename

Converts the contents of filename (which should contain marked-up text) to html. If filename is -, input is taken from stdin. If --markup-output is given, its argument is the name of the output file. Otherwise, output goes to stdout. See USING II AS AN HTML GENERATOR above.

preview [--no-browser] [--regenerate] [--browser=path]

Open a web browser on the blog. If necessary, ii will (re)render some or all of the blog's HTML first. If --regenerate is given, ii will regenerate everything from scratch.

If --browser is given, the argument is executed as the web browser's command line instead of the value of the ``BrowserPath'' field in ~/.iirc. Note that the argument is treated exactly the same as BrowserPath--it is executed by the shell, with %s--if given--replacing the name of the file to view. Placing & at the end of the command (properly quoted to keep your shell's grubby hands off of it, of course) will make the browser run in the background.

If --no-browser is given, preview will regenerate the blog's HTML but will not open a browser on it. This is useful if you already have a browser open on it and running in the background.

publish id

Mark the article with id as published. That means that the the next time you do an upload, its contents will be uploaded to your website along with the rest of the blog.

This is identical to editing the article and setting the ``Publish:'' header to ``Yes''.

The first time an article is marked published, the header field ``Publish-Date:'' is set to the current time and day. This date is used to sort articles in the index and on the front page with the more recent articles appearing first.

remove [--force] article-id

Deletes the article with ID number article-id from the blog. If --force is given, it does not first prompt you for confirmation.

All versions of the article are removed. However, the latest version is appended to the file _removed in the blog directory so if you want to make absolutely, postively sure that the article is gone, you need to also delete that file.

revert article-id version

Reverts the article with ID article-id to the version given by version. This does not remove any versions after version. Instead, it fetches that version and creates a new version of the document with identical contents.

Thus, you can undo any revert by simply doing another revert to the previous latest version.

(ii is very reluctant to throw anything away. If you want to permanently delete a version of an article for security reasons, say, you will need to use rcs directly. See THE CMS DIRECTORY below for more details.)

snarf filename

Import the contents of filename (which must be an RFC822-format file) as a new article. Missing fields are added and set to default values. If filename is -, then the contents are read from stdin. In practice, non-RFC822 articles will also work unless they look similar enough to confuse ii. In that case, you may have to clean it up by hand.

The purpose of this command is to make it easy to blog email messages or USENET posts.

template [template-name]

Set the template for the given blog. If template-name is a bare word, possibly ending with the extension .tpl, ii searches its template directory for a template of the given name. If it is a path to a template file, ii uses that template instead.

If template-name is missing, ii lists the installed templates.

unpublish article-id

Mark the article with ID article-id as not published. Unpublished articles do not get uploaded to the website. This is identical to editing the file and setting the ``Published:'' header to ``No''.

Unpublishing and republishing does not modify an article's position in the blog. To do that, you need to edit the ``Publish-Date:'' header.

upload [--regenerate] [--all]

Copy changes to this blog to the remote web server. If necessary, some or all of the html is first generated.

If --regenerate is given, all of the HTML is first regenerated from scratch.

Generally, ii tries to be economical with bandwidth and only upload the files it knows have changed. However, if --all is given, ii will first delete all HTML, CSS and image files in the destination directory, then upload the entire blog.

versions article-id

Lists the revisions of an article. Each line of the list contains version number followed by the date of that version. The version number is what you need to give ii when doing a revert.

Universal Options:

--help

Print out a brief summary of the commands and options, then exit.

--version

Print out the version number, copyright information and various legal disclaimers, then exit.

--blog-root=s

Sets the blog directory to use. Overrides the default (~/IIBlog) or whatever has been set in ~/.iirc.

--quiet

Disable (some) output messages.

--verbose

Display more output. In particular, it makes rcs display messages.


EXTERNAL PROGRAMS

ii requires the following external programs to be present and runnable by the current user.

In theory, ii will exit gracefully if one of these programs is missing when needed. Also theoretically, none of these programs except for perl is necessary for running ii with the markup command.


ARTICLE FORMAT

Individual blog entries are stored in RFC822 format. This is the format used by Internet email messages and by USENET news posts.

An article consists of a series of headers, one per line, followed by a blank line, followed by the actual content. Headers consist of a sequence of non-whitespace characters followed by a colon (``:'') followed by arbitrary text up to the end of the line. Lines beginning with whitespace are considered continuations of the previous header line.

Here is an example:

    Subject: Stupid Fortune Quote #4
    Date: 2006/09/13 10:52:39
    Publish-Date: 0000/00/00 00:00:00
    Publish: No
    I distrust a man who says when.  If he's got to be careful not to
    drink too much, it's because he's not to be trusted when he does.
            -- Sidney Greenstreet, "The Maltese Falcon"

There are four headers that ii uses:

Subject:

This is becomes the article's title. It is the heading when viewing it and the description in the big list of articles. It may contain HTML markup.

Date:

This is the time and date of the last modification of the article. Editing an article will change this.

Publish:

This is a boolean (i.e. either ``Yes'' or ``No''). If ``Yes'', this article will be published on your blog the next time you perform an upload operation. This is changed by the publish and unpublish commands.

Publish-Date:

This is the date that the article was first published. Initially, it will contain a date of all zeroes. The first time an article is published with the publish command, this field will be set to the current time and date and will not be modified after that.

Publish-Date: is used to determine the order in which articles appear in the blog.

Unknown headers are ignored by ii so it is safe to import email messages or USENET posts.

The headers are visible when you edit an article and you may edit them as necessary. (WARNING: this capability isn't very well tested.)


MARKUP

ii markup is modeled after the conventions used in ASCII-based e-mail and USENET news postings. This makes the source text easily human-readable while still producing decent HTML.

It is very similar to Markdown.

General Things

Headings

Headings consist of a line of text followed by a line of ``='' or ``-'' characters followed by a blank line. The underline must start at the beginning of the line to distinguish it from a horizontal rule.

Example:

        This Is A Heading
        =================

produces something like:

        <h1>This Is A Heading</h1>

If you use ``-'' instead of ``='', the HTML tag is ``h2'' instead of ``h1''.

You don't actually need to underline the whole heading. A single underline character is all you need:

        This Is Another Heading
        =

This will work fine. It just looks ugly.

Horizontal Rules

Horizontal rules (horizontal lines running the width of the document, denoted by the ``hr'' tag in HTML) are denoted with a line of one or more ``='' or ``-'' characters. The line must either begin with at least one whitespace character or be separated from the previous text line by at least one empty line. Otherwise, it is interpreted as a heading.

The line must contain all the same character. That is, you can use ``='' or ``-'' but not a mixture of the two.

Here are some examples:

        foo
        ======
        bar

is an HR.

So is this:

        foo
           ---
        bar

But not this:

        foo
        ---
        bar

The underline turns ``foo'' into a heading.

Neither is this:

        foo
         =-=
        bar

because the line characters are mixed.

Jumps

Jumps are logical separators. If an article contains a jump, everything after itwill not be shown on the front page and section before it will end with a link labeled ``(Read more...)'' pointing to the entire article text.

In the actual article page (and in html generated using the markup command) jumps are ignored.

Jumps are denoted with a single line containing three asterisks (``*'') by themselves in a row.

Example:

        Before the jump.
           * * *
        After the jump

Whitespace is entirely ignored in the jump line.

Paragraphs

Paragraphs are separated by either blank lines or by a first line that is indented with some whitespace. The latter case sometimes does not work if the previous text item was not also a paragraph. In practice, this doesn't mean anything because there's usually a blank line between the first paragraph and whatever non-paragraph element which preceded it, making it a paragraph by way of the blank-line delimiter.

Some examples:

        Example Heading
        ===============
        This is paragraph 1.
        This is paragraph 2.
        This is paragraph 3.

Using the other indentation style:

        Example Heading
        ===============
                This is the first
        paragraph.
                This is the second
        paragraph.  And there's
        more text here.
                This is the third
        paragraph.

Lists

Lists consist of a sequence of of list items. A list item is one or more paragraphs where the first line starts with a particular character sequence.

For unordered (bullet) lists, the list item starts with ``+''. For ordered (numbered) lists, the list item starts with a number followed by either ``.'' or ``)'' characters. The actual number used is ignored by ii. In either case, the character sequence must be followed by at least one whitespace character:

        + valid list item
        +invalid list item

List items may contain multiple paragraphs. However, these must be separated by a blank line (the indented first line notation doesn't work here) and the first line of each subsequent paragraph must be indented to the depth of the start of the text of the first line (not the paragraph character sequence).

For example:

        Here is an unordered list
        + foo
        + bar
        + quux

If each list item is just one line, you don't need to separate them with blanks, although you can.

         Here's an ordered list:
        1) one
        2) two
        3) three
           three-a
        4) four

Note the second paragraph in item 3).

HTML

ii normally just passes HTML tags through unless they can be interpreted as markup characters. However, it is also possible to pass blocks of HTML through completely unmodified.

Such blocks are denoted by a line starting with a simple HTML tag and ending with the closing tag on its own line. The tag may not contain attributes, must be on the start of the line and may not be followed by anything other than whitespace.

For example:

        This text gets treated as ordinary ii markup.
        <p>
        This text gets passed through verbatim.
        </p>

ii does not parse the HTML between the tags. Therefore, both the opening and closing tags must be at the start of the line. (The above example has been indented because it is an example. It must be unindented to work correctly.)

If the tag is ``html'', the outermost tag is discarded. Any other tag is passed through as part of the block. ii does nothing to ensure that the tag is valid HTML.

Block Quotes

Block quotes are denoted by beginning each line with a ``>'' character. This is the quoting convention used in email and USENET messages. For example:

        This is original text.
        >This is *quoted text*.
        >
        >So is this.
        And here's more original text.

All markup elements work in a block-quoted region. Thus, block quotes can be nested:

        This is outer text.
        >This is quoted text.
        >
        >>This is quoted text within the quoted text.
        And this is more unquoted text.

(Note: the examples are indented because that's the convention of this document. If you paste them into a text editor and run ii on them, you'll have to undo the indentation or it won't work. But you already knew that, right?)

Bold and Italic

You can mark text as bold or italic (i.e. using the <B> and <I> tags) by surrounding the text to emphasize with, respectively, asterisks (``*'') and underbars (``_'').

For example:

        The word *bold* is in *bold*.  And the word _italic_ is in
        _italic_.

Bold and italic markers are limited to their toplevel structure (i.e. paragraph, list item or heading). The end of the structure also ends the formatting. Something like this:

        First *paragraph.
        Second paragraph.
        Third* paragraph.

will not behave the way you would naively expect. You would think that in the resulting text, everthing from the first instance of the word ``paragraph'' to the word ``Third'' would be bold. However, this is not the case. The bold region ends with the first paragraph and the ``*'' in the third paragraph is interpreted as the start of another bold region. To get the desired effect, you would need to do this:

        First *paragraph.*
        *Second paragraph.*
        *Third* paragraph.

Additionally, when combining bold and underlined text, the underlined region must be inside the bold region. A ``*'' also closes any underline that had been started.

Thus, this:

        foo *bar _quux_ bobo*

Produces this:

        <p>foo <b>bar <i>quux</i> bobo</b></p>

while this:

        foo _bar *quux* bobo_

produces this:

        <p>foo <i>bar </i><b>quux</b> bobo</p>

This limitiation is a bug (or at least a quirk) of ii and may at some point be fixed. This means that you can't reliably depend on a bold closing an italic, or on a paragraph end closing either one of them.

You have been warned.

Links and Inline Images

Links (i.e. URLs) are denoted with square brackets (``['' and ``]''). In their simplest form, the URL just goes between the brackets:

        I like to read [http://www.slashdot.org].

In this case, the URL is also the link text. If you wish to set your own link text, you do that by putting that first, followed by a vertical bar (``|'') before the URL in the brackets. For example:

        I like to read [Slashdot|http://www.slashdot.org].

You may also escape the vertical bar (``|'') or closing square bracket (``]'') with a backslash if you need to put one in your URL or description. For example:

        [\|\]|http://wackyurl.com/wackyurl/\|\|\]boing]

produces this link:

        <a href="http://wackyurl.com/wackyurl/||]boing">|]</a>

As you can see, the ``|'' and ``]'' were passed through.

The desription text may also contain bold or underlined text. If so, the bold or underlined region should be properly closed. If not, it will end with the end of the link text, although this may change with later versions.

Footnotes

Footnotes are a Very Special case of links.

You can link to a footnote by placing a number between square brackets. For example:

    I found the software to be of enterprise quality[1].

The resulting rendered code looks much the same except that the square-bracketted number is now a link to the matching footnote below.

The footnote itself looks just like a paragraph except that the first characters of the first line must be the link number in square brackets. For example:

        [1] For the usual values of "enterprise".

(Note: in this case, the indentation is misleading. The footnote line must start at the start of the line.)

Only digits may go between the brackets. If you need to put a link to a footnote, just make the link look like a link:

        [1|1] This is not a footnote.

Similarly, footnote links are somewhat ambiguous since bare numbers may be valid URLs in some rare cases. The trick above--using the footnote number as a label--will not work in this case. ii assumes a link is a footnote if the URL is a bare integer and the label is missing or identical to the URL.

You can force ii to treat a numeric link as a link instead of a footnote by making the label different from the URL:

        This[one|1] link uses a completely different label.
        This[1 |1] link puts some whitespace in the label.
        This[1|./1] link puts pathway information in the URL.

Or, just give your local filenames some non-digit characters.


CONFIGURATION

ii creates several configuration files on startup. These can be edited with your preferred text editor.

Entries take the form KEY=VALUE where KEY is one of the keywords described below and VALUE is an arbitrary string. Leading and trailing whitespace characters around VALUE are trimmed off. If you need to store a value with leading or trailing spaces, you're pretty much out of luck.

An empty value is allowed and leaves the key unset.

Blank lines are ignored and comments are delimited by a # character at the start of the line.

There are two kinds of configuration file: the global configuration and the blog-local configuration files.

The Global Configuration File

The global configuration file is called .iirc and is located in your home directory. It contains options and settings that apply to all of your blogs.

Many of these are the paths to common Unix utilities. ii will initialize these using your path when it first creates the global configuration file and you will generally not need to change this.

If you remove these entries, ii will search the path for the program with the expected name.

Here are the valid entries:

BlogRoot

The absolute path to your IIBlog directory. Defaults to ``~/IIBlog/''.

Editor

Path to the external editor to use. If unset, uses the result of the VISUAL or EDITOR environment variables.

CheckoutPath

Path to co, the rcs command to perform a checkout.

CheckinPath

Path to ci, the rcs command to perform a checkin.

RLogPath

Path to rlog, the rcs command to output a file's revision history.

TarPath

Path to your tar program.

BrowserPath

The browser command to execute when previewing. This is a complete command-line executed on your shell and so may contain command-line arguments and a trailing ampersand (``&'') to set the browser running in the background. If the command-line contains the sequence '%s', that is replaced with the name of the file to edit. Otherwise, the filename is appended to the end and the ampersand, if present, relocated to a spot behind it.

Blog Configuration Files

In addition to the global configuration file, there is also a configuration file for each blog. It is automatically created as part of the blog. You edit it with the config command:

ii myblog config

Blog configuration files have the same syntax as the global configuation file.

The following key values are allowed in the blog config file:

Title

This is the title of your blog. It should not contain any markup.

RichTitle

This is also the title of your blog but may contain HTML markup. If unset, the value of ``Title'' is used instead.

SubTitle

This is the subtitle of your blog. This text replaces the ``<!--SUBTITLE-->'' template field and so may contain HTML markup if you wish.

SiteDisclaimer

This is a short disclaimer that appears on each page, usually next to the copyright message. It replaces <!--DISCLAIMER--> in the template. It may contain HTML markup.

CopyrightMsg

This is the copyright message that goes at the bottom of the page. It may contain HTML markup.

FrontPageMax

This is the maximum number of articles to display on the front page.

RecentPaneContentSize

This is the maximum number of articles to display in the ``Recent Contents'' pane of the front page.

HeadingLink

HeadingLink entries are a way for you to put various permanent links at the top of your page to, for example, link to a web page containing contact information.

For example:

    HeadingLink=Slashdot|www.slashdot.org

HeadingLink entries take the form ``HeadingLink=<link>'' where <link> is a link in the format used in the markup language (i.e. a label followed by ``|'' followed by the URL). As in markup, the label is optional and if omitted, you should also omit the ``|''. You may have as many HeadingLink entries as you want.

HeadingLinkSep

This is the sequence that gets placed between HeadingLink items in the final page. This may contain HTML.

What is an appropriate value for this also depends on the template you are using. For example, the template 'purplehaze' requires that this field be ``</li><li>'' because it places the content in a list. For other templates, this is not required and does not generate valid HTML.

This property could be considered a bug.

HeaderScript

This field contains arbitrary HTML that is placed in the article's <HEAD> section, usually after the title. It is mostly here to let you use HaloScan without altering the existing template.

ArticleScript

This field contains arbitrary HTML that is placed near the end of each article. The order of replacement guarantees that the ARTICLE_ID will be expanded *after* this text, so it is safe to use that tag here.

It is mostly here to let you use HaloScan without altering the existing template.

ServerName

The name or IP number of the web server that will be hosting your blog.

ServerUID

This is the username of your account on the web server.

ServerPasswd

This is the password of your account on the web server.

Note that this is stored in the clear. Be sure to set your permissions correctly to prevent anyone who shouldn't know the password from reading it.

ServerWebDir

This is the path on the server to the directory to which your website will be uploaded.

UsePassive

If True (i.e a non-zero, non-empty numeric value) your FTP upload will be done in passive mode. This is necessary if you are uploading from behind a firewall.

Syndication

If true (i.e. a non-zero, non-empty numeric value), this flag enables RSS syndication. The next time you update this blog, ii will also generate and upload the front page as an RSS file.

SiteURL

This is the base URL of your blog. That is, it is the URL of the directory containing all of the blog's files. This is used to set the article URL in RSS items. You must set this if you've enabled syndication.


TEMPLATES

Templates determine how your blog will look. ii includes four templates but it is often worthwhile to create your own (or to adapt something you downloaded from www.oswd.org). This section describes how to do this.

A template consists of a single file with the extension ``.tpl''. However, this is really just a standard Unix tar file which follows these conventions:

The only files ii uses are article_template.html and main_template.html. Other files are allowed so that you can add style sheets, images, scripts and so forth.

Templates are ordinary HTML files with special tags inserted. These tags are replaced with blog content when the page is rendered.

Tags look like ordinary HTML comments except that the text of the comment consists only of the tag word and nothing else, including whitespace. So the SUBJECT tag would look like this:

        <!--SUBJECT-->

ii will replace this with the article's subject line when rendering.

main_template.html

The main template is the basis for each blog page. main_template.html should be a complete HTML file. The following tags may be used in main_template.html:

TITLE

This is the blog's title, taken from the blog's config file.

RICHTITLE

This is also the blog's title but this version allows HTML tags.

SUBTITLE

This is the blog's subtitle. It may contain HTML tags.

LINKS

This is a series of hyperlinks seperated by some other sequence of characters. Links are given in the HeadingLink blog config file entry and the separator by HeadingLinkSep. You will need to coordinate their values with the template.

RECENT_LIST

This expands into a list of links to the last few articles. The links are separated by <br> tags.

CONTENTS

This expands into the page's contents.

CONTENTS_LINK

This is a link to the contents page. That's the page that contains a complete list of articles.

COPYRIGHT_MSG

This is the copyright message as taken from the blog's config file.

DISCLAIMER

This is the site disclaimer as taken from the blog's config file. It usually appears near the copyright message.

HDR_SCRIPT

This is an arbitrary snippet of HTML inside the HEAD section of the template and after the title. The snippet comes from the HeaderScript field in the blog configuration file. Its main use is to let you insert snippet to insert the required HaloScan scripts without modifying the template.

article_template.html

The article template is the basis for each individual article in a page. The front page's contents consists of multiple expansions of the article template while the article's page contains only one. Thus, article templates should be written to allow multiple repetitions in the same document.

The following tags may be used in an article template:

TEXT

This is the actual text of the article. Depending on context, it may be the entire text or the text before the first jump.

SUBJECT

This is the article's subject line.

POSTED_DATE

This is the date that the article was first posted. (Actually, it's the date that you first used the publish command on this article, but we assume that's close enough for our purposes.)

MODIFIED_DATE

This is the date of the last modification. Note that publication does not count as modification.

PERMALINK

This expands into the (relative) URL of the page containing the full text of this article. This functions as a permanent link to the article so long as you don't move your website around.

ARTICLE_ID

This expands into the article number. It is useful if you need a unique identifier for the article.

ART_SCRIPT

This expands into arbitrary HTML. It should be placed at or near the end of the article. It is evaluated before ARTICLE_ID so that the result of the expansion may contain the <!--ARTICLE_ID--> tag and have it be expanded.

The main purpose of this is to allow the user to insert the JavaScript required to use the HaloScan comment service.

ii includes several templates suitable for use as examples. The template white is the simplest of the lot and may be useful as a starting point for creating your own templates.

The others are derived from templates found on www.oswd.org.


THE CMS DIRECTORY

This section describes how ii stores its files. In theory, you should not need to know this. However, this being software, something is going to go wrong so you'll probably want to know how to clean up the mess.

All ii content is stored in the directory IIBlog in your home directory (well, unless you've changed that in ~/.iirc).

The IIBlog directory contains:

Each blog directory contains the following files and directories:

Describing them as safe to delete, above, assumes that ii is not running at the time.


ENVIRONMENT

HOME

Used to find the blog directory and global configuration file.

VISUAL and EDITOR

Used to find the user's preferred text editor.

PATH

Used to find the required external programs.


FILES


BUGS AND QUIRKS

ii tends to sort things by date and time, down to the nearest second. If you perform certain operations (e.g. publishing) multiple times within the same second, articles may appear in an unexpected (or unpredictable) order.

ii may expand template items it finds in blog content. It is not a good idea to depend on this behaviour.

Locking is rather crude. ii locks the entire content directory so that you can only ever do one operation at a time, even if they could safely be done concurrently. (The exception to this is the markup command, which does not set or require a lock.) If the content directory is locked, ii will wait until it becomes unlocked. This may or may not be what you want. Locking may not on NFS filesystems on some platforms.


AUTHOR, COPYRIGHT, LICENSING

ii is written by Chris Reuter <ii at blit.ca> and is Copyright (C) 2006-2007, Chris Reuter with the following exceptions:

All of these templates have been modified by me (Chris Reuter) to properly integrate with ii and occasionally to better present the generated HTML. As a result, they may no longer represent the original author's vision. If there are flaws in these designs, they are likely things I introduced afterward.

These are believed to be freely usable and redistributable due to their presence on the website ``Open Source Web Design'' (oswd.org) and by the tone of the sample text of the original templates and some comments in the template.

The rest of ii is made available under the terms of the GNU General Public License (i.e. ``the GPL'').

As a special exemption, web pages generated using the ``white'' template may be redistributed under your own terms.