Toledo Talk Source file for article: Textile

Article source for : Textile

[[Textile Quick Reference|Quick Reference]]

==

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:

<h1>Syntax</h1>

<DL>
<DT><A name=p></A>p.
<DD>
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
 tag at the end of the line (with the exception of the last line
in the paragraph). Paragraph blocks are enclosed in a tag.
<DT><A name=pre></A>pre.
<DD>
A pre-formatted block of text. Textile will not add any HTML tags for
individual lines. Whitespace is also preserved.
Note that within a "pre" block, < and > are translated into HTML
entities automatically.
<DT><A name=bc></A>bc.
<DD>
A "bc" signature is short for "block code", which implies a preformatted
section like the 'pre' block, but it also gets a <code> tag (or for
XHTML 2, a <blockcode> tag is used instead).
Note that within a "bc" block, < and > are translated into HTML
entities automatically.
<DT><A name=table></A>table.
<DD>
For composing HTML tables. See the "TABLES" section for more
information.
<DT><A name=bq></A>bq.
<DD>
A "bq" signature is short for "block quote". Paragraph text formatting is
applied to these blocks and they are enclosed in a <blockquote> tag as
well as tags within.
<DT>h1., h2., h3., h4., h5., h6.
<DD>
Headline signatures that produce <h1>, etc. tags. You can adjust the
relative output of these using the head_offset attribute.
<DT><A name=clear></A>clear.
<DD>
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.
<DT><A name=dl></A>dl.
<DD>
A "dl" signature is short for "definition list". See the "LISTS" section
for more information.
<DT><A name=fn></A>fn.
<DD>
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.</DD></DL>
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:
<DL>
<DT><A name=style></A><A name={style_rule}></A><CODE>{style rule}</CODE>
<DD>
A CSS style rule. Style rules can span multiple lines.
<DT><A name=ll></A><A name=[ll]></A><CODE>[ll]</CODE>
<DD>
A language identifier (for a "lang" attribute).
<DT><A name=class></A><A
name=(class)_or_(#id)_or_(class#id)></A><CODE>(class)</CODE> or
<CODE>(#id)</CODE> or <CODE>(class#id)</CODE>
<DD>
For CSS class and id attributes.
<DT><A name=">,_<,_=,_<>"></A><CODE>></CODE>, <CODE><</CODE>,
<CODE>=</CODE>, <CODE><></CODE>
<DD>
Modifier characters for alignment. Right-justification, left-justification,
centered, and full-justification.
<DT><A name=one></A><A name=(_(one_or_more)></A><CODE>(</CODE> (one or more)
<DD>
Adds padding on the left. 1em per "(" character is applied. When combined
with the align-left or align-right modifier, it makes the block float.
<DT><A name=one></A><A name=)_(one_or_more)></A><CODE>)</CODE> (one or more)
<DD>
Adds padding on the right. 1em per ")" character is applied. When combined
with the align-left or align-right modifier, it makes the block float.
<DT><A name=filter></A><A
name=|filter|_or_|filter|filter|filter|></A><CODE>|filter|</CODE> or
<CODE>|filter|filter|filter|</CODE>
<DD>
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.</DD></DL>
<H2><A name=Extended_Blocks></A>Extended Blocks</H2>
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:<PRE> 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.</PRE>
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.
<H2><A name=Escaping></A>Escaping</H2>
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:<PRE> p. Regular paragraph

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

p. Back to normal.</PRE>
You can also use this technique within a Textile block, temporarily disabling
the inline formatting functions:<PRE> p. This is ==*a test*== of escaping.</PRE>
<H2><A name=Inline_Formatting></A>Inline Formatting</H2>
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:
<DL>
<DT><A name=strong></A><A name=*strong*></A>*<CODE>strong</CODE>*
<DD>
Translates into strong.
<DT><A name=_emphasis_></A><CODE>_emphasis_</CODE>
<DD>
Translates into emphasis.
<DT><A name=bold></A><A name=**bold**></A>**<CODE>bold</CODE>**
<DD>
Translates into bold.
<DT><A name=__italics__></A><CODE>__italics__</CODE>
<DD>
Translates into italics.
<DT><A name=bigger></A><A name=++bigger++></A><CODE>++bigger++</CODE>
<DD>
Translates into <big>bigger</big>.
<DT><A name=smaller></A><A name=--smaller--></A><CODE>--smaller--</CODE>
<DD>
Translates into: smaller.
<DT><A name=deleted></A><A name=-deleted_text-></A><CODE>-deleted text-</CODE>

<DD>
Translates into <del>deleted text</del>.
<DT><A name=inserted></A><A name=+inserted_text+></A><CODE>+inserted
text+</CODE>
<DD>
Translates into <ins>inserted text</ins>.
<DT><A name=superscript></A><A
name=^superscript^></A><CODE>^superscript^</CODE>
<DD>
Translates into superscript.
<DT><A name=subscript></A><A name=~subscript~></A><CODE>~subscript~</CODE>
<DD>
Translates into subscript.
<DT><A name=span></A><A name=%span%></A><CODE>%span%</CODE>
<DD>
Translates into span.
<DT><A name=code></A><A name=@code@></A><CODE>@code@</CODE>
<DD>
Translates into <code>code</code>. Note that within a '@...@'
section, < and > are translated into HTML entities
automatically.</DD></DL>
Inline formatting operators accept the following modifiers:
<DL>
<DT><A name=style></A><A name={style_rule}></A><CODE>{style rule}</CODE>
<DD>
A CSS style rule.
<DT><A name=ll></A><A name=[ll]></A><CODE>[ll]</CODE>
<DD>
A language identifier (for a "lang" attribute).
<DT><A name=class></A><A
name=(class)_or_(#id)_or_(class#id)></A><CODE>(class)</CODE> or
<CODE>(#id)</CODE> or <CODE>(class#id)</CODE>
<DD>
For CSS class and id attributes.</DD></DL>
Examples<PRE> Textile is *way* cool.

Textile is *_way_* cool.</PRE>
Now this won't work, because the formatting characters need whitespace before
and after to be properly recognized.<PRE> Textile is way c*oo*l.</PRE>
However, you can supply braces or brackets to further clarify that you want
to format, so this would work:<PRE> Textile is way c[*oo*]l.</PRE>
<H2><A name=Footnotes></A>Footnotes</H2>
You can create footnotes like this:<PRE> And then he went on a long trip[1].</PRE>
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:<PRE> And then he went on a long
trip<a href="#fn1">1</a></PRE>
To supply the content of the footnote, place it at the end of your document
using a "fn" block signature:<PRE> fn1. And there was much rejoicing.</PRE>
Which creates a paragraph that looks like this:<PRE> 1 And there was
much rejoicing.</PRE>
<H2><A name=Links></A>Links</H2>
Textile defines a shorthand for formatting hyperlinks. The format looks like
this:<PRE> "Text to display":<A href="http://example.com/">http://example.com/</A></PRE>
In addition to this, you can add 'title' text to your link:<PRE> "Text to display (Title text)":<A href="http://example.com/">http://example.com/</A></PRE>
The URL portion of the link supports relative paths as well as other
protocols like ftp, mailto, news, telnet, etc.<PRE> "E-mail me please":mailto:someone@example.com</PRE>
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:<PRE> You["gotta":<A href="http://example.com]seethis/">http://example.com]seethis/</A>!</PRE>
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):<PRE> [excom]<A href="http://example.com/">http://example.com/</A>
[exorg]<A href="http://example.org/">http://example.org/</A></PRE>
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:<PRE> "Text to display":excom</PRE>
Once you've defined your link lookup table, you can use the identifiers any
number of times.
<H2><A name=Images></A>Images</H2>
Images are identified by the following pattern:<PRE> !/path/to/image!</PRE>
Image attributes may also be specified:<PRE> !/path/to/image 10x20!</PRE>
Which will render an image 10 pixels wide and 20 pixels high. Another way to
indicate width and height:<PRE> !/path/to/image 10w 20h!</PRE>
You may also redimension the image using a percentage.<PRE> !/path/to/image 20%x40%!</PRE>
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:<PRE> !/path/to/image 20%!</PRE>
Alt text can be given as well:<PRE> !/path/to/image (Alt text)!</PRE>
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:
<DL>
<DT><A name="<"></A><CODE><</CODE>
<DD>
Align the image to the left (causes the image to float if CSS options are
enabled).
<DT><A name=">"></A><CODE>></CODE>
<DD>
Align the image to the right (causes the image to float if CSS options are
enabled).
<DT><A name=dash></A><A name=-_(dash)></A><CODE>-</CODE> (dash)
<DD>
Aligns the image to the middle.
<DT><A name=^></A><CODE>^</CODE>
<DD>
Aligns the image to the top.
<DT><A name=tilde></A><A name=~_(tilde)></A><CODE>~</CODE> (tilde)
<DD>
Aligns the image to the bottom.
<DT><A name=style></A><A name={style_rule}></A><CODE>{style rule}</CODE>
<DD>
Applies a CSS style rule to the image.
<DT><A name=class></A><A
name=(class)_or_(#id)_or_(class#id)></A><CODE>(class)</CODE> or
<CODE>(#id)</CODE> or <CODE>(class#id)</CODE>
<DD>
Applies a CSS class and/or id to the image.
<DT><A name=one></A><A name=(_(one_or_more)></A><CODE>(</CODE> (one or more)
<DD>
Pads 1em on the left for each '(' character.
<DT><A name=one></A><A name=)_(one_or_more)></A><CODE>)</CODE> (one or more)
<DD>
Pads 1em on the right for each ')' character.</DD></DL>
<H2><A name=Character_Replacements></A>Character Replacements</H2>
A few simple, common symbols are automatically replaced:<PRE> (c)
(r)
(tm)</PRE>
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:<PRE> {c|} or {|c} cent sign
{L-} or {-L} pound sign
{Y=} or {=Y} yen sign</PRE>
Many of these macros can be guessed. For example:<PRE> {A'} or {'A}
{a"} or {"a}
{1/4}
{*}
{:)}
{:(}</PRE>
<H2><A name=Lists></A>Lists</H2>
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:<PRE> * one
* two
* three</PRE>
Multi-level lists:<PRE> * one
** one A
** one B
*** one B1
* two
** two A
** two B
* three</PRE>
Ordered lists:<PRE> # one
# two
# three</PRE>
Styling lists:<PRE> (class#id)* one
* two
* three</PRE>
The above sets the class and id attributes for the <ul> tag.<PRE> *(class#id) one
* two
* three</PRE>
The above sets the class and id attributes for the first <li> tag.
Definition lists:<PRE> dl. textile:a cloth, especially one manufactured by weaving
or knitting; a fabric
format:the arrangement of data for storage or display.</PRE>
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).
<H2><A name=Tables></A>Tables</H2>
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:<PRE> |a|b|c|
|1|2|3|</PRE>
To the complex:<PRE> table(fig). {color:red}_|Top|Row|
{color:blue}|/2. Second|Row|
|_{color:green}. Last|</PRE>
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:
<DL>
<DT><A name=style></A><A name={style_rule}></A><CODE>{style rule}</CODE>
<DD>
A CSS style rule.
<DT><A name=class></A><A
name=(class)_or_(#id)_or_(class#id)></A><CODE>(class)</CODE> or
<CODE>(#id)</CODE> or <CODE>(class#id)</CODE>
<DD>
A CSS class and/or id attribute.
<DT><A name=one></A><A name=(_(one_or_more)></A><CODE>(</CODE> (one or more)
<DD>
Adds 1em of padding to the left for each '(' character.
<DT><A name=one></A><A name=)_(one_or_more)></A><CODE>)</CODE> (one or more)
<DD>
Adds 1em of padding to the right for each ')' character.
<DT><A name="<"></A><CODE><</CODE>
<DD>
Aligns to the left (floats to left for tables if combined with the ')'
modifier).
<DT><A name=">"></A><CODE>></CODE>
<DD>
Aligns to the right (floats to right for tables if combined with the '('
modifier).
<DT><A name==></A><CODE>=</CODE>
<DD>
Aligns to center (sets left, right margins to 'auto' for tables).
<DT><A name="<>"></A><CODE><></CODE>
<DD>
For cells only. Justifies text.
<DT><A name=^></A><CODE>^</CODE>
<DD>
For rows and cells only. Aligns to the top.
<DT><A name=tilde></A><A name=~_(tilde)></A><CODE>~</CODE> (tilde)
<DD>
For rows and cells only. Aligns to the bottom.
<DT><A name=_></A><A name=__(underscore)></A><CODE>_</CODE> (underscore)
<DD>
Can be applied to a table row or cell to indicate a header row or cell.
<DT><A name=2></A><A name=\2_or_\3_or_\4,_etc.></A><CODE>\2</CODE> or
<CODE>\3</CODE> or <CODE>\4</CODE>, etc.
<DD>
Used within cells to indicate a colspan of 2, 3, 4, etc. columns. When you
see "\", think "push forward".
<DT><A name=2></A><A name=/2_or_/3_or_/4,_etc.></A><CODE>/2</CODE> or
<CODE>/3</CODE> or <CODE>/4</CODE>, etc.
<DD>
Used within cells to indicate a rowspan or 2, 3, 4, etc. rows. When you see
"/", think "push downward".</DD></DL>
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.
<H2><A name=CSS_Notes></A>CSS Notes</H2>
When CSS is enabled (and it is by default), CSS class names are automatically
applied in certain situations.
<DL>
<DT><A name=Aligning></A><A
name=Aligning_a_block_or_span_or_other_element_to_left,_right,_etc.></A>Aligning
a block or span or other element to left, right, etc.

<DD>
"left" for left justified, "right" for right justified, "center" for
centered text, "justify" for full-justified text.
<DT><A name=Aligning></A><A
name=Aligning_an_image_to_the_top_or_bottom></A>Aligning an image to the top
or bottom
<DD>
"top" for top alignment, "bottom" for bottom alignment, "middle" for middle
alignment.
<DT><A name=Footnotes></A>Footnotes
<DD>
"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.
<DT><A name=Capped></A><A name=Capped_text></A>Capped text
<DD>
For a series of characters that are uppercased, a span is placed around
them with a class of "caps".</DD></DL>
<H2><A name=Miscellaneous></A>Miscellaneous</H2>
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.

Lewiki uses the Perl module Text::Textile, which was written by Brad Choate, brad@bradchoate.com. It is an adaptation of Textile, developed by Dean Allen of <a href="http://www.textism.com/">Textism.com</a>.

 
 

<h2>Document fragment linking</h2>


The following feature doc is from http://instiki.org/show/Textile.



This was used to set up the link list at the top of this page. It doesn’t appear to be documented anywhere – inluding either http://hobix.com/textile/quick.html or http://textism.com/tools/textile/ – and it’s very handy for writers who need to link from one place in a document to another part of the same document.



Footnote creation and linking is a similar idea, but it’s done differently from the method shown here, and isn’t really equivalent.



Here’s how to do it:



Do this:



This is a "link from here":#to_here



h4(#to_here). To here



…to get this:



This is a link from here



To here



One can link to a header, but also to a paragraph, like so (showing only the anchor):



p(#anchor). Paragraph text


==

h2. Working Examples

==

table.
|{background:#f8eaba;border:1px solid #ccc;width:45%;padding:5px;vertical-align:top;}. {For Toledo Wi-Fi}|{background:#ffdddd;border:1px solid #ccc;width:45%;align:top;padding:5px;verticle-align:top;}. {Against Toledo Wi-Fi}|.

==

produces "this":http://www.toledotalk.com/cgi-bin/lewiki.pl/article/1437/Toledo_Wi-Fi_Debate

br.
table{border:1px solid black; width: 500px;}.
| |\4=. *Number of Servings*|
| |3|6|9|12|
|*Ingredients*|\4=. *Number of Shots*|
|Cuervo Gold Tequila| 2| 4| 6| 8|
|Cointreau| 0.75| 1.5| 2.25| 3|
|Grand Marnier| 0.75| 1.5| 2.25| 3|
|Sweet & Sour Mix| 6| 12| 18| 24|
|Rose's Lime| 1 Splash| 2 Splashes| 3 Splashes| 4 Splashes|

produces "this":http://www.toledotalk.com/cgi-bin/lewiki.pl/article/1605/Jr_recipes#Margaritas

edit=no