proxy70

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 &lt;PRE&gt; 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 "&lt;b&gt;" or "&lt;/a&gt;"), 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: " &lt;b&gt;Do you see&lt;/b&gt; the leading space
    on this line?

    " while this entry text won't: " &lt;b&gt;What's missing&lt;/b&gt; 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 :, ), &gt;, +, or -

    ---- four dashes alone on a line becomes &lt;hr&gt;

    *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 "&lt;!--noblox--&gt;" (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 "&lt;!--nobloxmarkup--&gt;".)

    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 &lt;PRE&gt; 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 &lt;=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
    &lt;PRE&gt; 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.