Here's the complete text for the download you were just reading about. For those that hate to read documentation, here's a link to DOWNLOAD blox 0.99.

To return to the Downloads page, click the Downloads button at left.

blox 0.99

The blox plugin generates "paragraph" markup tags around blocks of plain text as your entry files are processed by Blosxom. Just type plain text into your entry files, separating paragraphs by at least one blank line (really blank; no spaces, tabs, etc.). When Blosxom builds your stories, blox will add the open- and close-tags of your choice to each paragraph. Existing markup tags will be left alone.

blox also has options to insert linebreaks (e.g. <BR>) on single lines, and to use a simple, natural-idiom markup notation to add heads, rules, text styles, lists, blockquotes, images, anchors, and links to your entries with no tedious html coding.

blox also lets you use virtually any text processor and upload method for your entry files, by recognizing "lines" from either Unix-, Mac-, or Windows-based text processors (ascii 10; ascii 13; or ascii 13/10 line-ends).

• For example, consider this entry file text:

     Welcome to my entry.

     Short, isn't it?
Without block-level html tags, this entry file will render on the page as: Welcome to my entry.Short, isn't it? (Eh, not very pretty.)

• With blox, the entry renders like this:

    Welcome to my entry.

    Short, isn't it?

That's much better.

• blox's tagged output for that entry looks like this:

    <p>
    Welcome to my entry.
    </p>
    
    <p>
    Short, isn't it?
    </p>


Getting blox

There are two versions of blox available, each in two different forms:

Installing blox

To install blox, first open the file and look down at the "Configuration Section"; enter values as instructed; save. Then, drop the file into your Blosxom plugins folder. Blog on.

Options

Open and Close tags : the text you enter in between the single quote marks for $open_p_tag and $close_p_tag becomes the exact open- and close-tags inserted before and after each block of text in your entry file.

• You can use, for example:

$open_p_tag = '<p>';
$close_p_tag = '</p>';
• or:
$open_p_tag = '<blockquote>';
$close_p_tag = '</blockquote>';
• or even:
$open_p_tag = '<hr class="snazzy"><dfn class="1">';
$close_p_tag = '</dfn><hr class="snazzy">';

Initial and Final tags : the $add_initial_open_tag and $add_final_close_tag variables tell blox whether or not to try putting an open-tag at the very top of your entry, and a close-tag at the very bottom of your entry. For instance, maybe your story template puts a sexy drop cap paragraph style tag right before $story -- the effect would be ruined if blox put <p> atop your entry text. Likewise, you can prevent a close-tag from being added at the end of your entry file.

Use "0" to turn the tag off; use "1" to turn the tag on.

Breaking single lines : The $break_singles variable tells blox to add a tag at the end of single lines; the $break variable supplies the tag (normally <BR>). When this is turned off (set to zero), the following entry file text

    line one
    line two
    line three
will be rendered on your blog page as "line oneline twoline three".

Use "0" to turn the break off; use "1" to turn the break on. The normal $break tag is <br>; you can change this to <br clear="all">, etc. Depending on other settings, blox may change your $break behind the scene; read the More info on linebreaks note at the end of this section for complete details.

Simple markup : The $markup_active variable tells blox to use its simple markup system to automatically add tags for heads, rules, text styles, lists, blockquotes, images, anchors, and links. Notation rules are:

