ii - Infernal Icecube, a command-line weblog tool.
ii [flags] blog command [argument]
ii markup [filename] [--markup-output=filename]
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:
Templates
RSS syndication
A simple, intuitive markup language
Revision control
Uses your preferred text editor
No special server-side requirements--the blog is completely static
Non-interactive operation (useful for scripting)
Keeps all content locally, on your computer
Your content is stored in a hand-fixable format
It's easy to use (if you're comfortable with a Unix command-line)
Additionally, it is guaranteed not to turn you into a fourteen-year-old girl.
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.)
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
Starts up your preferred editor on the named blog's configuration file.
Creates the named blog if it does not already exist.
Edit the existing entry with the given article-id.
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.
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.
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.
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.
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.
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.)
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.
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.
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.
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.
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.
Print out a brief summary of the commands and options, then exit.
Print out the version number, copyright information and various legal disclaimers, then exit.
Sets the blog directory to use. Overrides the default (~/IIBlog)
or whatever has been set in ~/.iirc.
Disable (some) output messages.
Display more output. In particular, it makes rcs display messages.
ii requires the following external programs to be present and
runnable by the current user.
rcs (specifically, co, ci and rlog).
tar
Some text editor.
Optionally, some web browser.
perl version 5.8.3 or later. (Earlier versions may also work.
Perl 6.X almost certainly will not.)
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.
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:
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.
This is the time and date of the last modification of the article. Editing an article will change this.
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.
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.)
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.
HTML tags and elements get passed through unmolested except when they can be intepreted as something else.
Backslashes (``\'') escape stuff as follows: every character following a backslash gets into the final output, usually ignoring any special meaning the character would otherwise have.
Characters ``<'', ``>'' and ``&'' get passed through as-is unless they are surround by whitespace on both sides, in which case they are escaped. ``;'' is always passed through unmolested. End-of-line and start-of-line count as whitespace for these purposes but be careful not to look like the start of an HTML section.
Tabs are equivalent to 4 spaces.
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 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 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 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 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).
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 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?)
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 (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 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.
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 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:
The absolute path to your IIBlog directory. Defaults to ``~/IIBlog/''.
Path to the external editor to use. If unset, uses the result of the VISUAL or EDITOR environment variables.
Path to co, the rcs command to perform a checkout.
Path to ci, the rcs command to perform a checkin.
Path to rlog, the rcs command to output a file's revision history.
Path to your tar program.
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.
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:
This is the title of your blog. It should not contain any markup.
This is also the title of your blog but may contain HTML markup. If unset, the value of ``Title'' is used instead.
This is the subtitle of your blog. This text replaces the ``<!--SUBTITLE-->'' template field and so may contain HTML markup if you wish.
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.
This is the copyright message that goes at the bottom of the page. It may contain HTML markup.
This is the maximum number of articles to display on the front page.
This is the maximum number of articles to display in the ``Recent Contents'' pane of the front page.
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.
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.
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.
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.
The name or IP number of the web server that will be hosting your blog.
This is the username of your account on the web server.
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.
This is the path on the server to the directory to which your website will be uploaded.
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.
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.
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 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:
There are no subdirectories in the archive.
There is a file named article_template.html, formatted as described
below.
There is a file named main_template.html, also formatted as
described below.
There are no files named contents.html, index.html,
attached or with a name consisting of only digits followed by
.html.
There is no file with the extension ``.xml''.
All files have read permission set for the user.
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.
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:
This is the blog's title, taken from the blog's config file.
This is also the blog's title but this version allows HTML tags.
This is the blog's subtitle. It may contain HTML tags.
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.
This expands into a list of links to the last few articles. The links
are separated by <br> tags.
This expands into the page's contents.
This is a link to the contents page. That's the page that contains a complete list of articles.
This is the copyright message as taken from the blog's config file.
This is the site disclaimer as taken from the blog's config file. It usually appears near the copyright message.
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.
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:
This is the actual text of the article. Depending on context, it may be the entire text or the text before the first jump.
This is the article's subject line.
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.)
This is the date of the last modification. Note that publication does not count as modification.
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.
This expands into the article number. It is useful if you need a unique identifier for the article.
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.
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:
One directory for each blog named after the blog.
The file _removed.
_removed contains all deleted articles. It may be deleted or
truncated. If you have a particularly embarrassing blog entry you
want to get rid of, you will need to delete _removed as well.
Alternately, if you accidentally deleted a valuable article, that's where you go to recover the text.
The _lockfile. This is used to lock the repository and so make
sure that multiple instances of ii do not corrupt the contents.
Each blog directory contains the following files and directories:
config, the blog config file. This is what gets edited with the
edit command.
Zero or more numbered files (i.e. the name consists entirely of
digits), each containing one article. The numbers increase in order
of creation. This is the weblog's content. If you accidentally
delete one or more of these, it may be possible to recover the file
(or at least an earlier version) from the RCS directory.
RCS, the RCS repository. This holds the versions of all of the
articles. ii keeps all article files locked (i.e. checked out and
writable by the current user.) If an article is unlocked or missing,
that means something went wrong with ii. Deleting an article will
also delete its RCS file. (If this makes no sense to you, read the
man pages for rcsintro, co and ci.)
template.tar, the current template. This will only be here if you
have used the template command at least once. If it becomes
corrupted, you may delete it and rerun the template command on the
blog.
rendered, the directory containing the final generated HTML (and
related) files as well as the contents of the current template. This
is automatically created when needed (by the preview and upload
commands) and is deleted when ii is given the --regenerate
option. rendered is safe to delete. DO NOT store anything
valuable in this directory.
Describing them as safe to delete, above, assumes that ii is not
running at the time.
Used to find the blog directory and global configuration file.
Used to find the user's preferred text editor.
Used to find the required external programs.
~/.iirc is the global configuration file.
~/IIBlog/ is the content directory.
/usr/local/share/ii/ contains the system-wide template directory.
(This assumes that ii is installed in /usr/local/.)
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.
ii is written by Chris Reuter <ii at blit.ca> and is Copyright (C)
2006-2007, Chris Reuter with the following exceptions:
The template ``purplehaze'' was written by Haran <haran at wiredcity.com.au> and obtained from http://www.oswd.org/design/download/id/1110.
The template ``miniblog'' was written by James Koster http://JamesKoster.co.uk and was obtained from http://www.oswd.org/design/download/id/2477.
The original version of the template ``andreas08'' was written by Andreas Viklund and is available at http://www.openwebdesign.org/viewdesign.phtml.
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.