TXT2TAGS RULES
--------------
first, some conventions used:
SOL = start of line
EOL = end of line
TAB = the tabulation, \t char
---------------------------------------------------------------------
header line1 \n line2 \n line3
- the first 3 lines of the source file
- these lines will be the first 3 lines on the target document,
with high contrast to text body, or will be placed alone on the
first page (if paging is allowed)
- the headers are content-free, with no static information type
needed. even images can be used on header lines. but the following
is recomended for the most documents:
line 1: document title
line 2: author name and/or email
line 3: document date and/or version (nice place for %%date)
- leave the first line blank to not specify headers at all
(nice for command line oneliners or customized headers)
- leave the second and/or third lines blank to omit parts of header
---------------------------------------------------------------------
title <equal>words<equal>
- BALANCED equal signs around, = like this =
- the number of equal signs define the if title, subtitle, subsub...
- ==== it's a subsubsubtitle ====
- == spaces before or after each mark is optional ==
- there is a maximum of 4 subtitle, =====like this=====
- marks are not parsed on title lines, it's plain text
- === unbalanced equals are not title =
- title is NOT multiline ==like
this==
---------------------------------------------------------------------
paragraph
- paragraphs are delimited by blank lines
- except pm6, where each line is a paragraph
- other structures like lists, quote or pre also ends a paragraph
---------------------------------------------------------------------
comment <SOL><percent>coments
- a line begining with a percent char, % like this
- the % must be at the line begining, with no leading spaces
- as real comments, they're not showed on the converted text
- NOT multiline, so each comment line must begin with %
- useful for TODO and FIXME reminders
---------------------------------------------------------------------
bold <star><star>words<star><star>
- two stars around, **like this**
- NOT multiline **like
this**
- NO spaces at the marks boundary ** like this **
---------------------------------------------------------------------
bolditalic <star><slash>words<slash><star>
- starts and slashes around, */like this/*
- as bold, NOT multiline and NO boundary spaces
---------------------------------------------------------------------
italic <slash><slash>words<slash><slash>
- two slashes around, //like this//
- as bold, NOT multiline and NO boundary spaces
---------------------------------------------------------------------
underline <underscore><underscore>words<underscore><underscore>
- two underscores around, __like this__
- as bold, NOT multiline and NO boundary spaces
---------------------------------------------------------------------
preformatted <backquote>words<backquote>
- backquote around, `like this`
- as bold, NOT multiline and NO boundary spaces
---------------------------------------------------------------------
preformatted line <SOL><dash><dash><dash><space> words
- a line begining with exactly 3 consecutive dashes, --- like this
- the dashes must be at the start of the line, no spaces before
- use a space after the dashes to separate them from the text
- as a preformatted line it's NOT multiline, of course
---------------------------------------------------------------------
preformatted area <SOL><dash><dash><dash><EOL>
lines
<SOL><dash><dash><dash><EOL>
- a line with exactly 3 consecutive dashes
- followed by formatted text lines
- followed by another line with exactly 3 consecutive dashes
- NO spaces alowed before or after the marks
- marks are NOT interpreted inside preformatted area
---------------------------------------------------------------------
horizontal line <dash><dash><dash><dash><dash><dash><dash>...
<underscore><underscore><underscore>...
<equal><equal><equal><equal><equal><equal>...
- a line with at least 20 dashes, underscores and/or equal signs
- optional spaces can be placed at the line start or end
- any other chars on the line invalidate the mark
- if the first char of the mark is an equal, the line is large, or
if supported, it's a pause (for speech formats, like mgp)
---------------------------------------------------------------------
links url or email
links (explicit) <left-bracket>label url<right-bracket>
- a valid internet URL, ftp, news or email address
- these entities are detected as is, no mark needed, like@this.com
- the protocol (http, https, ftp) is optional, www.likethis.com
- optional explicit link mark, with label [my name www.likethis.com]
- if the target don't use links, they're just underlined
---------------------------------------------------------------------
quote <SOL><TAB>words
- a line that starts with a TAB
- more TABs at the start increase the quote depth (if allowed)
- there is not a limit for quote depth (depends on target)
- beautifiers like bold, italic are allowed insides quotes, but
other structures like lists, title or coments not.
---------------------------------------------------------------------
list <SOL><dash><space>words
- a line that starts with a dash followed by exactly one space,
- like this
- the first list char can NOT be a space, - like this
- optional spaces (regular spaces, not TAB) at the line begining
define sublists depth
- there is not a limit for sublists depth (depends on target)
- sublists end with a less depth item (from parent list)
- the list ends with two consecutive blank lines
---------------------------------------------------------------------
numbered list <SOL><plus><space>words
- a line that starts with a plus followed by exactly one space,
+ like this
- the first list char can NOT be a space, + like this
- same other rules of the previous non-numbered list
---------------------------------------------------------------------
definition list <SOL><equal><space>words<colon>
- a line that starts with a equal followed by exactly one space,
followed by words (the definition term), followed by a colon
= like this: got it?
- the first definition term char may be a space, = like this
- same other rules of the previous numbered list
---------------------------------------------------------------------
image <left-bracket>filename.XXX<right-bracket>
- a filename enclosed between brackets, [likethis.png]
- filename must end in .PNG, .jpg, .GIF, ... (case don't matter)
- symbols are allowed on the filename, [likethis!~1.jpg]
- NO spaces allowed on the filename, [like this.gif]
- NO spaces allowed on the brackets, [ likethis.gif ]
- of course, be sure that the desired target supports the image type
- the position of the mark on the line defines the image alignment:
[left.GIF] blablablabla [center.GIF] blablablabla [right.GIF]
---------------------------------------------------------------------
date (iso) <percent><percent>date
date (w/format) <percent><percent>date(format)
- two consecutive percent signs followed by the string "date"
- shorthand for the current date on the ISO yyyymmdd format
- optional date format, allowing %Y, %m, %d and such (see man date)
- useful for header versioning info
- sign of BLOATware...
---------------------------------------------------------------------
table <pipe><space>cell1<space><pipe><space>cell2...
- a leading pipe | identifies a table line
- a leading double pipe || identifies a table title line
- leading spaces are allowed before the leading pipes
- the fields are separated by the ' | ' string
- a final | at the first table line define border=YES
- a final | at the other table lines are optional (just cosmetic)
- beautifiers are valid inside table cells
- any non-table line closes a table
---------------------------------------------------------------------
raw <backquote><backquote>words<backquote><backquote>
- two backquotes around, ``like this``
- used to "protect" some text from parsing, ``**like this**``
- NOT multiline
---------------------------------------------------------------------
Aurelio Marinho Jargas
http://txt2tags.sf.net