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
