Main Page | Class Hierarchy | Class List | File List | Class Members

TextilePHP Documentation

$Id: index.html,v 1.12 2005/03/21 14:38:53 jhriggs Exp $

Textile - A Humane Web Text Generator.

SYNOPSIS


 include_once("Textile.php");
 $text = <<<EOT
 h1. Heading

 A _simple_ demonstration of Textile markup.

 * One
 * Two
 * Three

 "More information":http://www.textism.com/tools/textile is available.
 EOT;

 $textile = new Textile;
 $html = $textile->process($text);
 print $html;
 

ABSTRACT

Textile.php is a PHP-based implementation of Dean Allen's Textile syntax. Textile is shorthand for doing common formatting tasks.

SYNTAX

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:

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:

Extended Blocks

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.

Escaping

Sometimes you want Textile to just get out of the way and let you put some regular HTML markup in your document. You can disable Textile formatting for a given block using the '==' escape mechanism:
     p. Regular paragraph

     ==
     Escaped portion -- will not be formatted
     by Textile at all
     ==

     p. Back to normal.
 
You can also use this technique within a Textile block, temporarily disabling the inline formatting functions:
     p. This is ==*a test*== of escaping.
 

Inline Formatting

Formatting within a block of text is covered by the "inline" formatting rules. These operators must be placed up against text/punctuation to be recognized. These include:

Inline formatting operators accept the following modifiers:

Examples

     Textile is *way* cool.

     Textile is *_way_* cool.
 
Now this won't work, because the formatting characters need whitespace before and after to be properly recognized.
     Textile is way c*oo*l.
 
However, you can supply braces or brackets to further clarify that you want to format, so this would work:
     Textile is way c[*oo*]l.
 

Footnotes

You can create footnotes like this:
     And then he went on a long trip[1].
 
By specifying the brackets with a number inside, Textile will recognize that as a footnote marker. It will replace that with a construct like this:
     And then he went on a long
     trip1
 
To supply the content of the footnote, place it at the end of your document using a "fn" block signature:
     fn1. And there was much rejoicing.
 
Which creates a paragraph that looks like this:
     

1 And there was
     much rejoicing.
 

Links

Textile defines a shorthand for formatting hyperlinks. The format looks like this:
     "Text to display":http://example.com
 
In addition to this, you can add 'title' text to your link:
     "Text to display (Title text)":http://example.com
 
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:
     You["gotta":http://example.com]seethis!
 
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):
     [excom]http://example.com
     [exorg]http://example.org
 
For a list like this, the text in the square brackets is used to uniquely identify the link given. To refer to that link, you would specify it like this:
     "Text to display":excom
 
Once you've defined your link lookup table, you can use the identifiers any number of times.

Images

Images are identified by the following pattern:
     !/path/to/image!
 
Image attributes may also be specified:
     !/path/to/image 10x20!
 
Which will render an image 10 pixels wide and 20 pixels high. Another way to indicate width and height:
     !/path/to/image 10w 20h!
 
You may also redimension the image using a percentage.
     !/path/to/image 20%x40%!
 
Which will render the image at 20% of it's regular width and 40% of it's regular height.

Or specify one percentage to resize proprotionately:

     !/path/to/image 20%!
 
Alt text can be given as well:
     !/path/to/image (Alt text)!
 
The path of the image may refer to a locally hosted image or can be a full URL.

You can also use the following modifiers after the opening '!' character:

Character Replacements

A few simple, common symbols are automatically replaced:
     (c)
     (r)
     (tm)
 
In addition to these, there are a whole set of character macros that are defined by default. All macros are enclosed in curly braces. These include:
     {c|} or {|c} cent sign
     {L-} or {-L} pound sign
     {Y=} or {=Y} yen sign
 
Many of these macros can be guessed. For example:
     {A'} or {'A}
     {a"} or {"a}
     {1/4}
     {*}
     {:)}
     {:(}
 

Lists

Textile also supports ordered and unordered lists. You simply place an asterisk or pound sign, followed with a space at the start of your lines.

Simple lists:

     * one
     * two
     * three
 
Multi-level lists:
     * one
     ** one A
     ** one B
     *** one B1
     * two
     ** two A
     ** two B
     * three
 
Ordered lists:
     # one
     # two
     # three
 
Styling lists:
     (class#id)* one
     * two
     * three
 
The above sets the class and id attributes for the <ul> tag.
     *(class#id) one
     * two
     * three
 
The above sets the class and id attributes for the first <li> tag.

Definition lists:

     dl. textile:a cloth, especially one manufactured by weaving
     or knitting; a fabric
     format:the arrangement of data for storage or display.
 
Note that there is no space between the term and definition. The term must be at the start of the line (or following the "dl" signature as shown above).

Tables

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.

From the simple:

     |a|b|c|
     |1|2|3|
 
To the complex:
     table(fig). {color:red}_|Top|Row|
     {color:blue}|/2. Second|Row|
     |_{color:green}. Last|
 
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.

Modifiers allowed are:

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.

CSS Notes

When CSS is enabled (and it is by default), CSS class names are automatically applied in certain situations.

Miscellaneous

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.

LICENSE

Text::Textile is licensed under the same terms as Perl itself. Textile.php is licensed under the terms of the GNU General Public License.

AUTHOR & COPYRIGHT

Text::Textile was written by Brad Choate, <brad at bradchoate dot com>. It is an adaptation of Textile, developed by Dean Allen of Textism.com.

Textile.php is a PHP port of Brad Choate's Text::Textile (Textile.pm) Perl module.

Textile.php was ported by Jim Riggs <textile at jimandlissa dot com>. Great care has been taken to leave the Perl code in much the same form as Textile.pm. While changes were required due to syntactical differences between Perl and PHP, much of the code was left intact (even if alternative syntax or code optimizations could have been made in PHP), even to the point where one can compare functions/subroutines side by side between the two implementations. This has been done to ensure compatibility, reduce the possibility of introducing errors, and simplify maintainance as one version or the other is updated.

Author:
Jim Riggs <textile at jimandlissa dot com>

Brad Choate <brad at bradchoate dot com>

Copyright:
Copyright © 2004 Jim Riggs and Brad Choate
Version:
@(#)
Id
Textile.php,v 1.11 2004/09/23 15:01:28 jhriggs Exp

Generated on Mon Mar 21 08:37:26 2005 for TextilePHP by doxygen 1.3.7