This document describes all the details about each txt2tags mark. The target audience are experienced users. You may find it useful if you want to master the marks or solve a specific problem about a mark.

If you are new to txt2tags or just want to know which are the available marks, please read the Markup Demo.

Note 1: This document is generated directly from the txt2tags test-suite. All the rules mentioned here are 100% in sync with the current program code.

Note 2: A good practice is to consult the sources when reading, to see how the texts were made.

Table of Contents:

Paragraph
Comment
Line
Inline
Link
Image
Macro
Numbered Title
Title
- Syntax: Balanced equal signs (from 1 to 5)

Label: Between brackets, alphanumeric [A-Za-z0-9_-]

Syntax: Spaces around and/or inside are allowed (and ignored)
Invalid: Unbalanced equal signs
Invalid: Level deeper than 5
Invalid: Space between title and label
Invalid: Space inside label
Invalid: Strange chars inside label

Quote
Raw
Tagged
Verbatim
Definition List
Numbered List
List
Table

Paragraph

Syntax: Lines grouped together

A paragraph is composed by one or more lines. A blank line (or a table, or a list) ends the current paragraph.

Syntax: Leading and trailing spaces are ignored

Leading and trailing spaces are ignored.

Syntax: A comment don't close a paragraph

A comment line can be placed inside a paragraph. It will not affect it.

Closing: EOF closes the open paragraph

The end of the file (EOF) closes the currently open paragraph.

Comment

Syntax: The % character at the line beginning (column 1)

Syntax: Area (block)

Syntax: Area (block) with trailing spaces

Invalid: The % in any other position

% not on the line beginning (at column 2)

some text % half line comments are not allowed

Line

Syntax: At least 20 chars of - = _

Syntax: Any kind of mixing is allowed

Free mixing is allowed to make the line, but the first char is the identifier for the difference between separator ( - _ ) and strong ( = ) lines.

Syntax: Leading and/or trailing spaces are allowed

Invalid: Less than 20 chars (but strike matches)

~~-----~~

Invalid: Strange chars (but strike matches)

~~-----~~ ~~------~~

~~-----~~+~~------~~

( ~~----------------~~ )

Inline

Syntax: Marks are greedy and must be "glued" with contents

GLUED: The contents must be glued with the marks, no spaces between them. Right after the opening mark there must be a non-blank character, as well as right before the closing mark.

GREEDY: If the contents boundary character is the same as the mark character, it is considered contents, not mark. So ****bold**** turns to <B>**bold**</B> in HTML.

