Gets or sets the "disable html" control, which allows you to prevent HTML tags from being used within the text processed. Any HTML tags encountered will be removed if disable html is enabled. Default behavior is to allow HTML.

Gets or sets the CSS support for Textile. If CSS is enabled, Textile will emit CSS rules. You may pass a 1 or 0 to enable or disable CSS behavior altogether. If you pass a hashref, you may assign the CSS class names that are used by Text::Textile. The following key names for such a hash are recognized:

Gets or sets the physical file path to root of document files. This path is utilized when images are referenced and size calculations are needed (the Image::Size module is used to read the image dimensions).

Gets or sets the "preserve spaces" control flag. If enabled, this will replace any double spaces within the paragraph data with the &#8195; HTML entity (wide space). The default is 0. Spaces will pass through to the browser unchanged and render as a single space. Note that this setting has no effect on spaces within <pre>, <code> or <script>.

Gets or sets the character encoding logical flag. If character encoding is enabled, the HTML::Entities package is used to encode special characters. If character encoding is disabled, only <, >, " and & are encoded to HTML entities.

Takes a Textile formatted list (numeric or bulleted) and returns the markup for it. Text that is passed in requires substantial parsing, so the format_list method is a little involved. But it should always produce a proper ordered or unordered list. If it cannot (due to misbalanced input), it will return the original text. Arguments accepted:

Returns markup for the given image. $src is the location of the image, $extra contains the optional height/width and/or alt text. $url is an optional hyperlink for the image. $class holds the optional CSS class attribute.

The "src" (URL) for the image. This may be a local path, ideally starting with a "/". Images can be located within the file system if the docroot method is used to specify where the docroot resides. If the image can be found, the image_size method is used to determine the dimensions of the image.

Encodes input $html string, escaping characters as needed to HTML entities. This relies on the HTML::Entities package for full effect. If unavailable, encode_html_basic is used as a fallback technique. If the "char_encoding" flag is set to false, encode_html_basic is used exclusively.

Encodes the input $html string for the following characters: <, >, & and ". If $can_double_encode is true, all ampersand characters are escaped even if they already were. If $can_double_encode is false, ampersands are only escaped when they aren't part of a HTML entity already.

Returns the size for the image identified in $file. This method relies upon the Image::Size Perl package. If unavailable, image_size will return undef. Otherwise, the expected return value is a list of the width and height (in that order), in pixels.

Text::Textile processes text in units of blocks and lines. A block might also be considered a paragraph, since blocks are separated from one another by a blank line. Blocks can begin with a signature that helps identify the rest of the block content. Block signatures include:

A paragraph block. This is the default signature if no signature is explicitly given. Paragraphs are formatted with all the inline rules (see inline formatting) and each line receives the appropriate markup rules for the flavor of HTML in use. For example, newlines for XHTML content receive a <br /> tag at the end of the line (with the exception of the last line in the paragraph). Paragraph blocks are enclosed in a <p> tag.

A "clear" signature is simply used to indicate that the next block should emit a CSS style attribute that clears any floating elements. The default behavior is to clear "both", but you can use the left (<) or right (>) alignment characters to indicate which side to clear.

A "fn" signature is short for "footnote". You add a number following the "fn" keyword to number the footnote. Footnotes are output as paragraph tags but are given a special CSS class name which can be used to style them as you see fit.

All signatures should end with a period and be followed with a space. Inbetween the signature and the period, you may use several parameters to further customize the block. These include:

A filter may be invoked to further format the text for this signature. If one or more filters are identified, the text will be processed first using the filters and then by Textile's own block formatting rules.

Normally, a block ends with the first blank line encountered. However, there are situations where you may want a block to continue for multiple paragraphs of text. To cause a given block signature to stay active, use two periods in your signature instead of one. This will tell Textile to keep processing using that signature until it hits the next signature is found.

For example:

bq.. This is paragraph one of a block quote.
This is paragraph two of a block quote.
p. Now we're back to a regular paragraph.

You can apply this technique to any signature (although for some it doesn't make sense, like "h1" for example). This is especially useful for "bc" blocks where your code may have many blank lines scattered through it.

The URL portion of the link supports relative paths as well as other protocols like ftp, mailto, news, telnet, etc.

"E-mail me please":mailto:someone@example.com

You can also use single quotes instead of double-quotes if you prefer. As with the inline formatting rules, a hyperlink must be surrounded by whitespace to be recognized (an exception to this is common punctuation which can reside at the end of the URL). If you have to place a URL next to some other text, use the bracket or brace trick to do that:

Textile supports an alternate way to compose links. You can optionally create a lookup list of links and refer to them separately. To do this, place one or more links in a block of it's own (it can be anywhere within your document):

Textile supports tables. Tables must be in their own block and must have pipe characters delimiting the columns. An optional block signature of "table" may be used, usually for applying style, class, id or other options to the table element itself.

Modifiers can be specified for the table signature itself, for a table row (prior to the first "|" character) and for any cell (following the "|" for that cell). Note that for cells, a period followed with a space must be placed after any modifiers to distinguish the modifier from the cell content.

Used within cells to indicate a rowspan or 2, 3, 4, etc. rows. When you see "/", think "push downward".

When a cell is identified as a header cell and an alignment is specified, that becomes the default alignment for cells below it. You can always override this behavior by specifying an alignment for one of the lower cells.

"footnote" is applied to the paragraph tag for the footnote text itself. An id of "fn" plus the footnote number is placed on the paragraph for the footnote as well. For the footnote superscript tag, a class of "footnote" is used.

Textile tries to do it's very best to ensure proper XHTML syntax. It will even attempt to fix errors you may introduce writing in HTML yourself. Unescaped "&" characters within URLs will be properly escaped. Singlet tags such as br, img and hr are checked for the "/" terminator (and it's added if necessary). The best way to make sure you produce valid XHTML with Textile is to not use any HTML markup at all-- use the Textile syntax and let it produce the markup for you.