# Builderoo

### v0.7, by Dan Sanderson

Visit the Builderoo home page.

## Introduction

Builderoo is a text formatting system for Movable Type, the personal web publishing system from Six Apart. With Builderoo, you can:

• Change text filters in the middle of an entry using Roo tags. Use special purpose filters to generate sophisticated content in the middle of an entry, and use your favorite text filter for the rest. Disable text filters entirely for a section that uses plain HTML.
• Apply multiple text filters to a section, or an entire weblog entry. Use several small filters to spice up your formatting, in addition to your favorite filter. Control the order in which filters are applied.
• Speed up site building by caching the filtered output for a section. Use heavy-duty filters that take time rendering a section the first time, without slowing down subsequent re-builds of your web site.
• Create macros to be expanded in an entry before filters are applied. Use Roo tags, partial Roo tags, or other macros within a macro. Pass values to be inserted within the macro text from an entry. Quickly insert common or complex content using short RooMacro tags.
• Use text formatting plugins that interface with Builderoo's features. Build plugins that generate files based on mark-up, such as images or applets, using the caching mechanism to automatically clean up files that are no longer needed. Pass parameters to Builderoo plugins from Roo tags for finer control.

With Builderoo, text filter plugins are building blocks for quickly assembling sophisticated weblog content. A filter can perform small functions, such as replacing ASCII characters with HTML typographic characters, without concern for compatibility with other plugins. A filter can perform time-consuming functions, such as accessing a web service, without slowing down the site building process. A filter can perform specialized functions, such as generating images based on mark-up, without having to manage clean-up of unused resources.

Here is an example of Builderoo in action, using Brad Choate's MTTextile plugin as the "base" filter, and the RooLilypond plugin, one of several example plugins included with Builderoo, to generate musical score from Lilypond mark-up:

p. In his __Arabesque No. 1__, Claude Debussy uses triplets in
the melody against quarter notes like a waterfall against stones, not
always touching but always in tandem on the way down.

<% Roo:lilypond %>
\notes \new PianoStaff <<
\new Staff {
\key e \major
\clef treble
r4 \relative c' {
\times 2/3 { e'8 fis cis } \times 2/3 { e b cis }
\times 2/3 { gis b fis }   \times 2/3 { gis e gis }
dis2 cis4
}
}
\new Staff {
\key e \major
\clef bass
\relative c, { e8 b' e gis b gis e b e, cis' e gis cis gis e cis }
}
>>

</% Roo %>

p. A talented pianist can emphasize the detachment of the melody from the
accompaniment without deviating from the rhythm as written.


This example will appear in the blog entry as:

In his Arabesque No. 1, Claude Debussy uses triplets in the melody against quarter notes like a waterfall against stones, not always touching but always in tandem on the way down.

A talented pianist can emphasize the detachment of the melody from the accompaniment without deviating from the rhythm as written.

Several plugins are included with Builderoo to demonstrate its features. See plugins.html for more information.

## Installing Builderoo

### Requirements

Builderoo requires Movable Type 3.2 or later.

Builderoo v0.7 was tested with Perl 5.6.1 and Perl 5.8.1. It should work with all versions of Perl later than 5.6.1.

Some of the plugins included with Builderoo depend on other applications. See the documentation for the plugins for more information.

### Installation

To install Builderoo, do the following:

Step 1: Find Perl on your server. The first line of builderoo/builderoo-console.cgi must have the correct path to "perl," typically #!/usr/bin/perl. Check the first line of mt.cgi. If the path is different from /usr/bin/perl, modify builderoo/builderoo-console.cgi accordingly.

Step 2: Upload the builderoo directory into the plugins directory in your Movable Type installation.

Step 3: Change the file permissions of builderoo-console.cgi so it can be executed by the web server. At a Unix/Linux command line, the following command should set the correct permissions:

chmod 755 builderoo-console.cgi

These first three steps are similar to those used to install Movable Type. See the Movable Type installation instructions for more details on Perl and file permissions.

Step 4: Configure Builderoo from your weblog's Settings, under the "Plugins" panel. Choose "base" filters to use by default for all entries that use Builderoo.

Step 5: (optional) Make Builderoo the default text filter for new entries. In your weblog's Settings, under the "New Entry Defaults" panel, set "Text Formatting" to Builderoo.

Step 6: (optional) Install Builderoo text formatting plugins according to their instructions. Builderoo comes with several useful plugins that take advantage of Builderoo's features. See plugins.html for more information. For news about other plugins designed for Builderoo, visit the Builderoo home page.

