Txt2tags Markup Rules

author

date

%!includeconf: rules.conf

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 MARKUPDEMO].

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 rules.t2t] when

reading, to see how the texts were made.

Table of Contents:

%%TOC

-------------------------------------------------------------

= Paragraph =[paragraph]

%INCLUDED(t2t) starts here: ../../../test/marks/paragraph.t2t

%%% 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.

% this comment will be ignored

It will not affect it.

%%% Closing: EOF closes the open paragraph

The end of the file (EOF) closes the

currently open paragraph.

= Comment =[comment]

%INCLUDED(t2t) starts here: ../../../test/marks/comment.t2t

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

%glued with the % mark

% separated from the % mark

% very distant from the % mark

%%%%%%% lots of % marks

% a blank comment, used for vertical spacing:

%

% NOTE: what matters is the first % being at the line beginning,

% the rest of the line is just ignored.

%%% Syntax: Area (block)

%%%

You're not seeing this.

%%%

%%% Syntax: Area (block) with trailing spaces

%%%

You're not seeing this.

%%%

%%% Invalid: The % in any other position

% not on the line beginning (at column 2)

some text % half line comments are not allowed

= Line =[line]

%INCLUDED(t2t) starts here: ../../../test/marks/line.t2t

%%% 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 =[inline]

%INCLUDED(t2t) starts here: ../../../test/marks/inline.t2t

%%% 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.

i) **b** //i// __u__ --s-- ``m`` ""r"" ''t''

i) **bo** //it// __un__ --st-- ``mo`` ""ra"" ''tg''

i) **bold** //ital// __undr__ --strk-- ``mono`` ""raw"" ''tggd''

i) **bo ld** //it al// __un dr__ --st rk-- ``mo no`` ""r aw"" ''tg gd''

i) **bo * ld** //it / al// __un _ dr__ --st - rk-- ``mo ` no`` ""r " aw"" ''tg ' gd''

i) **bo **ld** //it //al// __un __dr__ --st --rk-- ``mo ``no`` ""r ""aw"" ''tg ''gd''

i) **bo ** ld** //it // al// __un __ dr__ --st -- rk-- ``mo `` no`` ""r "" aw"" ''tg '' gd''

i) ****bold**** ////ital//// ____undr____ ----strk---- ````mono```` """"raw"""" ''''tggd''''

i) ***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.

i) ***** ///// _____ ----- ````` """"" '''''

i) ****** ////// ______ ------ `````` """""" ''''''

i) ******* /////// _______ ------- ``````` """"""" '''''''

i) ******** //////// ________ -------- ```````` """""""" ''''''''

i) ********* ///////// _________ --------- ````````` """"""""" '''''''''

i) ********** ////////// __________ ---------- `````````` """""""""" ''''''''''

%%% Invalid: No contents

i) **** //// ____ ---- ```` """" ''''

i) ** ** // // __ __ -- -- `` `` "" "" '' ''

%%% Invalid: Contents not "glued" with marks

%% Spaces between the marks and the contents in any side

%% invalidate the mark.

i) ** bold** // ital// __ undr__ -- strk-- `` mono`` "" raw"" '' tggd''

i) **bold ** //ital // __undr __ --strk -- ``mono `` ""raw "" ''tggd ''

i) ** bold ** // ital // __ undr __ -- strk -- `` mono `` "" raw "" '' tggd ''

= Link =[link]

%INCLUDED(t2t) starts here: ../../../test/marks/link.t2t

%%% Syntax: E-mail

user@domain.com

user@domain.com.

user@domain.com. any text.

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

[label user@domain.com]

%%% 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 user@domain.com?subject=bla&cc=otheruser@domain.com].

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

%%% 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 www.domain.com]

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

%TODO normalize this behavior

[ label www.domain.com]

[label www.domain.com]

%%% Syntax: URL with label, stressing

[anchor http://www.domain.com/dir/index.html#anchor.]

[login http://user:password@domain.com/bla.html]

[form http://www.domain.com/bla.cgi?a=a@a.a&b=a+b+c.]

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

[login & form http://user:password@domain.com/bla.cgi?a=a@a.a&b=a+b+c.]

%%% Syntax: Link with label for local files

[local link up ..]

[local link file bla.html]

[local link anchor #anchor]

[local link file/anchor bla.html#anchor]

[local link file/anchor bla.html#anchor.]

[local link img abc.gif]

%%% Syntax: Another link as a label

[www.fake.com www.domain.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 www.com] ! [L4 w@ww.com] ! 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 www.domain.com]

[label ftp.domain.com]

[label WWW.DOMAIN.COM]

[label FTP.DOMAIN.COM]

%%% Invalid: Trailing space on link

[label www.domain.com ]

%%% Invalid: Label with ] char (use postproc)

[label] www.domain.com]

= Image =[image]

%INCLUDED(t2t) starts here: ../../../test/marks/image.t2t

%%% Syntax: Image name inside brackets: [img]

[img.png]

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

[[img.png] http://txt2tags.org]

%%% Align: Image position is preserved when inside paragraph

[img.png] Image at the line beginning.

Image in the middle [img.png] of the line.

Image at the line end. [img.png]

%%% Align: Image alone with spaces around is aligned

[img.png]

[img.png]

[img.png]

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

[img.png][img.png]

%%% Test: Various per line

Images [img.png] mixed [img.png] with [img.png] text.

Images glued together: [img.png][img.png][img.png].

%%% Invalid: Spaces inside are not allowed

[img.png ]

[ img.png]

[ img.png ]

% Ignored as they change every time when run

= Numbered Title =[numtitle]

%%% 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 +[lab_el-1]

++ Title Level 2 ++[lab_el-2]

+++ Title Level 3 +++[lab_el-3]

++++ Title Level 4 ++++[lab_el-4]

+++++ Title Level 5 +++++[lab_el-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 +++[lab_el-9]

%%% 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]

= Title =[title]

%INCLUDED(t2t) starts here: ../../../test/marks/title.t2t

%%% 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 =[lab_el-1]

== Title Level 2 ==[lab_el-2]

=== Title Level 3 ===[lab_el-3]

==== Title Level 4 ====[lab_el-4]

===== Title Level 5 =====[lab_el-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 ===[lab_el-9]

%%% 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 =[quote]

%INCLUDED(t2t) starts here: ../../../test/marks/quote.t2t

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 =[raw]

%%% Syntax: A single line

""" A raw line.

%%% Syntax: A single line with leading spaces

""" Another raw line, with leading spaces.

%%% Syntax: Area (block)

"""

A raw 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 raw line, need one space after mark.

%%% Invalid: Leading spaces on block marks

"""

Not a raw 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 raw area.

"""

= Verbatim =[verbatim]

%INCLUDED(t2t) starts here: ../../../test/marks/verbatim.t2t

%%% 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 =[deflist]

: Definition list

A list with terms

: Start term with colon

And its definition follows

= Numbered List =[numlist]

See [List #list], the same rules apply.

= List =[list]

%INCLUDED(t2t) starts here: ../../../test/marks/list.t2t

%%% 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.

%%% 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

% comment lines are NOT considered blank lines

- Level 4

% comment lines are NOT considered blank lines

- 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

% comment lines are NOT considered blank lines

% comment lines are NOT considered blank lines

- This list is closed by a line with spaces and TAB,

- then a comment line, then an empty line.

% comment lines are NOT considered blank lines

%%% 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 =[table]

%INCLUDED(t2t) starts here: ../../../test/marks/table.t2t

%%% 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 |

% comments don't close an opened table

| <- | -- | -> |

| -- | -- | -- |

| -> | -- | <- |

%%% 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

| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F |

%%% 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.