Text::Textile(3pm)
π NAME π
Text::Textile β A humane web text generator. π¦ (yes bestie, it's the Perl one, from the User Contributed Perl Documentation corner of the world, section 3pm, we love her)
β¨ SYNOPSIS β¨
okay so here's the whole vibe in one go, no cap:
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;
two ways to slay: call it like a function, or make an object and let her cook. either way you get HTML out the other side. π
πΈ ABSTRACT πΈ
Text::Textile is a Perl-based implementation of Dean Allen's Textile syntax, and Textile is basically shorthand for doing all the common formatting tasks. it's giving "I don't wanna type raw HTML, I wanna type vibes" and honestly? iconic. π
π METHODS π
this is the main character section, bestie. every method, every option, no skips. π
π§ new( [%options] )
Instantiates a brand new Text::Textile object. β¨ You can pass optional options in to initialize the object β and the attribute names for that options key are the exact same as the get/set method names documented right here in this page. iykyk. π«Ά
π set( $attribute, $value )
Used to set Textile attributes. Attribute names are, once again, the same as the get/set method names documented here. consistency queen. π
π get( $attribute )
Used to get Textile attributes. Attribute names = the same get/set method names documented here. you get the drill by now. π
π disable_html( [$disable] )
Gets or sets the "disable html" control, which is the little switch that lets you prevent HTML tags from being used inside the text you're processing. Any HTML tags that show up get removed when disable html is enabled. default behavior? HTML is allowed. so unless you flip it, she's permissive. π¦
π flavor( [$flavor] )
Assigns the HTML flavor of the output from Text::Textile. rn these are the valid choices:
htmlxhtmlβ behaves like"xhtml1"xhtml1xhtml2
default flavor is "xhtml1". π
lowkey important: the xhtml2 flavor support is experimental and incomplete β and it's gonna stay that way until the XHTML 2.0 draft becomes a proper recommendation. so like, don't build your whole life on it.
π css( [$css] )
Gets or sets the CSS support for Textile. If CSS is enabled, Textile will emit CSS rules. You can pass a 1 or a 0 to turn CSS behavior on or off altogether. ποΈ
But if you pass a hashref, you get to assign the CSS class names that Text::Textile uses. The following key names for that hash are recognized:
class_align_rightβ defaults to"right"class_align_leftβ defaults to"left"class_align_centerβ defaults to"center"class_align_topβ defaults to"top"class_align_bottomβ defaults to"bottom"class_align_middleβ defaults to"middle"class_align_justifyβ defaults to"justify"class_capsβ defaults to"caps"class_footnoteβ defaults to"footnote"id_footnote_prefixβ defaults to"fn"
π¦ charset( [$charset] )
Gets or sets the character set targeted for publication. atm Text::Textile only changes its behavior if the "utf-8" character set is assigned. β¨
Specifically: if utf-8 is requested, any special characters created by Textile get output as native utf-8 characters rather than HTML entities. glowing, radiant, un-entity-fied. π
π§ docroot( [$path] )
Gets or sets the physical file path to the root of document files. This path gets utilized when images are referenced and size calculations are needed β and yes, the Image::Size module is what's used to read those image dimensions. π
π trim_spaces( [$trim] )
Gets or sets the "trim spaces" control flag. If you enable it, this will clear out any lines that have only spaces on them (the newline itself stays, she's not dramatic). π§Ή
π preserve_spaces( [$preserve] )
Gets or sets the "preserve spaces" control flag. If enabled, this replaces any double spaces within the paragraph data with the   HTML entity (that's the wide space, bestie). The default is 0.
With default behavior, spaces just pass through to the browser unchanged and render as a single space. π
note note note: this setting has no effect on spaces within"<pre>","<code>"or"<script>". those are exempt, periodt.
π filter_param( [$data] )
Gets or sets a parameter that gets passed to filters. π¦
πΈ 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. π
π 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 <, >", " and & are encoded to HTML entities. ποΈ
(ok wait, re-reading: it's <, >, " and & β the four little gremlins that get escaped.)
β 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. And because she's a boss, this also supersedes the "char_encoding" flag. so she wins the argument, always. π
π handle_quotes( [$handle] )
Gets or sets the "smart quoting" control flag. Returns the current setting. βοΈ
π§ process( $str )
Alternative method for invoking the textile method. same energy, different door. πͺ
π¦ textile( $str )
Can be called either procedurally or as a method. Transforms $str using Textile markup rules. this is the method, the moment, the whole point. π
π
format_paragraph( [$args] )
Processes a single paragraph. The following attributes are allowed:
textβ the text to be processed.
π format_inline( [%args] )
Processes an inline string (plaintext) for Textile syntax. The following attributes are allowed:
textβ the text to be processed.
π format_macro( %args )
Responsible for processing a particular macro. Arguments passed include:
preβ open brace characterpostβ close brace charactermacroβ the macro to be executed
The return value from this method would be the replacement text for the macro given. And if the macro isn't defined? She returns pre + macro + post, thereby preserving the original macro string. no data lost, we respect the source. π
π format_cite( %args )
Processes text for a citation tag. The following attributes are allowed:
preβ any text that comes before the citation.textβ the text that is being cited.citeβ the URL of the citation.postβ any text that follows the citation.
π format_code( %args )
Processes '@...@' type blocks (code snippets). The following attributes are allowed:
textβ the text of the code itself.langβ the language (programming language) for the code.
π§ format_classstyle( $clsty, $class, $style )
Returns a string of tag attributes to accommodate the class, style and symbols present in $clsty. π§
$clsty is checked for:
"{...}"β style rules. If present, they are appended to$style."(...#...)"β class and/or ID name declaration"("(one or more) β pad left characters")"(one or more) β pad right characters"[ll]"β language declaration
The attribute string returned will contain any combination of class, id, style and/or lang attributes. mix and match, she handles it. π
π format_tag( %args )
Constructs an HTML tag. Accepted arguments:
tagβ the tag to producetextβ the text to output inside the tagpreβ text to produce before the tagpostβ text to produce following the tagclstyβ class and/or style attributes that should be assigned to the tag.
π¦ format_list( %args )
Takes a Textile formatted list (numeric or bulleted) and returns the markup for it. The text that's passed in requires substantial parsing, so the format_list method is a little involved β she's doing a lot, give her a second. π«Ά
But it should always produce a proper ordered or unordered list. If it cannot (due to misbalanced input), it will return the original text. no cap, she'd rather hand you back what you gave her than lie to you. π
Arguments accepted:
textβ the text to be processed.
π format_block( %args )
Processes "==xxxxx==" type blocks for filters. A filter would follow the open == sequence and is specified within pipe characters, like so:
==|filter|text to be filtered==
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. π’
πΈ format_link( %args )
Takes the Textile link attributes and transforms them into a hyperlink. clickable. iconic. π
β format_url( %args )
Takes the given $url and transforms it appropriately. β¨
π format_span( %args )
(yes bestie, she's here, she just doesn't come with a description in this doc. still valid, still part of the family. π)
π§ format_image( %args )
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. πΌοΈ
Arguments you may pass:
srcβ 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 thedocrootmethod is used to specify where the docroot resides. If the image can be found, theimage_sizemethod is used to determine the dimensions of the image.extraβ additional parameters for the image. This would include alt text, height/width specification or scaling instructions.alignβ alignment attribute.preβ text to produce prior to the tag.postβ text to produce following the tag.linkβ optional URL to connect with the image tag.clstyβ class and/or style attributes.
π format_table( %args )
Takes a Wiki-ish string of data and transforms it into a full table. π wiki vibes in, table vibes out.
π apply_filters( %args )
The following attributes are allowed:
textβ the text to be processed.filtersβ an array reference of filter names to run for the given text.
π encode_html( $html, $can_double_encode )
Encodes the input $html string, escaping characters as needed to HTML entities. This relies on the HTML::Entities package for full effect. If that's unavailable, encode_html_basic is used as a fallback technique. And if the "char_encoding" flag is set to false, encode_html_basic is used exclusively. π
π decode_html( $html )
Decodes HTML entities in $html back to their natural character equivalents. the reverse uno card. π
π encode_html_basic( $html, $can_double_encode )
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 an HTML entity already. nuance queen. π
π§ image_size( $file )
Returns the size for the image identified in $file. This method relies upon the Image::Size Perl package. If that's unavailable, image_size will return undef. Otherwise, the expected return value is a list of the width and height (in that order), in pixels. π
π encode_url( $str )
Encodes the query portion of a URL, escaping characters as necessary. π
π¦ mail_encode( $email )
Encodes the email address in $email for "mailto:" links. π§
π process_quotes( $str )
Processes a string, formatting plain quotes into curly quotes. π¬ so fancy.
β default_macros
Returns a hashref of macros that are assigned to be processed by default within the format_inline method. π¦
π _halign( $alignment )
Returns the alignment keyword depending on the symbol passed:
"<>"β becomes"justify""<"β becomes"left"">"β becomes"right""="β becomes"center"
symbols in, alignment words out. she translates. πͺ
_valign( $alignment ) π«Ά
Gives you back the alignment keyword that matches whatever symbol you handed it:
"^"becomes"top""~"becomes"bottom""-"becomes"middle"
_imgalign( $alignment ) πΌοΈ
Same deal, gives you back the alignment keyword based on the symbol you passed. It recognizes all these alignment symbols, and it gives them preference in the order listed:
"^"becomes"top""~"becomes"bottom""-"becomes"middle""<"becomes"left"">"becomes"right"
_repl( \@arr, $str ) π₯
An internal routine π β it takes a string and appends it onto an array. Then it hands back a marker, and that marker gets used later to put the preserved string back where it belongs.
_tokenize( $str ) βοΈ
Another internal routine, bestie. This one's whole job is breaking a string up into its individual tag elements and plaintext elements.
_css_defaults π
Sets up the default CSS names for all the CSS-controlled markup. This is an internal function and you should NOT call it directly, okay? Hands off.
_strip_borders( $pre, $post ) π§Ό
A utility routine that'll take the "border" characters off the given $pre and $post strings, but only if they match one of these conditions:
$pre starts with "[", $post ends with "]"
$pre starts with "{", $post ends with "}"
If neither condition hits, then $pre and $post just stay exactly as they were. Untouched, unbothered, living their truth. β¨
β SYNTAX β
Okay so this is the part you actually came for. Text::Textile processes text in units of blocks and lines. A block is basically a paragraph β like, blocks get separated from each other by a blank line. And a block can start with a signature that helps identify what the rest of the block content actually is. The block signatures are:
pβ a paragraph block. This is the default signature if you don't explicitly give one. Paragraphs get formatted with all the inline rules (peep the inline formatting section) and every line receives the appropriate markup rules for whichever flavor of HTML you're using. For example, newlines in XHTML content get a"<br />"tag at the end of the line (except for the last line in the paragraph, obviously). Paragraph blocks are wrapped in a"<p>"tag.preβ a pre-formatted block of text. Textile will not add any HTML tags for individual lines here. Whitespace is preserved too. π«Ά
Heads up: inside a"pre"block,<and>get translated into HTML entities automatically.
bcβ short for "block code", which means it's a preformatted section like"pre", except it also gets a"<code>"tag. (Or, for XHTML 2, a"<blockcode>"tag gets used instead.) π»
Same warning as before: inside a"bc"block,<and>get translated into HTML entities automatically.
tableβ for composing HTML tables. Go look at the"TABLES"section for the tea. βbqβ short for "block quote". Paragraph text formatting gets applied to these blocks, and they get wrapped in a<blockquote>tag, plus<p>tags inside. π¬h1,h2,h3,h4,h5,h6β headline signatures that produce"<h1>", etc. tags. You can adjust the relative output of these with thehead_offsetattribute. πclearβ this signature just says "the next block should emit a CSS style attribute that clears any floating elements." Default behavior is to clear"both", but you can use the left (<) or right (>) alignment characters to say which side to clear.dlβ short for "definition list". See the"LISTS"section for more. πfnβ short for "footnote". You add a number after the"fn"keyword to number the footnote. Footnotes get output as paragraph tags, but they also get a special CSS class name so you can style them however you want. π
All signatures should end with a period and then be followed with a space. And inbetween the signature and the period, you can use several parameters to customize the block even more. These include:
"{style rule}"β a CSS style rule. Style rules can span multiple lines. π¨"[ll]"β a language identifier (for a"lang"attribute)."(class)"or"(#id)"or"(class#id)"β for CSS class and id attributes.">","<","=","<>"β modifier characters for alignment. Respectively: right-justification, left-justification, centered, and full-justification. βοΈ"("(one or more) β adds padding on the left.1emper"("character gets applied. When you combine it with the align-left or align-right modifier, it makes the block float.")"(one or more) β adds padding on the right.1emper")"character gets applied. When you combine it with the align-left or align-right modifier, it makes the block float."|filter|"or"|filter|filter|filter|"β a filter can be invoked to further format the text for this signature. If one or more filters are identified, the text gets processed first using the filters, and then by Textile's own block formatting rules. π₯
πΈ Extended Blocks πΈ
Normally, a block ends at the first blank line it runs into. But sometimes you want a block to keep going across multiple paragraphs of text. To make a given block signature stay active, use two periods in your signature instead of one. That tells Textile to keep processing with that signature until it hits the next signature.
Like, 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 β bestie, why). It's especially useful for "bc" blocks where your code might have a ton of blank lines scattered through it. π
π¦ Escaping π¦
Sometimes you just want Textile to 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 handled by the "inline" formatting rules. These operators have to be placed up against text/punctuation to get recognized. Here's the whole roster:
*"strong"*β translates into<strong>strong</strong>."_emphasis_"β translates into<em>emphasis</em>.**"bold"**β translates into<b>bold</b>.__"italics__"β translates into<i>italics</i>."++bigger++"β translates into<big>bigger</big>."--smaller--"β translates into:<small>smaller</small>."-deleted text-"β translates into<del>deleted text</del>."+inserted text+"β translates into<ins>inserted text</ins>."^superscript^"β translates into<sup>superscript</sup>."~subscript~"β translates into<sub>subscript</sub>."%span%"β translates into<span>span</span>."@code@"β translates into<code>code</code>. Note that within an"@...@"section,<and>get translated into HTML entities automatically.
Inline formatting operators accept these modifiers:
"{style rule}"β a CSS style rule."[ll]"β a language identifier (for a"lang"attribute)."(class)"or"(#id)"or"(class#id)"β for CSS class and id attributes.
Examples β¨
Textile is *way* cool.
Textile is *_way_* cool.
Now this next one won't work, because formatting characters need whitespace before and after them to get properly recognized:
Textile is way c*oo*l.
But! You can supply braces or brackets to make it extra clear that you want formatting, 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 those brackets with a number inside, Textile recognizes it as a footnote marker. Then it replaces that with a construct like this:
And then he went on a long
trip<sup class="footnote"><a href="#fn1">1</a></sup>
To supply the actual content of the footnote, drop 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:
<p class="footnote" id="fn1"><sup>1</sup> And there was
much rejoicing.</p>
π Links π
Textile has a shorthand for formatting hyperlinks. The format looks like this:
"Text to display":http://example.com
On top of that, 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 and 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 that's more your vibe. And just like with the inline formatting rules, a hyperlink has to be surrounded by whitespace to get recognized (the exception to this is common punctuation, which can sit at the end of the URL). If you absolutely have to place a URL right next to some other text, use the bracket or brace trick to pull it off:
You["gotta":http://example.com]seethis!
Textile also supports an alternate way to compose links. You can optionally create a lookup list of links and refer to them separately. To do that, place one or more links in a block of its 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 you gave. To refer to that link, you'd specify it like this:
"Text to display":excom
Once you've defined your link lookup table, you can use those identifiers as many times as you want. π
πΌοΈ Images πΌοΈ
Images get identified by this pattern:
!/path/to/image!
Image attributes can be specified too:
!/path/to/image 10x20!
Which renders an image 10 pixels wide and 20 pixels high. Another way to say the width and height:
!/path/to/image 10w 20h!
You can also redimension the image using a percentage:
!/path/to/image 20%x40%!
Which renders the image at 20% of its regular width and 40% of its regular height.
Or you can specify just one percentage to resize it proportionately:
!/path/to/image 20%!
Alt text can be given as well:
!/path/to/image (Alt text)!
The path of the image can point to a locally hosted image, or it can be a full URL. π
You can also use the following modifiers after the opening "!" character:
"<"β align the image to the left (causes the image to float if CSS options are enabled).>β pushes the image to the right. Heads up tho, it also makes the image float if CSS options are enabled β¨-(dash) β aligns the image to the middle.^β aligns the image to the top.~(tilde) β aligns the image to the bottom.{style rule}β applies a CSS style rule to the image π(class)or(#id)or(class#id)β applies a CSS class and/or id to the image.((one or more) β pads1emon the left for each(character.)(one or more) β pads1emon the right for each)character.
π€ Character Replacements π€
A few simple, common symbols get auto-swapped, no effort required bestie:
(c)
(r)
(tm)
And on top of those, there's a whole set of character macros that are defined by default. Every macro gets wrapped in curly braces π and they include:
{c|}or{|c}β cent sign{L-}or{-L}β pound sign{Y=}or{=Y}β yen sign
So many of these macros are guessable, like, the vibes will carry you. For example:
{A'} or {'A}
{a"} or {"a}
{1/4}
{*}
{:)}
{:(}
π Lists π
Textile also does ordered and unordered lists, no cap. You literally just drop an asterisk or a pound sign, followed by a space, at the start of your lines. Periodt.
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
That one above sets the class and id attributes for the <ul> tag β¨
*(class#id) one
* two
* three
And that one 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 the tea: there's no space between the term and the definition. The term has to sit at the start of the line (or right after the dl signature, like in the example above). Miss that and it just won't hit the same π
π Tables π
Textile supports tables too, obviously. Tables have to live in their own block and they need pipe characters delimiting the columns. You can also use an optional block signature of table, 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). And for cells specifically: a period followed with a space must be placed after any modifiers, so Textile can tell the modifier apart from the actual cell content. Don't forget it π
Modifiers allowed are:
{style rule}β a CSS style rule.(class)or(#id)or(class#id)β a CSS class and/or id attribute.((one or more) β adds1emof padding to the left for each(character.)(one or more) β adds1emof padding to the right for each)character.<β aligns to the left (floats to left for tables if combined with the)modifier).>β aligns to the right (floats to right for tables if combined with the(modifier).=β aligns to center (sets left, right margins toautofor tables).<>β for cells only. Justifies text.^β for rows and cells only. Aligns to the top.~(tilde) β for rows and cells only. Aligns to the bottom._(underscore) β can be applied to a table row or cell to indicate a header row or cell.\2or\3or\4, etc. β used within cells to indicate a colspan of 2, 3, 4, etc. columns. When you see\, think "push forward"./2or/3or/4, etc. β used within cells to indicate a rowspan or 2, 3, 4, etc. rows. When you see/, think "push downward".
And here's the lil inheritance thing: when a cell is identified as a header cell and an alignment is specified, that becomes the default alignment for the 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 get automatically applied in certain situations:
- Aligning a block or span or other element to left, right, etc. β
leftfor left justified,rightfor right justified,centerfor centered text,justifyfor full-justified text. - Aligning an image to the top or bottom β
topfor top alignment,bottomfor bottom alignment,middlefor middle alignment. - Footnotes β
footnoteis applied to the paragraph tag for the footnote text itself. An id offnplus the footnote number is placed on the paragraph for the footnote as well. For the footnote superscript tag, a class offootnoteis used. - Capped text β for a series of characters that are uppercased, a span is placed around them with a class of
caps.
π 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. Trust the process bestie π
π BUGS & SOURCE π
Text::Textile is hosted at github.
- Source:
http://github.com/bradchoate/text-textile/tree/master - Bugs:
http://github.com/bradchoate/text-textile/issues
π COPYRIGHT & LICENSE π
Copyright 2005-2009 Brad Choate, brad@bradchoate.com.
This program is free software; you can redistribute it and/or modify it under the terms of either:
- the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
- the Artistic License version 2.0.
Text::Textile is an adaptation of Textile, developed by Dean Allen of Textism.com.
And that's the whole page, the whole vibe, the whole everything π¦ this one was rendered for perl v5.36.0 and dated 2022-10-13, so that's the version of Text::Textile(3pm) you're looking at β¨ thank you for reading, mwah, slay π
π
π¦ where this page comes from
- ubuntu noble: libtext-textile-perl 2.13-4 Β· Artistic-1.0-Perl OR GPL-1.0-or-later
- ubuntu resolute: libtext-textile-perl 2.13-4 Β· Artistic-1.0-Perl OR GPL-1.0-or-later
- ubuntu stonking: libtext-textile-perl 2.13-4 Β· Artistic-1.0-Perl OR GPL-1.0-or-later
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms