Blosxom Plug-in: blox

Blosxom Plug-in: blox
NAME
Blosxom Plug-in: blox

SYNOPSIS
* Wraps user-specified markup tags around "paragraphs" in plain text
entry files; optionally adds pre-selected linebreak tags to single
lines.

* Optional markup notation creates html tags for heads, rules,
blockquotes, lists, anchors, links, images, and bold, italic, underline,
and monospace text styles.

* Doesn't interfere with existing markup, including <PRE> tags

* Gets out of the way of other formatting plugins (via meta).

* Config file or hard-wired story comments allow blox to ignore
directories and files; un-ignore allows great specificity.

* Reads files from any text processor, recognizing Unix, Mac, and
Windows line ends.

INSTALLATION
Locate the blox plugin you downloaded; it may be in a ZIPped archive.
Open the "blox" file and answer the questions in CONFIGURATION SECTION.
Upload or drop the "blox" file into your blosxom plugins folder. Blog
on.

CONFIGURATION
With any luck, the instructions in the "Configuration Section" at the
top of this file are sufficient; if more information is needed, see the
documentation at: http://www.enilnomi.net/dltext/blox.dl

USAGE NOTES
You're always free to use html markup in your entries; blox won't change
any of your existing tags. However, in cases where you have a tag at the
start or end of a paragraph (such as "" or "</a>"), you must add a
single space before or after the tag to get blox to add its open or
close block tag.

For example, the following entry text (everything between the double
quotes) will produce a paragraph: " Do you see the leading space
on this line?

" while this entry text won't: " What's missing is a leading
space on this line.

"

(You don't need to add spaces to your text in anticipation of html tags
that blox markup notation might add -- leading or trailing spaces are
only needed for actual tags at the start or end of "paragraphs.")

SIMPLE MARKUP
A simple markup notation for generating html tags is available by
setting $markup_active to 1. Notation rules are: = Headline 1-6 1 to 6
"=" and a space, then head text, alone on a line. Optionally put a space
and matching number of "=" after head text.

{= Blockquote =} Start a line with "{=" to open a blockquote; end a line
with "=}" to close it. Blockquotes can span paragraphs, so make sure you
close them! All markup except for blockquotes can be used inside a
blockquote. If you need to use "=}" within a blockquote, escape it as
!=}.

* Unordered list item 1 Ordered list item Lines beginning with "list
marks" and a space, followed by text, become list items; the number of
list marks determines the nested level of the list. Consecutive list
items are contained in the same list. List items can be mulit-line,
provided no line starts with a space. List end on a blank line or a line
beginning with a space. List marks -- Unordered: *, +, and - Ordered:
digits; can optionally be followed by :, ), >, +, or -

---- four dashes alone on a line becomes <hr>

*bold words* stars enclose single-line words

/italic words/ slashes enclose single-line words

_underlined words_ underscores enclose single-line words

[=monospaced words] [= can be anywhere; ] can span lines

[img relative_url attributes] [ and ] enclose single-line "img" and a
space, followed by a relative (to root) url, followed by a space and
optional attributes.

[link text URL attributes] [ and ] enclose single-line link information.
Link text (and a space) is optional; URL is required, and can be marked
as being a complete address (http://), a relative-to-root address (//),
or a relative-to- blog address (:/); (a space and) attributes are
optional. Image markup can be used as link text.

[#anchor_name] [ and ] enclose # and singe-word same-page anchor

[link text ##anchor] [ and ] enclose single-line link text, ##, and
singe-word same-page anchor name. Image markup can be used as link text.

reference[1] links [1 URL attributes] [ and ] enclose digit(s) or single
letter to form a reference. Then, alone on a line, [ and ] enclose the
reference character(s) and a space, and a complete url; (a space and)
attributes are optional.

Escaping Markup ! preceding exclamation point escapes ("ignores")
markup.

The file "blox markup guide.txt" (included in the archive version of
blox and available online at
www.enilnomi.net/downloads/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 to read complete markup
documentation.

IGNORING FILES
There are three ways to tell blox to skip over (ignore) an entry file:
1) The html comment "" (no quotes) at the start of any line
in the story will tell blox to skip that file. (Similarly, ignore markup
for a file by using "".)

2) To ignore a file via the meta plugin, use any value other than "blox"
for the variable $meta-markup -- $meta-markup:textile2;
$meta-markup:none; $meta-markup:noblox will all ignore a file.
($meta-markup:blox will NOT ignore a file.)

3) Use a "noblox" file to ignore indivdual files and/or entire
directories: create a text file named "noblox" (no quotes) in Blosxom's
plugins state directory, and enter the paths to files or directories
that blox should ignore.

Valid paths in the noblox file are formatted lines:
* all paths start from where the Blosxom datadir leaves off
* no path begins with a slash (/)
* all directory paths end with a slash (/)

For example, if your $blosxom::datadir is:
/var/www/html/example.net/blosxom
and you want blox to ignore the story:
www/example.net/blosxom/tech/projects/time_machine.txt
then your "noblox" entry for the file would look like this:
tech/projects/time_machine.txt

To have blox skip the whole /projects folder:
tech/projects/

To have blox skip the whole somewhere.net/blosxom/tech folder:
tech/

Lines in the noblox file can themeslves be ignored by adding a leading
"#" (no quotes); i.e. making them Perl comments.

UN-IGNORING FILES
Files or directories within ignored paths can be "un-ignored" by
preceding their paths with a "!" (no quotes) in the noblox file.

For example, let's say that everything in the /tech directory could be
ignored, except for the files in /tech/projects directory. Your noblox
entries would look like this: tech/ !tech/projects/ So, entry files in
/tech/programming or /tech/news will be ignored, but the files in the
/tech/projects will be handled by blox.

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

PREFORMATTED TEXT
As of version 0.98 blox properly renders preformatted text blocks (text
within <PRE> tags); previous versions required most users to make blox
ignore files that contained PRE tags. Now, nearly no one should have to
ignore such files.

LINE ENDS
The blox plugin reads line ends from Unix (ascii 10), Mac (ascii 13),
and Windows (ascii 10/13) with equal grace; use any text processor you
like to edit story files and noblox files.

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

VERSION
2004-10-30 (v0.99) - blox with markup; based on 2004-09-24 (0.97-11e)
2004-10-30 (v0.98) - blox with no markup; based on 2004-09-24 (0.97-11e)
2004-10-24 (v0.97e) - non-release WIP for markup, bugs, cleanup
(0.97-11e) 2004-09-22 (v0.97d) - named character classes dropped for
perl <=5.006; several settings are config'able; cleanup 2004-08-24
(v0.97a) - normal tagged links were being mangled; fixed 2004-07-22
(v0.97) - cleanup; add un-ignore, linebreaking, styles, graceful PREs;
convert line-ends in noblox file 2003-09-14 (v0.96) - better line-end
conversion 2003-09-09 (v0.95) - LOL! put Win line-end chars in correct
order ;-) 2003-08-31 (v0.94) - add Mac and Windows line-ending
conversion 2003-08-30 (v0.93) - wip 2003-08-04 (v0.92) - add mechanisms
to ignore specified entries 2003-07-31 (v0.9) - half-fast workaround for
<PRE> tags 2003-07-20 (v0.8) - it's alive

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

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.