*bold words*stars enclose words on single lines
/italic words/slashes enclose words on single lines
_underline words_underscores enclose words on single lines
[=monospace letters]"[=" can be anywhere; "]" can span lines
* Unordered List Item
0 Ordered List Item
Consecutive lines beginning with '* ' and '0 ' become lists; nest lists with '** ' and '00 ', etc. Ordered items can begin with one or more digits, optionally followed by a :, ), >, +, or -; unordered items can begin with one or more *, +, or -. List items can span lines, provided no line starts with a space.
{= Blockquote =} Text contained by '{=' and '=}' becomes blockquote. {= must start a line, =} must end a line; =} can span paragraphs.
[img /path/to/image.gif]brackets enclose "img" and a relative-to-root image path. Image dimensions and attributes are optional.
[http://path]brackets enclose single-line url, beginning with "htttp:", "ftp:", or "irc:". Attributes are optional.
[link name http://path]brackets enclose single-line words and url; url begins with "http:", "ftp:", or "irc:". Attributes are optional.
[link name //rel/to/site]
[link name :/rel/to/blog]
url can also be relative-to-root (//) or relative-to-blog (:/). Attributes are optional.
[#anchor_name]
[link name ##anchor_name]
brackets enclose '#' and single-word anchor name; brackets enclose single-line link name and '##' and single-word anchor name; attributes are optional.
= Headline 1-6equals sign(s) and one space preceed text at start of single line; the number of "=" sets the "number" of the head; e.g. "= " yields H1 while "==== " yields H4. Equals signs can balance on the far side of the text; e.g. "=== Topic" is the same as "=== Topic ===".
----four dashes at start of line followed by newline becomes a horizontal rule
!exclamation point escapes ("negates") any of these effects by preceding the leading mark.

The file blox markup guide.txt is a complete guide to blox markup notation. Set $markup_active and $break_singles to 1 in blox, and drop the file into your datadir; when you refresh your blog you'll see many samples of working and non-working markup. View the rendered markup here.

Using a noblox file : There may be times when you want blox to skip an entry file, or a whole folder of entry files. One method is to put <--noblox--> as the first line of body text in an entry file...but for existing files, this means changing the mod time, thus changing the post's position in your blog (p'bly). To avoid this, you can also skip a file by entering its path (from your Blosxom datadir) as a line in a text file named "noblox" (no quotes).

The $use_noblox_file variable tells blox whether or not to spend time looking at a noblox file; the $noblox_path variable tells blox where to look for the noblox file.

To use a noblox file, first create a text file named "noblox" (without the quotes) in the "state" dir of your Blosxom plugins directory; on individual lines in this file, list directories or files that blox should skip over. The paths you enter should start where $blosxom::datadir leaves off. Here are two samples -- note the format for directories:

   dirname/
   dirname/filename.ext

Here's an example. Let's say the path to your Bloxsom datadir is:
    /var/www/html/my_domain.net/blosxom
and you want blox to skip the file at:
    /my_domain.net/blosxom/docs/tech/projects/time_machine.txt
you would enter this on a line in the noblox file:
    docs/tech/projects/time_machine.txt
To skip the entire "projects" directory, you would enter this on a line in the noblox file:
    docs/tech/projects/

If certain files or directories within a noblox directory need to use blox, you can "un-ignore" them by prepending a "!" (no quotes) to their path. For example, let's say that everything in the
    /docs/tech directory
could be ignored, except for the files in
    /docs/tech/projects directory
Your noblox entries would look like this:
    docs/tech/
    !docs/tech/projects/
Now, every entry file in /docs/tech/programming and /docs/tech/news will be ignored, but the files in the /docs/tech/projects directory will be handled by blox.

NOTE: a noblox comment within an entry file always "trumps" an unignore path in the noblox file.

Playing nice with other plugins : The $play_nice variable lets you turn off the expected blox behavior of ignoring stories that contain a $meta::markup value. Most users should leave this value set to 1:
    my $play_nice = 1;

Advanced markup config : Several settings let you control the tags generated by blox markup. Tag elements can be set for the four "character styles" italic ($i_tag; normally "i"), bold ($b_tag; normally "b"), underline($u_tag; normally "u"), and monospaced ($mono_tag; normally "code"). For instance, you might want to use em as the italics tag; or strong as the bold tag, or tt or kbd as the monospaced tag.

Setting the $use_xhtml_tags variable to 1 tells blox to close the so-called "empty" tags <hr>, <br>, and <img> with " />" (XHTML) instead of the "normal" ">" (HTML).

Normally, blox is "loose" and doesn't add close tags to list items; setting the $close_list_item variable to 1 will add </li> tags to list items.

Normally, blox is "loose" and doesn't add link text to anchors (e.g. <a href="#top></a>); setting the $anchor_text variable to 1 will add a non-breaking space (&nbsp;) as link text, yielding <a href="#top>&nbsp;</a>.

More info on linebreaks
blox always adds <br> tags to multi-line list items, regardless of the $break_singles setting. Only <br> is used; your $break setting is ignored (but see below).

When $use_xhtml_tags is set to 1, blox changes the list item break tag to < /br> automatically. Likewise, blox will automatically change your $break tag when $use_xhtml_tags is set; even if you've changed $break to <br clear="all">, blox will change it to <br clear="all" />. (Specifically, if your $break tag starts with "<br", blox will close it with " />" when $use_xhtml_tags is set.)


Usage

When typing entry files, just ignore making paragraph tags and leave a blank line between paragraphs. To use a tag at the start or end of a paragraph and still have blox insert a paragraph tag, add a single space character before or after that tag. Use the markup notation to avoid even more html coding; note that leading or trailing spaces are not required when paragraphs begin or end with markup.

To have blox ignore (skip over) files, add a <!--noblox--> comment to the file, or include its path in a noblox file in your plugins state directory.

• Here's an example. Let's say that your paragraph tags are <p> and </p>, and here's your entry file text:

 <span class="initial_caps">Each entry starts</span> with a 
few words in bold all-caps. Subsequent topic-introducing 
paragraphs are called out by opening with a few bold words. 
Put a space before the opening SPAN tag, and blox will still 
add an open-P tag.

See how this paragraph begins with normal styling...only the first 
paragraph gets the razzle-dazzle.

 <b>Here's a new idea</b>, so the first few words are wrapped 
in a <b> tag. A space is added before the tag, so that blox 
will add an open-P tag to this block.

<blockquote>
Here's a blockquote; we'd just as soon not have blox wrap a 
'paragraph' tag around it, so we make sure there are no spaces
before or after its tags.
</blockquote>

That's the end of this entry. (To make sure blox puts a close-P 
tag on this block, put a space character after this </em> tag)
<em>Bye!</em> 
(Note that there is a space char at the very end of the entry)

• Here's the html blox generates for that entry:
(Note that leading and trailing spaces have been removed)

<p>
<span class="initial_caps">Each entry starts</span> with a 
few words in bold all-caps. Subsequent topic-introducing 
paragraphs are called out by opening with a few bold words. 
Put a space before the opening SPAN tag, and blox will still 
add an open-P tag.
</p>

<p>
See how this paragraph begins with normal styling...only the first 
paragraph gets the razzle-dazzle.
</p>

<p>
<b>Here's a new idea</b>, so the first few words are wrapped 
in a <b> tag. A space is added before the tag, so that blox 
will add an open-P tag to this block.
</p>

<blockquote>
Here's a blockquote; we'd just as soon not have blox wrap a 
'paragraph' tag around it, so we make sure there are no spaces
before or after its tags.
</blockquote>

<p>
That's the end of this entry. (To make sure blox puts a close-P 
tag on this block, put a space character after this </em> tag)
<em>Bye!</em> 
</p>

• And here's how the entry renders in a browser:

Each entry starts with a few words in bold all-caps. Subsequent topic-introducing paragraphs are called out by opening with a few bold words. Put a space before the opening SPAN tag, and blox will still add an open-P tag.

See how this paragraph begins with normal styling...only the first paragraph gets the razzle-dazzle.

Here's a new idea, so the first few words are wrapped in a <b> tag. A space is added before the tag, so that blox will add an open-P tag to this block.

Here's a blockquote; we'd just as soon not have blox wrap a 'paragraph' tag around it, so we make sure there are no spaces before or after its tags.

That's the end of this entry. (To make sure blox puts a close-P tag on this block, put a space character after this </em> tag) Bye!


• Things get even easier when you use the blox markup; note the changes in the entry:

 <span class="initial_caps">Each entry starts</span> with a 
few words in bold all-caps. Subsequent topic-introducing 
paragraphs are called out by opening with a few bold words. 
Put a space before the opening SPAN tag, and blox will still 
add an open-P tag.

See how this paragraph begins with normal styling...only the first 
paragraph gets the razzle-dazzle.

*Here's a new idea*, so the first few words are wrapped 
in a <b> tag by the "*" markup. No space is needed before 
the tag, because there is no actual < at the start of the block.

{=
Here's markup for a blockquote; since it's separated from surrounding 
text by blank lines, blox will not wrap it in 'paragraph' tags.
=}

That's the end of this entry. (blox needs no help in closing this 
paragraph, since it ends with markup instead of >.) /*Bye!*/

• Here's how the entry renders in a browser:

Each entry starts with a few words in bold all-caps. Subsequent topic-introducing paragraphs are called out by opening with a few bold words. Put a space before the opening SPAN tag, and blox will still add an open-P tag.

See how this paragraph begins with normal styling...only the first paragraph gets the razzle-dazzle.

Here's a new idea, so the first few words are wrapped in a <b> tag by the "*" markup. No space is needed before the tag, because there is no actual < at the start of the block.

Here's markup for a blockquote; since it's separated from surrounding text by blank lines, blox will not wrap it in 'paragraph' tags.

That's the end of this entry. (blox needs no help in closing this paragraph, since it ends with markup instead of >.) Bye!


Discussion

blox makes typing entry files easier by adding three levels of automated html markup. blox always wraps "paragraph" tags around blocks of entry file text. Optionally, blox will add <br> tags after single line breaks. As a final option, blox can render headline, blockquote, list, rule, image, link, italic, bold, underline, and monospace tags from a simple markup notation. blox will not interfere with existing tags.

blox "paragraph" markup operates according to the following rules:

These rules allow blox to run fast and lean, while not interfering with existing tags. To "force" blox to add an open- or close-paragraph tag to blocks that start or end with a tag, just add a space before or after the tag.

blox "linebreak" markup operates according to the following rules:

Again, these rules allow blox to run very fast, while not interfering with existing tags. To "force" blox to add a "break" tag to line ends that end with a tag or are followed by a tag, just add a space after or before the tag.

blox markup notation operates according to the following rules:

Compared to other formatters, blox runs very fast, in a very small footprint. This is because blox doesn't bother trying to figure out existing html tags; it avoids them like the plague. This lets blox rattle off a mess of substitutions without spending time and space analyzing and storing html. (White lie: blox treats <PRE> blocks special; they are pulled out of the entry before processing and restored after processing, to ensure that they are not changed.)

So that's why blox has the silly requirement of adding a space to leading or trailing tags in order to get paragraph open- or close-tags -- you're paying the (small) price of the memory and time benefits granted by total "tag-avoidance" ;-)


blox Limitations & Compatibility

blox expects plain ASCII text; it has no added knowldege of UTF-8, Unicode, etc. It has been developed and tested exclusively in an "en-US", "charset=iso-8859-1" environment. It has never seen locale.

With new entry files, you can simply ignore setting tags for "paragraphs," "breaks" and other common elements, and focus on tags such as <span>, <table>, <div>, etc.) and -- of course -- writing your entry.

