.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Textile 3pm"
.TH Text::Textile 3pm "2016-01-02" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Textile \- A humane web text generator.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Text::Textile qw(textile);
\&    my $text = <<EOT;
\&    h1. Heading
\&
\&    A _simple_ demonstration of Textile markup.
\&
\&    * One
\&    * Two
\&    * Three
\&
\&    "More information":http://www.textism.com/tools/textile is available.
\&    EOT
\&
\&    # procedural usage
\&    my $html = textile($text);
\&    print $html;
\&
\&    # OOP usage
\&    my $textile = new Text::Textile;
\&    $html = $textile\->process($text);
\&    print $html;
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Text::Textile is a Perl-based implementation of Dean Allen's Textile
syntax. Textile is shorthand for doing common formatting tasks.
.SH "METHODS"
.IX Header "METHODS"
.SS "new( [%options] )"
.IX Subsection "new( [%options] )"
Instantiates a new Text::Textile object. Optional options
can be passed to initialize the object. Attributes for the
options key are the same as the get/set method names
documented here.
.ie n .SS "set( $attribute, $value )"
.el .SS "set( \f(CW$attribute\fP, \f(CW$value\fP )"
.IX Subsection "set( $attribute, $value )"
Used to set Textile attributes. Attribute names are the same
as the get/set method names documented here.
.ie n .SS "get( $attribute )"
.el .SS "get( \f(CW$attribute\fP )"
.IX Subsection "get( $attribute )"
Used to get Textile attributes. Attribute names are the same
as the get/set method names documented here.
.SS "disable_html( [$disable] )"
.IX Subsection "disable_html( [$disable] )"
Gets or sets the \*(L"disable html\*(R" control, which allows you to
prevent \s-1HTML\s0 tags from being used within the text processed.
Any \s-1HTML\s0 tags encountered will be removed if disable html is
enabled. Default behavior is to allow \s-1HTML.\s0
.SS "flavor( [$flavor] )"
.IX Subsection "flavor( [$flavor] )"
Assigns the \s-1HTML\s0 flavor of output from Text::Textile. Currently
these are the valid choices: html, xhtml (behaves like \*(L"xhtml1\*(R"),
xhtml1, xhtml2. Default flavor is \*(L"xhtml1\*(R".
.PP
Note that the xhtml2 flavor support is experimental and incomplete
(and will remain that way until the \s-1XHTML 2.0\s0 draft becomes a
proper recommendation).
.SS "css( [$css] )"
.IX Subsection "css( [$css] )"
Gets or sets the \s-1CSS\s0 support for Textile. If \s-1CSS\s0 is enabled,
Textile will emit \s-1CSS\s0 rules. You may pass a 1 or 0 to enable
or disable \s-1CSS\s0 behavior altogether. If you pass a hashref,
you may assign the \s-1CSS\s0 class names that are used by
Text::Textile. The following key names for such a hash are
recognized:
.IP "class_align_right" 4
.IX Item "class_align_right"
defaults to \*(L"right\*(R"
.IP "class_align_left" 4
.IX Item "class_align_left"
defaults to \*(L"left\*(R"
.IP "class_align_center" 4
.IX Item "class_align_center"
defaults to \*(L"center\*(R"
.IP "class_align_top" 4
.IX Item "class_align_top"
defaults to \*(L"top\*(R"
.IP "class_align_bottom" 4
.IX Item "class_align_bottom"
defaults to \*(L"bottom\*(R"
.IP "class_align_middle" 4
.IX Item "class_align_middle"
defaults to \*(L"middle\*(R"
.IP "class_align_justify" 4
.IX Item "class_align_justify"
defaults to \*(L"justify\*(R"
.IP "class_caps" 4
.IX Item "class_caps"
defaults to \*(L"caps\*(R"
.IP "class_footnote" 4
.IX Item "class_footnote"
defaults to \*(L"footnote\*(R"
.IP "id_footnote_prefix" 4
.IX Item "id_footnote_prefix"
defaults to \*(L"fn\*(R"
.SS "charset( [$charset] )"
.IX Subsection "charset( [$charset] )"
Gets or sets the character set targeted for publication.
At this time, Text::Textile only changes its behavior
if the \*(L"utf\-8\*(R" character set is assigned.
.PP
Specifically, if utf\-8 is requested, any special characters
created by Textile will be output as native utf\-8 characters
rather than \s-1HTML\s0 entities.
.SS "docroot( [$path] )"
.IX Subsection "docroot( [$path] )"
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).
.SS "trim_spaces( [$trim] )"
.IX Subsection "trim_spaces( [$trim] )"
Gets or sets the \*(L"trim spaces\*(R" control flag. If enabled, this
will clear any lines that have only spaces on them (the newline
itself will remain).
.SS "preserve_spaces( [$preserve] )"
.IX Subsection "preserve_spaces( [$preserve] )"
Gets or sets the \*(L"preserve spaces\*(R" control flag. If enabled, this
will replace any double spaces within the paragraph data with the
&#8195; \s-1HTML\s0 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 \f(CW\*(C`<pre>\*(C'\fR,
\&\f(CW\*(C`<code>\*(C'\fR or \f(CW\*(C`<script>\*(C'\fR.
.SS "filter_param( [$data] )"
.IX Subsection "filter_param( [$data] )"
Gets or sets a parameter that is passed to filters.
.SS "filters( [\e%filters] )"
.IX Subsection "filters( [%filters] )"
Gets or sets a list of filters to make available for
Text::Textile to use. Returns a hash reference of the currently
assigned filters.
.SS "char_encoding( [$encode] )"
.IX Subsection "char_encoding( [$encode] )"
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 \f(CW\*(C`<\*(C'\fR, \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`"\*(C'\fR and \f(CW\*(C`&\*(C'\fR are encoded to \s-1HTML\s0 entities.
.ie n .SS "disable_encode_entities( $boolean )"
.el .SS "disable_encode_entities( \f(CW$boolean\fP )"
.IX Subsection "disable_encode_entities( $boolean )"
Gets or sets the disable encode entities logical flag. If this
value is set to true no entities are encoded at all. This
also supersedes the \*(L"char_encoding\*(R" flag.
.SS "handle_quotes( [$handle] )"
.IX Subsection "handle_quotes( [$handle] )"
Gets or sets the \*(L"smart quoting\*(R" control flag. Returns the
current setting.
.ie n .SS "process( $str )"
.el .SS "process( \f(CW$str\fP )"
.IX Subsection "process( $str )"
Alternative method for invoking the textile method.
.ie n .SS "textile( $str )"
.el .SS "textile( \f(CW$str\fP )"
.IX Subsection "textile( $str )"
Can be called either procedurally or as a method. Transforms
\&\fI\f(CI$str\fI\fR using Textile markup rules.
.SS "format_paragraph( [$args] )"
.IX Subsection "format_paragraph( [$args] )"
Processes a single paragraph. The following attributes are
allowed:
.IP "text" 4
.IX Item "text"
The text to be processed.
.SS "format_inline( [%args] )"
.IX Subsection "format_inline( [%args] )"
Processes an inline string (plaintext) for Textile syntax.
The following attributes are allowed:
.IP "text" 4
.IX Item "text"
The text to be processed.
.ie n .SS "format_macro( %args )"
.el .SS "format_macro( \f(CW%args\fP )"
.IX Subsection "format_macro( %args )"
Responsible for processing a particular macro. Arguments passed
include:
.IP "pre" 4
.IX Item "pre"
open brace character
.IP "post" 4
.IX Item "post"
close brace character
.IP "macro" 4
.IX Item "macro"
the macro to be executed
.PP
The return value from this method would be the replacement
text for the macro given. If the macro is not defined, it will
return pre + macro + post, thereby preserving the original
macro string.
.ie n .SS "format_cite( %args )"
.el .SS "format_cite( \f(CW%args\fP )"
.IX Subsection "format_cite( %args )"
Processes text for a citation tag. The following attributes
are allowed:
.IP "pre" 4
.IX Item "pre"
Any text that comes before the citation.
.IP "text" 4
.IX Item "text"
The text that is being cited.
.IP "cite" 4
.IX Item "cite"
The \s-1URL\s0 of the citation.
.IP "post" 4
.IX Item "post"
Any text that follows the citation.
.ie n .SS "format_code( %args )"
.el .SS "format_code( \f(CW%args\fP )"
.IX Subsection "format_code( %args )"
Processes '@...@' type blocks (code snippets). The following
attributes are allowed:
.IP "text" 4
.IX Item "text"
The text of the code itself.
.IP "lang" 4
.IX Item "lang"
The language (programming language) for the code.
.ie n .SS "format_classstyle( $clsty, $class, $style )"
.el .SS "format_classstyle( \f(CW$clsty\fP, \f(CW$class\fP, \f(CW$style\fP )"
.IX Subsection "format_classstyle( $clsty, $class, $style )"
Returns a string of tag attributes to accommodate the class,
style and symbols present in \f(CW$clsty\fR.
.PP
\&\fI\f(CI$clsty\fI\fR is checked for:
.ie n .IP """{...}""" 4
.el .IP "\f(CW{...}\fR" 4
.IX Item "{...}"
style rules. If present, they are appended to \f(CW$style\fR.
.ie n .IP """(...#...)""" 4
.el .IP "\f(CW(...#...)\fR" 4
.IX Item "(...#...)"
class and/or \s-1ID\s0 name declaration
.ie n .IP """("" (one or more)" 4
.el .IP "\f(CW(\fR (one or more)" 4
.IX Item "( (one or more)"
pad left characters
.ie n .IP """)"" (one or more)" 4
.el .IP "\f(CW)\fR (one or more)" 4
.IX Item ") (one or more)"
pad right characters
.ie n .IP """[ll]""" 4
.el .IP "\f(CW[ll]\fR" 4
.IX Item "[ll]"
language declaration
.PP
The attribute string returned will contain any combination
of class, id, style and/or lang attributes.
.ie n .SS "format_tag( %args )"
.el .SS "format_tag( \f(CW%args\fP )"
.IX Subsection "format_tag( %args )"
Constructs an \s-1HTML\s0 tag. Accepted arguments:
.IP "tag" 4
.IX Item "tag"
the tag to produce
.IP "text" 4
.IX Item "text"
the text to output inside the tag
.IP "pre" 4
.IX Item "pre"
text to produce before the tag
.IP "post" 4
.IX Item "post"
text to produce following the tag
.IP "clsty" 4
.IX Item "clsty"
class and/or style attributes that should be assigned to the tag.
.ie n .SS "format_list( %args )"
.el .SS "format_list( \f(CW%args\fP )"
.IX Subsection "format_list( %args )"
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:
.IP "text" 4
.IX Item "text"
The text to be processed.
.ie n .SS "format_block( %args )"
.el .SS "format_block( \f(CW%args\fP )"
.IX Subsection "format_block( %args )"
Processes \*(L"==xxxxx==\*(R" type blocks for filters. A filter
would follow the open \*(L"==\*(R" sequence and is specified within
pipe characters, like so:
.PP
.Vb 1
\&    ==|filter|text to be filtered==
.Ve
.PP
You may specify multiple filters in the filter portion of
the string. Simply comma delimit the filters you desire
to execute. Filters are defined using the filters method.
.ie n .SS "format_link( %args )"
.el .SS "format_link( \f(CW%args\fP )"
.IX Subsection "format_link( %args )"
Takes the Textile link attributes and transforms them into
a hyperlink.
.ie n .SS "format_url( %args )"
.el .SS "format_url( \f(CW%args\fP )"
.IX Subsection "format_url( %args )"
Takes the given \f(CW$url\fR and transforms it appropriately.
.ie n .SS "format_span( %args )"
.el .SS "format_span( \f(CW%args\fP )"
.IX Subsection "format_span( %args )"
.ie n .SS "format_image( %args )"
.el .SS "format_image( \f(CW%args\fP )"
.IX Subsection "format_image( %args )"
Returns markup for the given image. \f(CW$src\fR is the location of
the image, \f(CW$extra\fR contains the optional height/width and/or
alt text. \f(CW$url\fR is an optional hyperlink for the image. \f(CW$class\fR
holds the optional \s-1CSS\s0 class attribute.
.PP
Arguments you may pass:
.IP "src" 4
.IX Item "src"
The \*(L"src\*(R" (\s-1URL\s0) for the image. This may be a local path,
ideally starting with a \*(L"/\*(R". 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.
.IP "extra" 4
.IX Item "extra"
Additional parameters for the image. This would include
alt text, height/width specification or scaling instructions.
.IP "align" 4
.IX Item "align"
Alignment attribute.
.IP "pre" 4
.IX Item "pre"
Text to produce prior to the tag.
.IP "post" 4
.IX Item "post"
Text to produce following the tag.
.IP "link" 4
.IX Item "link"
Optional \s-1URL\s0 to connect with the image tag.
.IP "clsty" 4
.IX Item "clsty"
Class and/or style attributes.
.ie n .SS "format_table( %args )"
.el .SS "format_table( \f(CW%args\fP )"
.IX Subsection "format_table( %args )"
Takes a Wiki-ish string of data and transforms it into a full
table.
.ie n .SS "apply_filters( %args )"
.el .SS "apply_filters( \f(CW%args\fP )"
.IX Subsection "apply_filters( %args )"
The following attributes are allowed:
.IP "text" 4
.IX Item "text"
The text to be processed.
.IP "filters" 4
.IX Item "filters"
An array reference of filter names to run for the given text.
.ie n .SS "encode_html( $html, $can_double_encode )"
.el .SS "encode_html( \f(CW$html\fP, \f(CW$can_double_encode\fP )"
.IX Subsection "encode_html( $html, $can_double_encode )"
Encodes input \f(CW$html\fR string, escaping characters as needed
to \s-1HTML\s0 entities. This relies on the HTML::Entities package
for full effect. If unavailable, encode_html_basic is used
as a fallback technique. If the \*(L"char_encoding\*(R" flag is
set to false, encode_html_basic is used exclusively.
.ie n .SS "decode_html( $html )"
.el .SS "decode_html( \f(CW$html\fP )"
.IX Subsection "decode_html( $html )"
Decodes \s-1HTML\s0 entities in \f(CW$html\fR to their natural character
equivelants.
.ie n .SS "encode_html_basic( $html, $can_double_encode )"
.el .SS "encode_html_basic( \f(CW$html\fP, \f(CW$can_double_encode\fP )"
.IX Subsection "encode_html_basic( $html, $can_double_encode )"
Encodes the input \f(CW$html\fR string for the following characters:
<, >, & and ". If \f(CW$can_double_encode\fR is true, all
ampersand characters are escaped even if they already were.
If \f(CW$can_double_encode\fR is false, ampersands are only escaped
when they aren't part of a \s-1HTML\s0 entity already.
.ie n .SS "image_size( $file )"
.el .SS "image_size( \f(CW$file\fP )"
.IX Subsection "image_size( $file )"
Returns the size for the image identified in \f(CW$file\fR. 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.
.ie n .SS "encode_url( $str )"
.el .SS "encode_url( \f(CW$str\fP )"
.IX Subsection "encode_url( $str )"
Encodes the query portion of a \s-1URL,\s0 escaping characters
as necessary.
.ie n .SS "mail_encode( $email )"
.el .SS "mail_encode( \f(CW$email\fP )"
.IX Subsection "mail_encode( $email )"
Encodes the email address in \fI\f(CI$email\fI\fR for \*(L"mailto:\*(R" links.
.ie n .SS "process_quotes( $str )"
.el .SS "process_quotes( \f(CW$str\fP )"
.IX Subsection "process_quotes( $str )"
Processes string, formatting plain quotes into curly quotes.
.SS "default_macros"
.IX Subsection "default_macros"
Returns a hashref of macros that are assigned to be processed by
default within the format_inline method.
.ie n .SS "_halign( $alignment )"
.el .SS "_halign( \f(CW$alignment\fP )"
.IX Subsection "_halign( $alignment )"
Returns the alignment keyword depending on the symbol passed.
.ie n .IP """<>""" 4
.el .IP "\f(CW<>\fR" 4
.IX Item "<>"
becomes \*(L"justify\*(R"
.ie n .IP """<""" 4
.el .IP "\f(CW<\fR" 4
.IX Item "<"
becomes \*(L"left\*(R"
.ie n .IP """>""" 4
.el .IP "\f(CW>\fR" 4
.IX Item ">"
becomes \*(L"right\*(R"
.ie n .IP """=""" 4
.el .IP "\f(CW=\fR" 4
.IX Item "="
becomes \*(L"center\*(R"
.ie n .SS "_valign( $alignment )"
.el .SS "_valign( \f(CW$alignment\fP )"
.IX Subsection "_valign( $alignment )"
Returns the alignment keyword depending on the symbol passed.
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
becomes \*(L"top\*(R"
.ie n .IP """~""" 4
.el .IP "\f(CW~\fR" 4
.IX Item "~"
becomes \*(L"bottom\*(R"
.ie n .IP """\-""" 4
.el .IP "\f(CW\-\fR" 4
.IX Item "-"
becomes \*(L"middle\*(R"
.ie n .SS "_imgalign( $alignment )"
.el .SS "_imgalign( \f(CW$alignment\fP )"
.IX Subsection "_imgalign( $alignment )"
Returns the alignment keyword depending on the symbol passed.
The following alignment symbols are recognized, and given
preference in the order listed:
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
becomes \*(L"top\*(R"
.ie n .IP """~""" 4
.el .IP "\f(CW~\fR" 4
.IX Item "~"
becomes \*(L"bottom\*(R"
.ie n .IP """\-""" 4
.el .IP "\f(CW\-\fR" 4
.IX Item "-"
becomes \*(L"middle\*(R"
.ie n .IP """<""" 4
.el .IP "\f(CW<\fR" 4
.IX Item "<"
becomes \*(L"left\*(R"
.ie n .IP """>""" 4
.el .IP "\f(CW>\fR" 4
.IX Item ">"
becomes \*(L"right\*(R"
.ie n .SS "_repl( \e@arr, $str )"
.el .SS "_repl( \e@arr, \f(CW$str\fP )"
.IX Subsection "_repl( @arr, $str )"
An internal routine that takes a string and appends it to an array.
It returns a marker that is used later to restore the preserved
string.
.ie n .SS "_tokenize( $str )"
.el .SS "_tokenize( \f(CW$str\fP )"
.IX Subsection "_tokenize( $str )"
An internal routine responsible for breaking up a string into
individual tag and plaintext elements.
.SS "_css_defaults"
.IX Subsection "_css_defaults"
Sets the default \s-1CSS\s0 names for \s-1CSS\s0 controlled markup. This
is an internal function that should not be called directly.
.ie n .SS "_strip_borders( $pre, $post )"
.el .SS "_strip_borders( \f(CW$pre\fP, \f(CW$post\fP )"
.IX Subsection "_strip_borders( $pre, $post )"
This utility routine will take \*(L"border\*(R" characters off of
the given \f(CW$pre\fR and \f(CW$post\fR strings if they match one of these
conditions:
.PP
.Vb 2
\&    $pre starts with "[", $post ends with "]"
\&    $pre starts with "{", $post ends with "}"
.Ve
.PP
If neither condition is met, then the \f(CW$pre\fR and \f(CW$post\fR
values are left untouched.
.SH "SYNTAX"
.IX Header "SYNTAX"
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:
.IP "p" 4
.IX Item "p"
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 \s-1HTML\s0 in use. For example, newlines for \s-1XHTML\s0
content receive a \f(CW\*(C`<br />\*(C'\fR tag at the end of the line
(with the exception of the last line in the paragraph).
Paragraph blocks are enclosed in a \f(CW\*(C`<p>\*(C'\fR tag.
.IP "pre" 4
.IX Item "pre"
A pre-formatted block of text. Textile will not add any
\&\s-1HTML\s0 tags for individual lines. Whitespace is also preserved.
.Sp
Note that within a \*(L"pre\*(R" block, < and > are
translated into \s-1HTML\s0 entities automatically.
.IP "bc" 4
.IX Item "bc"
A \*(L"bc\*(R" signature is short for \*(L"block code\*(R", which implies
a preformatted section like the \*(L"pre\*(R" block, but it also
gets a \f(CW\*(C`<code>\*(C'\fR tag (or for \s-1XHTML 2,\s0 a \f(CW\*(C`<blockcode>\*(C'\fR
tag is used instead).
.Sp
Note that within a \*(L"bc\*(R" block, < and > are
translated into \s-1HTML\s0 entities automatically.
.IP "table" 4
.IX Item "table"
For composing \s-1HTML\s0 tables. See the \*(L"\s-1TABLES\*(R"\s0 section for more
information.
.IP "bq" 4
.IX Item "bq"
A \*(L"bq\*(R" signature is short for \*(L"block quote\*(R". Paragraph text
formatting is applied to these blocks and they are enclosed
in a <blockquote> tag as well as <p> tags
within.
.IP "h1, h2, h3, h4, h5, h6" 4
.IX Item "h1, h2, h3, h4, h5, h6"
Headline signatures that produce \f(CW\*(C`<h1>\*(C'\fR, etc. tags.
You can adjust the relative output of these using the
head_offset attribute.
.IP "clear" 4
.IX Item "clear"
A \*(L"clear\*(R" signature is simply used to indicate that the next
block should emit a \s-1CSS\s0 style attribute that clears any
floating elements. The default behavior is to clear \*(L"both\*(R",
but you can use the left (<) or right (>) alignment
characters to indicate which side to clear.
.IP "dl" 4
.IX Item "dl"
A \*(L"dl\*(R" signature is short for \*(L"definition list\*(R". See the
\&\*(L"\s-1LISTS\*(R"\s0 section for more information.
.IP "fn" 4
.IX Item "fn"
A \*(L"fn\*(R" signature is short for \*(L"footnote\*(R". You add a number
following the \*(L"fn\*(R" keyword to number the footnote. Footnotes
are output as paragraph tags but are given a special \s-1CSS\s0
class name which can be used to style them as you see fit.
.PP
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:
.ie n .IP """{style rule}""" 4
.el .IP "\f(CW{style rule}\fR" 4
.IX Item "{style rule}"
A \s-1CSS\s0 style rule. Style rules can span multiple lines.
.ie n .IP """[ll]""" 4
.el .IP "\f(CW[ll]\fR" 4
.IX Item "[ll]"
A language identifier (for a \*(L"lang\*(R" attribute).
.ie n .IP """(class)"" or ""(#id)"" or ""(class#id)""" 4
.el .IP "\f(CW(class)\fR or \f(CW(#id)\fR or \f(CW(class#id)\fR" 4
.IX Item "(class) or (#id) or (class#id)"
For \s-1CSS\s0 class and id attributes.
.ie n .IP """>"", ""<"", ""="", ""<>""" 4
.el .IP "\f(CW>\fR, \f(CW<\fR, \f(CW=\fR, \f(CW<>\fR" 4
.IX Item ">, <, =, <>"
Modifier characters for alignment. Right-justification, left-justification,
centered, and full-justification.
.ie n .IP """("" (one or more)" 4
.el .IP "\f(CW(\fR (one or more)" 4
.IX Item "( (one or more)"
Adds padding on the left. 1em per \*(L"(\*(R" character is applied.
When combined with the align-left or align-right modifier,
it makes the block float.
.ie n .IP """)"" (one or more)" 4
.el .IP "\f(CW)\fR (one or more)" 4
.IX Item ") (one or more)"
Adds padding on the right. 1em per \*(L")\*(R" character is applied.
When combined with the align-left or align-right modifier,
it makes the block float.
.ie n .IP """|filter|"" or ""|filter|filter|filter|""" 4
.el .IP "\f(CW|filter|\fR or \f(CW|filter|filter|filter|\fR" 4
.IX Item "|filter| or |filter|filter|filter|"
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.
.SS "Extended Blocks"
.IX Subsection "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.
.PP
For example:
.PP
.Vb 1
\&    bq.. This is paragraph one of a block quote.
\&
\&    This is paragraph two of a block quote.
\&
\&    p. Now we\*(Aqre back to a regular paragraph.
.Ve
.PP
You can apply this technique to any signature (although for
some it doesn't make sense, like \*(L"h1\*(R" for example). This is
especially useful for \*(L"bc\*(R" blocks where your code may
have many blank lines scattered through it.
.SS "Escaping"
.IX Subsection "Escaping"
Sometimes you want Textile to just get out of the way and
let you put some regular \s-1HTML\s0 markup in your document. You
can disable Textile formatting for a given block using the \*(L"==\*(R"
escape mechanism:
.PP
.Vb 1
\&    p. Regular paragraph
\&
\&    ==
\&    Escaped portion \-\- will not be formatted
\&    by Textile at all
\&    ==
\&
\&    p. Back to normal.
.Ve
.PP
You can also use this technique within a Textile block,
temporarily disabling the inline formatting functions:
.PP
.Vb 1
\&    p. This is ==*a test*== of escaping.
.Ve
.SS "Inline Formatting"
.IX Subsection "Inline Formatting"
Formatting within a block of text is covered by the \*(L"inline\*(R"
formatting rules. These operators must be placed up against
text/punctuation to be recognized. These include:
.ie n .IP "*""strong""*" 4
.el .IP "*\f(CWstrong\fR*" 4
.IX Item "*strong*"
Translates into <strong>strong</strong>.
.ie n .IP """_emphasis_""" 4
.el .IP "\f(CW_emphasis_\fR" 4
.IX Item "_emphasis_"
Translates into <em>emphasis</em>.
.ie n .IP "**""bold""**" 4
.el .IP "**\f(CWbold\fR**" 4
.IX Item "**bold**"
Translates into <b>bold</b>.
.ie n .IP """_\|_italics_\|_""" 4
.el .IP "\f(CW_\|_italics_\|_\fR" 4
.IX Item "__italics__"
Translates into <i>italics</i>.
.ie n .IP """++bigger++""" 4
.el .IP "\f(CW++bigger++\fR" 4
.IX Item "++bigger++"
Translates into <big>bigger</big>.
.ie n .IP """\-\-smaller\-\-""" 4
.el .IP "\f(CW\-\-smaller\-\-\fR" 4
.IX Item "--smaller--"
Translates into: <small>smaller</small>.
.ie n .IP """\-deleted text\-""" 4
.el .IP "\f(CW\-deleted text\-\fR" 4
.IX Item "-deleted text-"
Translates into <del>deleted text</del>.
.ie n .IP """+inserted text+""" 4
.el .IP "\f(CW+inserted text+\fR" 4
.IX Item "+inserted text+"
Translates into <ins>inserted text</ins>.
.ie n .IP """^superscript^""" 4
.el .IP "\f(CW^superscript^\fR" 4
.IX Item "^superscript^"
Translates into <sup>superscript</sup>.
.ie n .IP """~subscript~""" 4
.el .IP "\f(CW~subscript~\fR" 4
.IX Item "~subscript~"
Translates into <sub>subscript</sub>.
.ie n .IP """%span%""" 4
.el .IP "\f(CW%span%\fR" 4
.IX Item "%span%"
Translates into <span>span</span>.
.ie n .IP """@code@""" 4
.el .IP "\f(CW@code@\fR" 4
.IX Item "@code@"
Translates into <code>code</code>. Note
that within a \*(L"@...@\*(R" section, < and > are
translated into \s-1HTML\s0 entities automatically.
.PP
Inline formatting operators accept the following modifiers:
.ie n .IP """{style rule}""" 4
.el .IP "\f(CW{style rule}\fR" 4
.IX Item "{style rule}"
A \s-1CSS\s0 style rule.
.ie n .IP """[ll]""" 4
.el .IP "\f(CW[ll]\fR" 4
.IX Item "[ll]"
A language identifier (for a \*(L"lang\*(R" attribute).
.ie n .IP """(class)"" or ""(#id)"" or ""(class#id)""" 4
.el .IP "\f(CW(class)\fR or \f(CW(#id)\fR or \f(CW(class#id)\fR" 4
.IX Item "(class) or (#id) or (class#id)"
For \s-1CSS\s0 class and id attributes.
.PP
\fIExamples\fR
.IX Subsection "Examples"
.PP
.Vb 1
\&    Textile is *way* cool.
\&
\&    Textile is *_way_* cool.
.Ve
.PP
Now this won't work, because the formatting
characters need whitespace before and after
to be properly recognized.
.PP
.Vb 1
\&    Textile is way c*oo*l.
.Ve
.PP
However, you can supply braces or brackets to
further clarify that you want to format, so
this would work:
.PP
.Vb 1
\&    Textile is way c[*oo*]l.
.Ve
.SS "Footnotes"
.IX Subsection "Footnotes"
You can create footnotes like this:
.PP
.Vb 1
\&    And then he went on a long trip[1].
.Ve
.PP
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:
.PP
.Vb 2
\&    And then he went on a long
\&    trip<sup class="footnote"><a href="#fn1">1</a></sup>
.Ve
.PP
To supply the content of the footnote, place it at the end of your
document using a \*(L"fn\*(R" block signature:
.PP
.Vb 1
\&    fn1. And there was much rejoicing.
.Ve
.PP
Which creates a paragraph that looks like this:
.PP
.Vb 2
\&    <p class="footnote" id="fn1"><sup>1</sup> And there was
\&    much rejoicing.</p>
.Ve
.SS "Links"
.IX Subsection "Links"
Textile defines a shorthand for formatting hyperlinks.
The format looks like this:
.PP
.Vb 1
\&    "Text to display":http://example.com
.Ve
.PP
In addition to this, you can add \*(L"title\*(R" text to your link:
.PP
.Vb 1
\&    "Text to display (Title text)":http://example.com
.Ve
.PP
The \s-1URL\s0 portion of the link supports relative paths as well
as other protocols like ftp, mailto, news, telnet, etc.
.PP
.Vb 1
\&    "E\-mail me please":mailto:someone@example.com
.Ve
.PP
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 \s-1URL\s0). If you have to place a \s-1URL\s0 next to
some other text, use the bracket or brace trick to do that:
.PP
.Vb 1
\&    You["gotta":http://example.com]seethis!
.Ve
.PP
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):
.PP
.Vb 2
\&    [excom]http://example.com
\&    [exorg]http://example.org
.Ve
.PP
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:
.PP
.Vb 1
\&    "Text to display":excom
.Ve
.PP
Once you've defined your link lookup table, you can use
the identifiers any number of times.
.SS "Images"
.IX Subsection "Images"
Images are identified by the following pattern:
.PP
.Vb 1
\&    !/path/to/image!
.Ve
.PP
Image attributes may also be specified:
.PP
.Vb 1
\&    !/path/to/image 10x20!
.Ve
.PP
Which will render an image 10 pixels wide and 20 pixels high.
Another way to indicate width and height:
.PP
.Vb 1
\&    !/path/to/image 10w 20h!
.Ve
.PP
You may also redimension the image using a percentage.
.PP
.Vb 1
\&    !/path/to/image 20%x40%!
.Ve
.PP
Which will render the image at 20% of it's regular width
and 40% of it's regular height.
.PP
Or specify one percentage to resize proprotionately:
.PP
.Vb 1
\&    !/path/to/image 20%!
.Ve
.PP
Alt text can be given as well:
.PP
.Vb 1
\&    !/path/to/image (Alt text)!
.Ve
.PP
The path of the image may refer to a locally hosted image or
can be a full \s-1URL.\s0
.PP
You can also use the following modifiers after the opening \*(L"!\*(R"
character:
.ie n .IP """<""" 4
.el .IP "\f(CW<\fR" 4
.IX Item "<"
Align the image to the left (causes the image to float if
\&\s-1CSS\s0 options are enabled).
.ie n .IP """>""" 4
.el .IP "\f(CW>\fR" 4
.IX Item ">"
Align the image to the right (causes the image to float if
\&\s-1CSS\s0 options are enabled).
.ie n .IP """\-"" (dash)" 4
.el .IP "\f(CW\-\fR (dash)" 4
.IX Item "- (dash)"
Aligns the image to the middle.
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
Aligns the image to the top.
.ie n .IP """~"" (tilde)" 4
.el .IP "\f(CW~\fR (tilde)" 4
.IX Item "~ (tilde)"
Aligns the image to the bottom.
.ie n .IP """{style rule}""" 4
.el .IP "\f(CW{style rule}\fR" 4
.IX Item "{style rule}"
Applies a \s-1CSS\s0 style rule to the image.
.ie n .IP """(class)"" or ""(#id)"" or ""(class#id)""" 4
.el .IP "\f(CW(class)\fR or \f(CW(#id)\fR or \f(CW(class#id)\fR" 4
.IX Item "(class) or (#id) or (class#id)"
Applies a \s-1CSS\s0 class and/or id to the image.
.ie n .IP """("" (one or more)" 4
.el .IP "\f(CW(\fR (one or more)" 4
.IX Item "( (one or more)"
Pads 1em on the left for each \*(L"(\*(R" character.
.ie n .IP """)"" (one or more)" 4
.el .IP "\f(CW)\fR (one or more)" 4
.IX Item ") (one or more)"
Pads 1em on the right for each \*(L")\*(R" character.
.SS "Character Replacements"
.IX Subsection "Character Replacements"
A few simple, common symbols are automatically replaced:
.PP
.Vb 3
\&    (c)
\&    (r)
\&    (tm)
.Ve
.PP
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:
.PP
.Vb 3
\&    {c|} or {|c} cent sign
\&    {L\-} or {\-L} pound sign
\&    {Y=} or {=Y} yen sign
.Ve
.PP
Many of these macros can be guessed. For example:
.PP
.Vb 6
\&    {A\*(Aq} or {\*(AqA}
\&    {a"} or {"a}
\&    {1/4}
\&    {*}
\&    {:)}
\&    {:(}
.Ve
.SS "Lists"
.IX Subsection "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.
.PP
Simple lists:
.PP
.Vb 3
\&    * one
\&    * two
\&    * three
.Ve
.PP
Multi-level lists:
.PP
.Vb 8
\&    * one
\&    ** one A
\&    ** one B
\&    *** one B1
\&    * two
\&    ** two A
\&    ** two B
\&    * three
.Ve
.PP
Ordered lists:
.PP
.Vb 3
\&    # one
\&    # two
\&    # three
.Ve
.PP
Styling lists:
.PP
.Vb 3
\&    (class#id)* one
\&    * two
\&    * three
.Ve
.PP
The above sets the class and id attributes for the <ul>
tag.
.PP
.Vb 3
\&    *(class#id) one
\&    * two
\&    * three
.Ve
.PP
The above sets the class and id attributes for the first <li>
tag.
.PP
Definition lists:
.PP
.Vb 3
\&    dl. textile:a cloth, especially one manufactured by weaving
\&    or knitting; a fabric
\&    format:the arrangement of data for storage or display.
.Ve
.PP
Note that there is no space between the term and definition. The
term must be at the start of the line (or following the \*(L"dl\*(R"
signature as shown above).
.SS "Tables"
.IX Subsection "Tables"
Textile supports tables. Tables must be in their own block and
must have pipe characters delimiting the columns. An optional
block signature of \*(L"table\*(R" may be used, usually for applying
style, class, id or other options to the table element itself.
.PP
From the simple:
.PP
.Vb 2
\&    |a|b|c|
\&    |1|2|3|
.Ve
.PP
To the complex:
.PP
.Vb 3
\&    table(fig). {color:red}_|Top|Row|
\&    {color:blue}|/2. Second|Row|
\&    |_{color:green}. Last|
.Ve
.PP
Modifiers can be specified for the table signature itself,
for a table row (prior to the first \*(L"|\*(R" character) and
for any cell (following the \*(L"|\*(R" 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.
.PP
Modifiers allowed are:
.ie n .IP """{style rule}""" 4
.el .IP "\f(CW{style rule}\fR" 4
.IX Item "{style rule}"
A \s-1CSS\s0 style rule.
.ie n .IP """(class)"" or ""(#id)"" or ""(class#id)""" 4
.el .IP "\f(CW(class)\fR or \f(CW(#id)\fR or \f(CW(class#id)\fR" 4
.IX Item "(class) or (#id) or (class#id)"
A \s-1CSS\s0 class and/or id attribute.
.ie n .IP """("" (one or more)" 4
.el .IP "\f(CW(\fR (one or more)" 4
.IX Item "( (one or more)"
Adds 1em of padding to the left for each \*(L"(\*(R" character.
.ie n .IP """)"" (one or more)" 4
.el .IP "\f(CW)\fR (one or more)" 4
.IX Item ") (one or more)"
Adds 1em of padding to the right for each \*(L")\*(R" character.
.ie n .IP """<""" 4
.el .IP "\f(CW<\fR" 4
.IX Item "<"
Aligns to the left (floats to left for tables if combined with the
\&\*(L")\*(R" modifier).
.ie n .IP """>""" 4
.el .IP "\f(CW>\fR" 4
.IX Item ">"
Aligns to the right (floats to right for tables if combined with
the \*(L"(\*(R" modifier).
.ie n .IP """=""" 4
.el .IP "\f(CW=\fR" 4
.IX Item "="
Aligns to center (sets left, right margins to \*(L"auto\*(R" for tables).
.ie n .IP """<>""" 4
.el .IP "\f(CW<>\fR" 4
.IX Item "<>"
For cells only. Justifies text.
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
For rows and cells only. Aligns to the top.
.ie n .IP """~"" (tilde)" 4
.el .IP "\f(CW~\fR (tilde)" 4
.IX Item "~ (tilde)"
For rows and cells only. Aligns to the bottom.
.ie n .IP """_"" (underscore)" 4
.el .IP "\f(CW_\fR (underscore)" 4
.IX Item "_ (underscore)"
Can be applied to a table row or cell to indicate a header
row or cell.
.ie n .IP """\e2"" or ""\e3"" or ""\e4"", etc." 4
.el .IP "\f(CW\e2\fR or \f(CW\e3\fR or \f(CW\e4\fR, etc." 4
.IX Item "2 or 3 or 4, etc."
Used within cells to indicate a colspan of 2, 3, 4, etc. columns.
When you see \*(L"\e\*(R", think \*(L"push forward\*(R".
.ie n .IP """/2"" or ""/3"" or ""/4"", etc." 4
.el .IP "\f(CW/2\fR or \f(CW/3\fR or \f(CW/4\fR, etc." 4
.IX Item "/2 or /3 or /4, etc."
Used within cells to indicate a rowspan or 2, 3, 4, etc. rows.
When you see \*(L"/\*(R", think \*(L"push downward\*(R".
.PP
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.
.SS "\s-1CSS\s0 Notes"
.IX Subsection "CSS Notes"
When \s-1CSS\s0 is enabled (and it is by default), \s-1CSS\s0 class names
are automatically applied in certain situations.
.IP "Aligning a block or span or other element to left, right, etc." 4
.IX Item "Aligning a block or span or other element to left, right, etc."
\&\*(L"left\*(R" for left justified, \*(L"right\*(R" for right justified,
\&\*(L"center\*(R" for centered text, \*(L"justify\*(R" for full-justified
text.
.IP "Aligning an image to the top or bottom" 4
.IX Item "Aligning an image to the top or bottom"
\&\*(L"top\*(R" for top alignment, \*(L"bottom\*(R" for bottom alignment,
\&\*(L"middle\*(R" for middle alignment.
.IP "Footnotes" 4
.IX Item "Footnotes"
\&\*(L"footnote\*(R" is applied to the paragraph tag for the
footnote text itself. An id of \*(L"fn\*(R" plus the footnote
number is placed on the paragraph for the footnote as
well. For the footnote superscript tag, a class of
\&\*(L"footnote\*(R" is used.
.IP "Capped text" 4
.IX Item "Capped text"
For a series of characters that are uppercased, a
span is placed around them with a class of \*(L"caps\*(R".
.SS "Miscellaneous"
.IX Subsection "Miscellaneous"
Textile tries to do it's very best to ensure proper \s-1XHTML\s0
syntax. It will even attempt to fix errors you may introduce
writing in \s-1HTML\s0 yourself. Unescaped \*(L"&\*(R" characters within
URLs will be properly escaped. Singlet tags such as br, img
and hr are checked for the \*(L"/\*(R" terminator (and it's added
if necessary). The best way to make sure you produce valid
\&\s-1XHTML\s0 with Textile is to not use any \s-1HTML\s0 markup at all\*(--
use the Textile syntax and let it produce the markup for you.
.SH "BUGS & SOURCE"
.IX Header "BUGS & SOURCE"
Text::Textile is hosted at github.
.PP
Source: <http://github.com/bradchoate/text\-textile/tree/master>
.PP
Bugs: <http://github.com/bradchoate/text\-textile/issues>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005\-2009 Brad Choate, brad@bradchoate.com.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of either:
.IP "\(bu" 4
the \s-1GNU\s0 General Public License as published by the Free
Software Foundation; either version 1, or (at your option) any later
version, or
.IP "\(bu" 4
the Artistic License version 2.0.
.PP
Text::Textile is an adaptation of Textile, developed by Dean Allen
of Textism.com.