## Using Roo Tags

When Builderoo is selected as the text formatter for an entry, the entry will be formatted using the base filters, as set in the Builderoo configuration for the weblog. To use a different set of filters—or no filters at all—for a section of the entry, surround the section in a "Roo" tag:

<% Roo:filterkey %> This is a special section. </% Roo %>

To specify the text filter to use, include its "key" in the starting tag after Roo:. The filter key is a unique identifier that represents a text filter. To see a list of keys for available filters, click on the help box (?) next to the "Text Formatting" drop-down list in the entry editing window.

You may specify multiple filters to apply by listing their keys, separated with commas (no spaces). Filters are applied in order from left to right. The results of the first are passed to the second, and so on.

<% Roo:firstfilter,secondfilter,thirdfilter %> This is a special section. </% Roo %>

You may specify that the section not be filtered at all by specifying no filter keys. The colon is still required.

<% Roo: %> No filters will be applied to this section. </% Roo %>

A Roo section can contain other Roo sections. Only the filters for the inner section are used on the inner section. When the inner section ends, the outer section's filters process the rest of the outer section.

### Filter Parameters

Roo tags may include parameters to be passed to filters that accept them. Parameters are specified in brackets after the filter name, using the parameter name, an equals sign (=), and the parameter value. If the parameter value contains spaces, surround it with double-quotes ("). Within double-quotes, a double-quote character may be included in the value by preceding it with a backslash (\); similarly, a backslash character may be included by using two backslashes (\\). Multiple parameters may be specified, separated by spaces. For example:

<% Roo:firstfilter[attr1=value attr2="Bob says, \"Hi!\""],secondfilter %>

### Literal Text That Looks Like a Roo Tag

To have the text "<% Roo" or "</% Roo" appear in a blog entry, use the special tags <% Roo \\ %> and </% Roo \\ %>, respectively. Note that the characters are passed to text filters just as they appear; to have them display in a web page, a text filter must translate the angle brackets to HTML entities (e.g. < to &lt;).

<% Roo:verbatim %>
I enclose my Roo sections with <% Roo \\ %>:filterkey %> and </% Roo \\ %>%> tags.
</% Roo %>

(This example uses the "verbatim" filter, a sample plugin included with Builderoo that converts special characters to HTML entities. See plugins.html for more information.)

## Caching Filter Results

Builderoo can remember the filtered version of a section, so it does not have to re-run the filters the next time the entry is rendered if the section hasn't changed. Special purpose filters can perform heavy-duty tasks, such as generate images or fetch data from a web service, and not slow down subsequent re-builds of pages containing the entry.

In most cases, only certain filters need to have their results cached, and they should always be cached. The text filter plugin can tell Builderoo to always cache its results using the Builderoo plugin API. (See below.)

If multiple filters are being applied to a single section, and any of the filters are to be cached, then the entire section is cached. If a cached section contains a subsection, the subsection follows its own caching rules.

To explicitly cache a Roo section, regardless of whether or not the text filter told Builderoo to cache it, use the "cache" attribute in the opening tag:

<% Roo:filterkey cache %> ... big data ... </% Roo %>

Sections to be cached will run their filters every time you preview the entry, then once more when the entry is first published. Each subsequent time the entry is published, if there are no changes to the section, the cached results will be used without running the filters.

## Using RooMacros

RooMacros are predefined sections of text that are inserted into an entry when a RooMacro tag is used, before any text filters are applied. To use a RooMacro in an entry, include a RooMacro tag:

<% RooMacro:macroname %>

Or, use the abbreviated tag:

<% RooM:macroname %>

To create new RooMacros for use in your entries, select "Edit RooMacros for this weblog" from the weblog's main menu screen. (Select the weblog from the "Weblogs" dropdown at the top of the screen, then click "Go".) Alternatively, go to the weblog's settings, "Plugins" panel, Show Settings for Builderoo, then "visit the Builderoo console", then select the weblog from the list.

A RooMacro associates a macro name with a section of text. A macro name must contain only letters, numbers, and underscores (_), and must be unique for all macros for a blog. Macro definitions may contain text, Roo tags, and other RooMacros.

RooMacros may take parameters that are substituted within the macro text. To pass parameters to a macro, use brackets after the macro name, similar to Roo filter parameters:

<% RooM:macroname[value1=first value2="second value"] %>

To include a parameter substitution in macro text, use a RooVar tag. RooVar tags can only be used in macro definitions.

 macroname ... <% RooVar:value1 %> ...

To have the contents of the RooVar "escaped", with double-quotes (") and backslashes (\) preceded by backslashes, use the escape attribute in the RooVar tag. This is useful for a value passed from one macro to another:

 macroname <% RooM:othermacro[foo="<% RooVar:foovalue escape %>"] %>

### Examples

Here is an example of a macro that wraps the results of another macro in a <div> tag, allowing the "param" parameter to be passed through to the second macro:

 macroname 
<% RooMacro:second specialparam=myvalue param="<% RooVar:param %>" %>


Here is an example of a macro that inserts an image. A Roo tag with no filters is used to protect the IMG from other filters:

 macroname <% Roo: %>

Here is an example of a macro that opens a Roo tag for the "myfilter" filter including the "foo" parameter passed to the macro, adds some text, then leaves the Roo tag open:

 macroname <% Roo:myfilter[special="value" foo="<% RooVar:foo %>"] %> Some text.

This last example might be used in an entry as follows:

<% RooM:macroname[foo="bar"] %> Some more text. </% Roo %>

The result would be equivalent to:

<% Roo:myfilter[special="value" foo="bar"] %> Some text. Some more text </% Roo %>

### Literal Text That Looks Like a RooMacro/RooVar Tag

As with Roo tags, to insert the text "<% RooMacro", "<% RooM", or "<% RooVar" into an entry (or macro definition) as typed, use <% RooMacro \\ %>, <% RooM \\ %>, and <% RooVar \\ %>, respectively.

## Developing Builderoo Plugins

Text formatting plugins can interface with Builderoo for extra functionality. A plugin registers itself with a call to a subroutine in Builderoo.pm.

A text filter plugin that works without Builderoo, but has optional functionality if Builderoo is installed, may register as both a regular text filter and as a Builderoo plugin. If Builderoo is used, the additional functionality will be used. Plugins that require Builderoo should register only with Builderoo, and not as a regular Movable Type text filter, so it does not appear in the list of text filters outside of Builderoo.

A text filter that is set up to cache will be passed an identifier associated with the cached section. When Builderoo notices a cached section is no longer used and removes it, Builderoo can call a routine specified by the filter. This is useful for filters that generate external resources, such as images or applets, so unused resources can be deleted. The cache identifier is passed to the clean-up routine, so the filter can manage its resources.

For details on how to develop Builderoo plugins, including information on how the caching mechanism works, see the "perldoc" documentation for Builderoo.pm, or visit the Builderoo home page.

## Known Issues

The following are known issues with Builderoo v0.7, which may or may not be addressed in a future version. (In some cases, the problems are unavoidable due to inherent limitations in Movable Type 3.2.)

• Cache reaping (clean-up of unused resources) is known not to work under all circumstances. In everyday use, this isn't too much of a problem, and mostly results in cached "preview" sections not being deleted. As a work-around, you can manually delete files and directories made with cache keys that end in "_p" if disk space becomes an issue. (The example plugins, such as RooLaTeX, make directories named after the cache keys, so extraneous files generated during previews are easy to clean up manually.)
• Base filters are not applied when excerpts are automatically generated from entry text, nor are they applied when the Trackback "auto-discover links" feature parses an entry. Roo tags will parse and execute filters, but filters will not have access to their configuration, and they will not cache. This is because Movable Type does not provide an MT::Template::Context object to text filters under these circumstances. Some plugins may wish to not render output if no context object is available.
• Text filters that render HTML at the beginning and ending of the text they are filtering may cause problems with Roo sections in the middle of a paragraph. For example, the "Convert Line Breaks" filter that comes with Movable Type (key: __default__) puts a <p> tag at the beginning and a </p> tag at the end of the text it is filtering. Because sections of an entry are rendered by Builderoo one at a time, a single paragraph rendered with __default__ that has a Roo tag in the middle will be split into multiple paragraphs. You may wish to avoid text filters that have this kind of behavior, or use different filters for paragraphs that contain inline Roo sections.
• Caching is only supported when publishing blog entries. Builderoo uses a special timed cache to support previewing of blog entries. This timed cache may be used inadvertently in other contexts where real caching is not supported, with the possibly undesired result that external resources will be removed when the cached data expires.
• Base filter settings apply to every entry in a weblog that uses Builderoo as its text formatting engine. If the base filter settings are changed, all existing entries that use Builderoo for text formatting will pick up the new setting the next time they are built.
• An author cannot view the list of available RooMacros, or the current base filters, unless they have permission to configure the weblog. Currently, this information is only available through the Builderoo plugin configuration and the Builderoo Console. (Ideally, this would appear in the help pop-up with the list of filters, but the pop-up does not have access to the blog ID. An alternative display has not yet been implemented.)

## Change History

The following is the release history for Builderoo:

v0.7, September 12, 2005: Major rewrite!

• This and all future versions require Movable Type 3.2 or later.
• This is a 0.x release and is not backwards compatible with other releases. Users of previous versions will want to completely uninstall the old version before installing the new one. Previously cached data will be regenerated on the next re-build.
• Most of the functions of the Builderoo Console have been moved to MT 3.2's new plugin configuration facility. See the System Overview "Plugins" screen and the weblog setings "Plugins" screen. In particular, Builderoo's own plugin configuration facility (through the Console) has been removed in favor of the MT feature.
• The example plugins have been upgraded to be easier to install and use. Dependent libraries for RegexFilter (Brad Choate's MTRegex) and RooBeautifier (Mike Jewell's Beautifier, as modified by Sean Voisen) are now included in the distribution.
• There is no longer a way to configure caching defaults for every text filter. (It wasn't that useful a feature, and it cluttered up the API.)
• MT 3.2 no longer uses Storable for plugin data, so neither does Builderoo.
• RooLilypond is now written for Lilypond 2.6.3 and later. This removes the dependency of RooLilypond on LaTeX and dvips, and includes a new default header and footer to support new syntax. It is possible to support older versions of Lilypond with modifications to the plugin, but this version of RooLilypond is only known to work with Lilypond 2.6.3 and later.
• The default "oversampling" for RooLaTeX and RooLilypond is 0.7, because lower values required too much memory for my own web host to run them. Hopefully 0.7 will work for most people. If these plugins fail to generate an image, and the log file says something about running out of memory, increase this value closer to (or equal to) 1.

v0.6, June 12, 2005: Re-organized the Builderoo files to take advantage of better support in Movable Type v3.16 for plugins. Users that have had problems with Builderoo not finding its libraries or templates should remove the old Builderoo files, upgrade to Movable Type v3.16 or later, and install this new version of Builderoo according to the new, simpler instructions.

v0.52, July 21, 2004: New sample plugin: RooSpell, a spelling checker. Also, a teeny bug fix to silence spurious warnings when saving an entry, and some minor documentation updates.

v0.51, July 14, 2004: A bug fix release:

• Fixed a problem with the Console not seeing any plugins in some cases.
• The sample plugins that generate images were causing Movable Type to lose track of its "tmpl" directory by changing the current working directory. They now change it back before returning.
• The sample plugins that generate iamges were setting permissions on generated directories in a way that broke with some web hosting configurations. This has been fixed.
• Fixed an error message about "\$ctx" on entry save in some cases.
• Updated installation instructions.

v0.5, June 28, 2004: The first public release. This release was submitted to the Movable Type 3.0 Developer Contest, June 2004. Many thanks to Jim Flanagan for helping to test Builderoo prior to submission.

v0.4, June 27, 2004: A private release. Implemented filter parameters, RooMacros. Upgraded the sample plugins to take advantage of these features.

v0.3, June 15, 2004: A private release. Implemented the Builderoo plugin mechanism, plugin panel for the Console, and preview expiration.

v0.2, June 12, 2004: A private release. Implemented the caching and reaping mechanism for Builderoo in the context of a weblog entry, and the "cache" attribute for Roo tags.

v0.1, June 9, 2004: A private release. Implemented Roo tags, default filters, and the "Text Filters" portion of the Builderoo Console.

## License and Distribution

Builderoo v0.7 is distributed under "The MIT License," an Open Source license. The full text of the license is as follows:

Copyright © 2004-2007 Dan Sanderson

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.

Digest::Perl::MD5, copyright © 2000 Christian Lackas, is distributed under the Perl Artistic License. See the Digest::Perl::MD5 documentation for more information.

MTRegex, copyright © 2002 Brad Choate, is distributed under "The MIT License," an Open Source license. The full text of the copyright notice and license can be found in examples/regexfilter/lib/README.txt.

Beautufier, copyright © 2003 Mike Jewell, with modifications copyright © 2003 Sean Voisen, is distributed under the GNU Public License, Version 2, June 1991. The full text of the GNU Public License under which Beautifier is distributed can be found in examples/roobeautifier/lib/COPYING.txt, with a complete list of files in example/roobeautifier/lib/README.txt.

Please visit the Builderoo home page to download updates and additional plugins, report bugs, and submit feedback and suggestions for new features.