With existing entry files, blox may be "tricked" into producing "phantom" paragraph tags by certain machine-generated or messy markup. In these cases, it's better to have blox skip the file. This can be accomplished in two ways:

  1. set a line in the story to "<!--noblox-->" (without the quotes); and of course, add formatting, since blox will now skip this file ;-)
  2. to avoid modifying entry files, create a text file named "noblox" (again, without the quotes) in the "state" dir of your Blosxom plugins directory; on individual lines in this file, list directories or files that blox should skip over. Here are two examples -- note the format for directories:
       dirname/
       dirname/filename.ext
(See the Using a noblox file part of the Options section, above, for complete information on ignoring and un-ignoring files.)

Likewise, there may be times when you want blox to ignore markup but still add paragraph (and/or break) tags. This can be accomplished in three ways:

  1. set a line in the story to "<!--nobloxmarkup-->" (without the quotes)
  2. if you use the meta plugin, add a meta-markup variable to the entry; set the value to anything other than "blox" (e.g. meta-markup:noblox)
  3. if you use the config plugin, create a config file that sets $blox::markup_active to 0
NOTE: there is not yet a "nobloxmarkup file" feature.


The best way to assess blox' compatibility with your existing entry files is to try it out; if entries don't look good, then adios, blox! (Remember: blox does nothing to your actual files -- any mistakes it makes with your entries only appear in Blosxom's output.

NOTE: if you are using the "blok" plugin, you should remove it; its functionality is built into blox. You can either delete blok, or change its name to "blok-".

Bugs

Address bug reports and comments to the Blosxom mailing list:
http://www.yahoogroups.com/group/blosxom

License & Copyright

this Blosxom Plug-in
Copyright 2003-2004, Stu MacKenzie (S2_Mac, HyperSTUff)

Version: v0.99 2004-10-30 (2004-10-24 0.97-11e)
License: MIT/Public Domain
See plugin file for complete details and restrictions

 

DOWNLOAD blox 0.99