# Flatiron Textile Specification

*"A specification that's as solid as iron!"*<br />
-- Autumn, again (she's still at it with the puns)

This document intends to specify clearly and simply the behavior to be expected when using flatiron, and to be an aid to writing flatiron-flavored textile documents.[^1]

This specification is **not** intended to be a full specification of textile. It assumes that you know the basics, and is primarily intended to specify certain behaviors and edge cases more clearly, and where flatiron differs from other textile implementations. The version of textile that flatiron is based around is version 2.0.0, for which a brief outline can be found archived [here](https://web.archive.org/web/20040212085707/http://www.textism.com:80/tools/textile/).

## Overview

The flatiron textile specification takes no interest in the validity of any of the other languages that may be contained within it: HTML, CSS, URL format, etc. Flatiron will simply paste any non-textile garbage you give it into the output - it's not flatiron's business what you do with that.

If you want flatiron to be kind to you and leave your HTML tags alone --for example, if your punctuation keeps being converted to fancy symbols-- you should enclose them in `==` signs or put them in a `notextile.` block to indicate flatiron should copy them as-is.

## Blocks

In general, blocks consist of a sequence of non-empty lines, terminated by an empty line. The exceptions to this are the final block in the document, which can be terminated by end of file, and extended blocks.

Flatiron has considered the possibility of allowing blocks to be nested, and has decided that this makes things too complicated, preferring to keep a shallow document structure.[^2] If you want complexity, flatiron is not for you.

## Phrase modifiers

Phrase modifiers do not need to be surrounded by spaces in order to function -- e.g. `RIP__scrip__` is valid flatiron textile for italic text. If you want to use literal underscores in your text then you could escape them something like this: `RIP==__scrip__==`.

### Deleted text

The "deleted text" modifier, typically represented by hyphens in other textile flavors e.g. `-deleted text-`, has been replaced with the hash symbol: `#deleted text#`[^3]

## Links

### Title text

The title text portion of links must *always* be preceded by a space, in order to disambiguate it from the acronym syntax. e.g.
```textile
"Sourcehut page (Sourcehut is much better than github)":(https://git.sr.ht/~autumnull/flatiron)
```

This preceding space will not be rendered in the link text. If for some reason you do want a space included at the end of the link text, just put 2 spaces before the title text.

### Escaping

Link text may contain double quotes and parentheses, if they are escaped using a backslash, e.g.
```textile
"Earvin \"Magic\" Johnson \(Basketball Player\)":https://en.wikipedia.org/wiki/Magic_Johnson
```
is a link with quotes in the link text. The quotes in the link text will still be converted to curly quotes.

Similarly, the title text for the link may also contain parentheses, as long as they are escaped with backslashes.

### Links followed by text

Links can be directly followed by text if they are placed within parentheses, e.g.
```textile
Have you seen "this":(https://git.sr.ht/~autumnull/flatiron)?
```
will be parsed as a link followed by a question mark. When using parentheses in this way, any parentheses within the URL itself should be escaped using backslashes.

## Punctuation

- `"quotes"` → `“quotes”`
- `'quotes'` → `‘quotes’`
- `it's` → `it’s`
- `em -- dash` → `em — dash`
- `en - dash` → `en – dash`
- `2 x 4` → `2 × 4`
- `foo(tm)` → `foo™`
- `foo(r)` → `foo®`
- `foo(c)` → `foo©`

## Attributes

Attributes `(class#id)` `{style}` `[language]` may appear in any order. Any brackets, braces or parentheses that appear within these must be escaped with backslashes if they are of the same kind as the containing section, e.g. any curly braces appearing in the `style` portion must be replaced with `\{` and `\}`.

## Alignment and Indentation

Alignment and indentation modifiers may appear in either order in the block modifier, e.g. `p))>. ` is equivalent to `p>)). `, but these are not the same as `p)>). `, which is not a valid block modifier.

Indentation modifiers must appear in "left-then-right" order, e.g. `p(). ` is valid, but `p)(. ` is not.

Alignment and indentation must always come after attributes[^4]:
```
p(greeting){color:green}[fr]()>. Salut!
```

### Alignment

Flatiron has some opinions about alignment.[^5]

#### Aligning text

The valid alignment options for text, and the properties they add to the tag's `style` attribute:

- `<` - `text-align: left;`
- `>` - `text-align: right;`
- `=` - `text-align: center;`
- `<>` - `text-align: justify`

#### Aligning Images

The valid alignment options for images, and the properties they add to the tag's `style` attribute:

- `<` - `float: left;`
- `>` - `float: right;`
- `=` - `display: block; margin: auto;`

## Images

Image URLs may contain exclamation marks and parentheses, but they must be escaped with backslashes.

The alt text for images may also contain parentheses, but again, they must be escaped with backslashes.

## Acronyms

Acronym text may contain parentheses as long as they are escaped. e.g.
```textile
PHP(PHP: Hypertext Preprocessor \(originally Personal Home Page\))
```

Acronyms may be of the form `ABC` or `A.B.C.`, but must contain at least 2 letters in order to be recognised as an acronym. They must also be preceded and followed by either a non-alphanumeric character or the start/end of a phrase.

## Code and Preformatted Text

Flatiron will HTML-escape any instance of `<`, `>`, or `&` that shows up in inline code, block code, or preformatted text blocks.[^6] It will also ignore any textile that is used in those contexts.

## Extended blocks

### Extended blocks containing textile

By default, textile's "extended block" syntax makes it very difficult to write code blocks that contain textile, since it means that you cannot put any textile block modifiers into your code block, as they will end the extended block. Thus flatiron uses a special syntax to communicate extended blocks that may contain textile:

If you want to include literal text that would otherwise render as textile within a block, then you should preface every subsequent line in the block with a vertical bar `|`.

For example, the following is a valid flatiron textile block:
```textile
bc. This is supposed to be a block of textile code.
|
|bq. Textile should really have a closing delimiter for blocks.
|--Autumn
|
|Here's some textile code within the textile code:
|
|bc.
||bq. This is getting out of hand... now there are two of them!
||--Nute Gunray
|
|Now some more text within the code block
```

The above block, when rendered, will produce the following output:

```html
<pre><code>This is supposed to be a block of textile code.

bq. Textile should really have a closing delimiter for blocks.
--Autumn

Here's some textile code within the textile code:

bc.
|bq. This is getting out of hand... now there are two of them!
|--Nute Gunray

Now some more text within the code block</code></pre>
```

## Raw (No Textile)

### Raw phrases containing equals signs

Raw phrases, e.g. `==no **textile**==` can contain double equals signs, as long as they are escaped using a backslash. e.g.
```textile
==This is two equals signs: \== here are two more: \====
```
will be rendered as
```
<p>This is two equals signs: == here are two more: ==</p>
```
## Raw sections and paragraphs

A raw phrase comprising an entire block will be interpreted as being implicitly within a paragraph. e.g.
```
Here is some paragraph text.

==This is *not* supposed to be read as textile!!==

This is some more paragraph text
```
will be rendered as
```
<p>Here is some paragraph text.</p>
<p>This is *not* supposed to be read as textile!!</p>
<p>This is some more paragraph text</p>
```

On the other hand, a `notextile. ` block will never be placed within paragraph tags, and will be copied straight into the output. e.g.
```
Here is some paragraph text.

notextile. This is *not* supposed to be read as textile!!

This is some more paragraph text
```
will be rendered as
```
<p>Here is some paragraph text.</p>
This is *not* supposed to be read as textile!!
<p>This is some more paragraph text</p>
```

[^1]: Delicious!

[^2]: Flatirons prefer flat textiles 🙂 (Listen you're lucky you even get nested lists, those things were gross to implement)

[^3]: This decision was made in order to avoid collision with hyphens in regular text, since flatiron textile no longer requires that phrase modifiers be surrounded by spaces. The other phrase modifiers were not deemed to be common enough in regular text to warrant replacing.

[^4]: This is so that the braces in the indentation modifier can be distinguished from those in the class/id modifier more easily.

[^5]: In particular, flatiron believes that alignment is fundamentally an element of *style* rather than *structure*, and as such belongs in CSS, not HTML. However, given that alignment in textile is contained inline within the markup, it seems most sensible to also make it inline within the HTML. Flatiron thus uses the inline `style` attribute on tags in order to apply alignment, rather than outsourcing that to external CSS or using HTML attributes. This means that the HTML outputted by flatiron will be self-contained, while keeping a healthy distinction between style and structure. I'm sure you understand x

[^6]: This is so that you don't have to escape any characters in your code that might otherwise render as HTML. Yes this does mean that you can't put literal HTML tags in your preformatted text and expect them to be kept in the output -- you should not do this. That's weird. Cut it out.