{ b }{ i }{ u }{ s }{ m }{ r }{ t }
{ bo }{ it }{ un }{ st }{ mo }{ ra }{ tg }
{ bold }{ ital }{ undr }{ ~~strk~~ }{ mono }{ raw }{ tggd }
{ bo ld }{ it al }{ un dr }{ ~~st rk~~ }{ mo no }{ r aw }{ tg gd }
{ bo * ld }{ it / al }{ un _ dr }{ ~~st - rk~~ }{ mo ` no }{ r " aw }{ tg ' gd }
{ bo **ld }{ it //al }{ un __dr }{ ~~st --rk~~ }{ mo ``no }{ r ""aw }{ tg ''gd }
{ bo ** ld }{ it // al }{ un __ dr }{ ~~st -- rk~~ }{ mo `` no }{ r "" aw }{ tg '' gd }
{ **bold** }{ //ital// }{ __undr__ }{ ~~--strk--~~ }{ ``mono`` }{ ""raw"" }{ ''tggd'' }
{ *bold* }{ /ital/ }{ _undr_ }{ ~~-strk-~~ }{ `mono` }{ "raw" }{ 'tggd' }

Syntax: Repetition is greedy

When the mark character is repeated many times, the contents are expanded to the largest possible. Thats why they are greedy, the outer marks are the ones used.

{ * }{ / }{ _ }{ - }{ ` }{ " }{ ' }
{ ** }{ // }{ __ }{ -- }{ `` }{ "" }{ '' }
{ *** }{ /// }{ ___ }{ ~~---~~ }{ ``` }{ """ }{ ''' }
{ **** }{ //// }{ ____ }{ ~~----~~ }{ ```` }{ """" }{ '''' }
{ ***** }{ ///// }{ _____ }{ ~~-----~~ }{ ````` }{ """"" }{ ''''' }
{ ****** }{ ////// }{ ______ }{ ~~------~~ }{ `````` }{ """""" }{ '''''' }

Invalid: No contents

{ **** }{ //// }{ ____ }{ ---- }{ ```` }{ """" }{ '''' }
{ ** ** }{ // // }{ __ __ }{ -- -- }{ `` `` }{ "" "" }{ '' '' }

Invalid: Contents not "glued" with marks

Spaces between the marks and the contents in any side invalidate the mark.

{ ** bold** }{ // ital// }{ __ undr__ }{ -- strk-- }{ `` mono`` }{ "" raw"" }{ '' tggd'' }
{ **bold ** }{ //ital // }{ __undr __ }{ --strk -- }{ ``mono `` }{ ""raw "" }{ ''tggd '' }
{ ** bold ** }{ // ital // }{ __ undr __ }{ -- strk -- }{ `` mono `` }{ "" raw "" }{ '' tggd '' }

Link

Syntax: E-mail

user@domain.com
user@domain.com.
user@domain.com. any text.
any text: user@domain.com. any text.
label

Syntax: E-mail with form data

user@domain.com?subject=bla
user@domain.com?subject=bla.
user@domain.com?subject=bla,
user@domain.com?subject=bla&cc=otheruser@domain.com
user@domain.com?subject=bla&cc=otheruser@domain.com.
user@domain.com?subject=bla&cc=otheruser@domain.com,
label.
label.

Syntax: URL

http://www.domain.com
http://www.domain.com/dir/
http://www.domain.com/dir///
http://www.domain.com.
http://www.domain.com,
http://www.domain.com. any text.
http://www.domain.com, any text.
http://www.domain.com/dir/. any text.
any text: http://www.domain.com. any text.
any text: http://www.domain.com/dir/. any text.
any text: http://www.domain.com/dir/index.html. any text.
any text: http://www.domain.com/dir/index.html, any text.

Syntax: URL with anchor

http://www.domain.com/dir/#anchor
http://www.domain.com/dir/index.html#anchor
http://www.domain.com/dir/index.html#anchor.
http://www.domain.com/dir/#anchor. any text.
http://www.domain.com/dir/index.html#anchor. any text.
any text: http://www.domain.com/dir/#anchor. any text.
any text: http://www.domain.com/dir/index.html#anchor. any text.

Syntax: URL with form data

http://domain.com?a=a@a.a&b=a+b+c.
http://domain.com?a=a@a.a&b=a+b+c,
http://domain.com/bla.cgi?a=a@a.a&b=a+b+c.
http://domain.com/bla.cgi?a=a@a.a&b=a+b+c@.

Syntax: URL with form data and anchor

http://domain.com?a=a@a.a&b=a+b+c.#anchor
http://domain.com/bla.cgi?a=a@a.a&b=a+b+c.#anchor
http://domain.com/bla.cgi?a=a@a.a&b=a+b+c@.#anchor

Syntax: URL with login data

http://user:password@domain.com/bla.html.
http://user:password@domain.com/dir/.
http://user:password@domain.com.
http://user:@domain.com.
http://user@domain.com.

Syntax: URL with login, form and anchor

http://user:password@domain.com/bla.cgi?a=a@a.a&b=a+b+c.#anchor
http://user:password@domain.com/bla.cgi?a=a@a.a&b=a+b+c@#anchor

Syntax: URL with label

label

Syntax: URL with label (trailing spaces are discarded, leading are maintained)

label
label

Syntax: URL with label, stressing

anchor
login
form
form & anchor
login & form

Syntax: Link with label for local files

local link up
local link file
local link anchor
local link file/anchor
local link file/anchor
local link img

Syntax: Another link as a label

www.fake.com

Syntax: URL with funny chars

http://domain.com:8080/~user/_st-r@a=n$g,e/index%20new.htm
http://domain.com:8080/~user/_st-r@a=n$g,e/index%20new.htm?a=/%22&b=+.@*_-
http://domain.com:8080/~user/_st-r@a=n$g,e/index%20new.htm?a=/%22&b=+.@*_-#anchor_-1%.
http://foo._user-9:pass!#$%&*()+word@domain.com:8080/~user/_st-r@a=n$g,e/index%20new.htm?a=/%22&b=+.@*_-#anchor_-1%.

Test: Various per line

http://L1.com ! L2@www.com ! L3 ! L4 ! www.L5.com

Feature: Guessed link, adding protocol automatically

www.domain.com
www2.domain.com
ftp.domain.com
WWW.DOMAIN.COM
FTP.DOMAIN.COM
label
label
label
label

Invalid: Trailing space on link

[label www.domain.com ]

Invalid: Label with ] char (use postproc)

[label] www.domain.com]

Image

Syntax: Image name inside brackets: [img]

Syntax: Image pointing to a link: [[img] link]

Align: Image position is preserved when inside paragraph

Image at the line beginning.

Image in the middle of the line.

Image at the line end.

Align: Image alone with spaces around is aligned

Test: Two glued images with no spaces (left & right)

Test: Various per line

Images mixed with text.

Images glued together: .

Invalid: Spaces inside are not allowed

[../img/t2tpowered.png ]

[ ../img/t2tpowered.png]

[ ../img/t2tpowered.png ]

Macro

Syntax: Macro without formatting string

Date : 20081027 - 20081027
Mtime : 20081027 - 20081027
Infile : rules.t2t - rules.t2t
Outfile : rules.html - rules.html

Syntax: Macro name is case insensitive

Date : 20081027
Mtime : 20081027
Infile : rules.t2t
Outfile : rules.html

Syntax: Macro with formatting string

Date : txt 20 txt
Mtime : txt 20 txt
Infile : txt t2t txt
Outfile : txt html txt

Syntax: Leading and trailing spaces are preserved

Date : ( txt ) - ( 20 )
Mtime : ( txt ) - ( 20 )
Infile : ( txt ) - ( t2t )
Outfile : ( txt ) - ( html )

Test: Expansion of the percent char

Date : % - % - %% - %%
Mtime : % - % - %% - %%
Infile : % - % - %% - %%
Outfile : % - % - %% - %%

Test: Various per line, glued

Date : 202008102720081027
Mtime : 202008102720081027
Infile : t2trules.t2trules.t2t
Outfile : htmlrules.htmlrules.html

Test: Path formatters

Path : /a/pessoal/sourceforge.net/txt2tags/src/doc/English/rules/rules.t2t
Path : /a/pessoal/sourceforge.net/txt2tags/src/doc/English/rules.html
Dirname : /a/pessoal/sourceforge.net/txt2tags/src/doc/English/rules, rules
Dirname : /a/pessoal/sourceforge.net/txt2tags/src/doc/English, English
File : rules + t2t = rules.t2t
File : rules + html = rules.html

Numbered Title

See Title, the same rules apply.

Title

Syntax: Balanced equal signs (from 1 to 5)

Title Level 1

Title Level 2

Title Level 3

Title Level 4

Title Level 5

Label: Between brackets, alphanumeric [A-Za-z0-9_-]

Title Level 1

Title Level 2

Title Level 3

Title Level 4

Title Level 5

Syntax: Spaces around and/or inside are allowed (and ignored)

Title Level 3

Invalid: Unbalanced equal signs

=Not Title

==Not Title=

===Not Title====

Invalid: Level deeper than 5

======Not Title 6======

=======Not Title 7=======

Invalid: Space between title and label

=Not Title= [label1]

Invalid: Space inside label

=Not Title=[ label ]

Invalid: Strange chars inside label

=Not Title=[la/bel]

Quote

Syntax: TAB defines quote

To quote a paragraph, just prefix it by a TAB character. All the lines of the paragraph must begin with a TAB.

Any non-tabbed line closes the quote block.

Nesting: Creating deeper quotes

The number of leading TABs identifies the quote block depth. This is quote level 1.
With two TABs, we are on the quote level 2.
The more TABs, more deep is the quote level.
There isn't a limit.

Nesting: Reverse nesting works

This quote starts at level 4.
Then its depth is decreased.
Counting down, one by one.
Until the level 1.

Nesting: Random count

Unlike lists, any quote block is independent, not part of a tree.

The TAB count don't need to be incremental by one.

The nesting don't need to follow any rule.

Quotes can be opened and closed in any way.

You choose.

Nesting: When not supported

Some targets (as sgml) don't support the nesting of quotes. There is only one quote level.
In this case, no matter how much TABs are used to define the quote block, it always will be level 1.

Syntax: Spaces after TAB

Spaces AFTER the TAB character are allowed. But be careful, it can be confusing.

Invalid: Spaces before TAB

Spaces BEFORE the TAB character invalidate the mark. It's not quote.

Invalid: Paragraphs inside

Paragraph breaks inside a quote aren't possible.

This sample are two separated quoted paragraphs, not a quote block with two paragraphs inside.

Closing: EOF closes the open block

The end of the file (EOF) closes the currently open quote block.

Raw

See Verbatim, the same rules apply.

Tagged

See Verbatim, the same rules apply.

Verbatim

Syntax: A single line

A verbatim line.

Syntax: A single line with leading spaces

  Another verbatim line, with leading spaces.

Syntax: Area (block)

A verbatim area delimited
       by lines with marks.

Syntax: Area (block) with trailing spaces

Trailing spaces and TABs after the area marks
are allowed, but not encouraged nor documented.

Invalid: No space between mark and contents

```Not a verbatim line, need one space after mark.

Invalid: Leading spaces on block marks

``` Not a verbatim area. The marks must be at the line beginning, no leading spaces. ```

Closing: EOF closes the open block

The end of the file (EOF) closes
the currently open verbatim area.

Definition List

See List, the same rules apply.

Numbered List

See List, the same rules apply.

List

Items: Prefixed by hyphen

Use the hyphen to prefix list items.
There must be one space after the hyphen.
The list is closed by two consecutive blank lines.

Items: Free leading spacing (indentation)

The list can be indented on the source document.
You can use any number of spaces.
The result will be the same.

Items: Vertical spacing between items

Let one blank line between the list items.
It will be maintained on the conversion.
Some targets don't support this behavior.
This one was separated by a line with blanks. You can also put a blank line inside
the item contents and it will be preserved.

Items: Exactly ONE space after the hyphen

-This is not a list (no space)

- This is not a list (more than one space)

- This is not a list (a TAB instead the space)

Items: Catchy cases

- This is a list
+ This is a list
: This is a list

Nesting: Creating sublists

This is the "mother" list first item.
Here is the second, but inside this item,
- there is a sublist, with its own items.
- Note that the items of the same sublist
- must have the same indentation.
  - And this can go on, opening sublists.
    - Just add leading spaces before the
    - hyphen and sublists will be opened.
    - The two blank lines closes them all.

Nesting: Free leading spacing (indentation)

When nesting lists, the additional spaces are free.
- You can add just one,
  - or many.
    - What matters is to put more than the previous.
    - But remember that the other items of the same list
    - must use the same indentation.

Nesting: Maximum depth

There is not a depth limit,
- you can go deeper and deeper.
  - But some targets may have restrictions.
    - The LaTeX maximum is here, 4 levels.
      - This one and the following sublists
        
        are moved up to the level 4
        
        when converting to LaTeX.
        
        On the other targets,
        
        it is just fine
        
        to have a very deep list.

Nesting: Reverse doesn't work

Reverse nesting doesn't work.

Because a sublist *must* have a mother list.

It's the list concept, not a txt2tags limitation.

All this sublists will be bumped to mother lists.

At level 1, like this one.

Nesting: Going deeper and back

When nesting back to an upper level, the previous sublist is automatically closed.

Level 1
- Level 2
  - Level 3
    - Level 4
  - Level 3 -- (closed Level 4)
- Level 2 -- (closed Level 3)
Level 1 -- (closed Level 2)

More than one list can be closed when nesting back.

Level 1
- Level 2
  - Level 3
    - Level 4
Level 1 -- (closed Level 4, Level 3 and Level 2)

Nesting: Vertical spacing between lists

Level 1
- Level 2 -- blank BEFORE and AFTER (in)
  - Level 3
    - Level 4
  - Level 3
- Level 2 -- blank BEFORE and AFTER (out)
Level 1
- Level 2 -- blank BEFORE (spaces) and AFTER (TAB)
  - Level 3

Nesting: Messing up

Be careful when going back on the nesting, it must be on a valid level! If not, it will be bumped up to the previous valid level.

Level 1
- Level 2
  - Level 3
    - Level 4
  - Level 3.5 ???
  - Level 3
- Level 2.5 ???
- Level 2
Level 1.5 ???
Level 1

Closing: Two (not so) empty lines

This list is closed by a line with spaces and other with TABs

This list is NOT closed by two comment lines
This list is closed by a line with spaces and TAB,
then a comment line, then an empty line.

Closing: Empty item closes current (sub)list

The two blank lines closes ALL the lists. To close just the current, use an empty item.

Level 1
- Level 2
  - Level 3
  Level 2
Level 1

The empty item can have trailing blanks.

Empty item with trailing spaces.

Empty item with trailing TAB.

Closing: EOF closes the lists

If the end of the file (EOF) is hit,
- all the currently opened list are closed,
  - just like when using the two blank lines.

Table

Syntax: Lines starting with a pipe |

Cell 1

Syntax: Extra pipes separate cells

Cell 1

Cell 2

Cell 3

Syntax: With a trailing pipe, make border

Cell 1

Cell 2

Cell 3

Syntax: Table lines starting with double pipe are heading

Cell 1	Cell 2	Cell 3

Align: Spaces before the leading pipe centralize the table

Cell 1

Cell 2

Cell 3

Align: Spaces inside the cell denote its alignment

Heading	Heading	Heading
<-	--	->
--	--	--
->	--	<-

Span: Column span is defined by extra pipes at cell closing

1	2	3+4
1	2	3	4
1+2+3			4
1	2+3		4
1+2+3+4

Test: Empty cells are placed as expected

0	1	2
4	5		7
8		A	B
	D	E	F

Test: Lines with different number of cells

1
1	2
1	2	3
1	2	3	4
1	2	3	4	5

Test: Empty cells + Span + Messy cell number = Fun!

Jan
Fev
Mar
Apr
May
20%	40%	60%	80%	100%

		/
	/ / / / /
/ / / / / / / / /
	o		o
		.
	= = = =

01	02			05		07
		11		13			16
17		19	20			23
25	26			29	30		32
		35		37		39	40

Test: Lots of cells at the same line

Test: Empty lines

Invalid: There must be at least one space around the pipe

|this|is|not|a|table|

|this| is| not| a| table|

|this |is |not |a |table |

Invalid: You must use spaces, not TABs

| this | is | not | a | table |

The End.

Txt2tags Markup Rules

Paragraph

Syntax: Lines grouped together

Syntax: Leading and trailing spaces are ignored

Syntax: A comment don't close a paragraph

Closing: EOF closes the open paragraph

Comment

Syntax: The % character at the line beginning (column 1)

Syntax: Area (block)

Syntax: Area (block) with trailing spaces

Invalid: The % in any other position

Line

Syntax: At least 20 chars of - = _

Syntax: Any kind of mixing is allowed

Syntax: Leading and/or trailing spaces are allowed

Invalid: Less than 20 chars (but strike matches)

Invalid: Strange chars (but strike matches)

Inline

Syntax: Marks are greedy and must be "glued" with contents

Syntax: Repetition is greedy

Invalid: No contents

Invalid: Contents not "glued" with marks

Link

Syntax: E-mail

Syntax: E-mail with form data

Syntax: URL

Syntax: URL with anchor

Syntax: URL with form data

Syntax: URL with form data and anchor

Syntax: URL with login data

Syntax: URL with login, form and anchor

Syntax: URL with label

Syntax: URL with label (trailing spaces are discarded, leading are maintained)

Syntax: URL with label, stressing

Syntax: Link with label for local files

Syntax: Another link as a label

Syntax: URL with funny chars

Test: Various per line

Feature: Guessed link, adding protocol automatically

Invalid: Trailing space on link

Invalid: Label with ] char (use postproc)

Image

Syntax: Image name inside brackets: [img]

Syntax: Image pointing to a link: [[img] link]

Align: Image position is preserved when inside paragraph

Align: Image alone with spaces around is aligned

Test: Two glued images with no spaces (left & right)

Test: Various per line

Invalid: Spaces inside are not allowed

Macro

Syntax: Macro without formatting string

Syntax: Macro name is case insensitive

Syntax: Macro with formatting string

Syntax: Leading and trailing spaces are preserved

Test: Expansion of the percent char

Test: Various per line, glued

Test: Path formatters

Numbered Title

Title

Syntax: Balanced equal signs (from 1 to 5)

Title Level 1

Title Level 2

Title Level 3

Title Level 4

Title Level 5

Label: Between brackets, alphanumeric [A-Za-z0-9_-]

Title Level 1

Title Level 2

Title Level 3

Title Level 4

Title Level 5

Syntax: Spaces around and/or inside are allowed (and ignored)

Title Level 3

Title Level 3

Title Level 3

Title Level 3

Title Level 3

Title Level 3

Invalid: Unbalanced equal signs

Invalid: Level deeper than 5