# The header:
{header|
    {title|The Bracetax syntax}
# can also contain {authors|...} and {subtitle|...}
}

{section 1|Introduction}

This document defines the rules of the Bracetax syntax and explain the
semantics of its commands. Some examples give the expected behaviour for
transformations in HTML and LaTeX using the {t|ocamlbracetax} library.
It's also used as a {link index.html#sec_example_core|complete example of
bracetax syntax}.

{section 1|Rules}


In the text there are {i|only} three special characters:
{list|
    {*} The {i|opening brace}, {t|{{}}, which starts the command mode
    {*} The {i|closing brace}, {t|{}}}, which finishes a command
    {*} The {i|sharp}, {t|{#}}, which starts a comment to the end of the line
}
Those charcters can be escaped with the commands {t|{{}{{}{}}}, {t|{{}{}}{}}}
and {t|{{}{#}{}}}.
{p}
All whitespace characters are considered as a space ({t|' '}).
{p}
A command has the form:
{code}
{cmd arg1 arg2 arg3|concerned text}
{end}
Between the {t|{{}} and the {t||}, it's the command mode:
{begin list}
    {*} {t|'\\'} escapes the backslash (used as escaper)
    {*} {t|'\ '} escapes the space (used as argument separator)
    {*} {t|'\|'} escapes the pipe (used as command/text separator)
    {*} {t|'\{{}'} and {t|'\{}}'} escape
        the braces (except for the {t|{{}{{}{}}} and {t|{{}{}}{}}} commands)
{end}
A command can have no arguments and no text, {i|e.g.} {t|{{}br{}}}
{p}
And for long blocs: {begin t}{{}cmd arg|Some text{}}{end}
is equivalent to {begin t}{{}begin cmd arg{}}Some text{{}end{}}{end}
{p}
Non-parsed ({i|i.e. {q|code}}) blocs have a
{link local:sec_verbatim|special syntax}
{p}
For each command the arguments can be considered optional (they have default
values).

{section 1|Comments}

Are only allowed in {i|text mode}:
{code e}
Text # Comments...
{cmd arg|
    Text # Also comments...
}
{cmd # NOT COMMENTS !!! | Text }
{e}

{section 1|Commands}


{section 2|Characters}

Example:
{code e}
Those are {{}, {}}, {#}, Unbreakable->{~}<-space,
horizontal{...}ellipsis, dashes: en{--}em{---}, and {utf 0x42}, {utf 339}.
{e}
Those are {{}, {}}, {#}, Unbreakable->{~}<-space,
horizontal{...}ellipsis, dashes: en{--}em{---}, and {utf 0x42}, {utf 339}. {p}

Here are actually all the commands available for special characters:
{begin table 2}
Bracetax's character{--}commands.
{c h|Command} {c h|Character}
{c|{t|{text}{{}{end}}} {c|{i|Left brace: '{{}'}}
{c|{t|{text}{}}{end}}} {c|{i|Right brace: '{}}'}}
{c|{t|{text}{#}{end}}} {c|{i|Sharp: '{#}'}}
{c|{t|{text}{~}{end}}} {c|{i|Unbreakable space: '{~}'}}
{c|{t|{text}{...}{end}}} {c|{i|Horizontal ellipsis: '{...}'}}
{c|{t|{text}{--}{end}}} {c|{i|The en-dash: '{--}'}}
{c|{t|{text}{---}{end}}} {c|{i|The em-dash: '{---}'}}
{c|{t|{text}{utf <int>}{end}}} {c|{i|Any UTF char as integer.}}
{end}
 {p}

Notes:
{list|
{*} In LaTeX, {t|{text}{utf <int>}{end}} depends on the
{t|{text}\unichar{...}{end}} command which is far from complete.
{*} There are many different typographical dashes. Bracetax provides
the two most used (together with the standard hyphen-minus which is on
every keyboard: '-').
See
{link http://en.wikipedia.org/wiki/Dash
|wikipedia:Dash},
{link http://en.wikipedia.org/wiki/Hyphen
|wikipedia:Hyphen},
{link http://en.wikipedia.org/wiki/Quotation_mark,_non-English_usage#Quotation_dash
|wikipedia:Quotation_dash}.


}




{section 2|Header}

To have a title bloc in you document:
{code e}
{begin header}
    Ignored text !!
    {title|Bracetax}
    {authors|{link http://seb.mondet.org|Sebastien Mondet}}
    {subtitle|A simple syntax for wikis and more...}
{end}
{e}

{section 2 sec_verbatim|Non parsed blocs}

{section 3 sec_code|The code command}
# We use the 'e' end tag so we are able to put {end} inside a code 
# environment:
The default case:
{code e}
{code}
My free    form {{ } {|} c
  code
{end}
{e}

But you can set the {i|end tag}:
{code e}
{code AnotherEndTag}
 Still Free
 form
with:
{end}
inside the bloc
{AnotherEndTag}
{e}

Those blocs will be rendered as {t|<pre>} or {t|\begin{{}verbatim{}}}.

{section 3 sec_bypass|The bypass command}

The command {t|{{}bypass{}}} has the same syntax than {t|{{}code{}}} but is
used to output directly some content, e.g.:
{code}
{bypass endtag}Some <i>HTML</i>{endtag}
{end}
It can be used by preprocessors to implement special commands.

{p}

For security reasons, this command can be disabled (actually treated as the
{{}code{}} command) in {t|ocamlbracetax} and in {t|brtx} (option
{t|-deny-bypass}).
Using {{}bypass{}} with a web application written with an interpreted language
could lead to code injection issues{...}

{section 3 sec_text|The text command}

The {t|{text}{text}{end}} command works also like
{t|{text}{code}{end}}, but it used to treat all the content as
{q|text}, {q|braces} and {q|sharps}, will have no effect.
For example:
{code}
{text endtag} Some text with {braces, |pipes} and #sharps#.{endtag}
{end}
will give: {text endtag} Some text with {braces, |pipes} and #sharps#.{endtag}

{section 3 sec_ignore|The ignore comand}

The {t|{text}{ignore}{end}} command has also the same syntax as the
{t|{text}{code}{end}} one, but is used to {i|ignore} some text, it
can be used to implement so-called {q|block comments}.
{code}
Some {ignore someendtag}uninteresting,
useless, and unreadable{someendtag} text
{end}
is equivalent to
{code}
Some #uninteresting,
#useless, and unreadable{someendtag}
 text
{end}

{section 2|Formating}

Some basic formatting:
{code e}
{i|italic}, {b|bold},
{i|italo{b|bold}},
{t|mono-spaced},
super{sup|script}, sub{sub|script}
{e}
{i|italic}, {b|bold}, {i|italo{b|bold}}, {t|mono-spaced}, super{sup|script},
sub{sub|script}

{section 2|Quoting}

{section 3|Run-In Quotations}

{code e}
Quotes:
    {q|default},
    {q '|single},
    {q es|españolas},
    {q fr|françaises},
    {q en|English},
    {q de|Deutsch} and 
    {q brout|unknown is default}
{e}
Quotes: {q|default}, {q '|single}, {q es|españolas}, {q fr|françaises},
{q en|English}, {q de|Deutsch} and {q|unknown is default}.
# {q en|English}, {q de|Deutsch} and {q brout|unknown is default}

{section 3|Block Quotations}

They are as simple as {t|{text}{quote| ... }{end}}. For example:
{code e}
{begin quote}
There is a theory which states that if ever anybody discovers exactly
what the Universe is for and why it is here, it will instantly
disappear and be replaced by something even more bizarre and
inexplicable. There is another theory which states that this has
already happened.
{b|Douglas Adams}
{end}
{e}
will give:
{begin quote}
There is a theory which states that if ever anybody discovers exactly
what the Universe is for and why it is here, it will instantly
disappear and be replaced by something even more bizarre and
inexplicable. There is another theory which states that this has
already happened.
{b|Douglas Adams}
{end}

{section 2|Paragraphs and line-breaks}

Paragraph: {t|{{}p{}}}, Line-break: {t|{{}br{}}}

{section 2|Sections}

The syntax is:
{code e}
{section level label|Title of the section}
{e}
The {t|level} is an integer: 1, 2, 3 or 4 (default is 1){br}
The {t|label} is a string for local {link local:sec_links|links}/references.

{section 2|Lists}

A list can be {t|item} (default) or {t|enum}, a new item begins with
{t|{{}*{}}}:
{code e}
{begin list enum}
  {*} The one
  {*} Two
  {*} Three
    {list item|{*} inside {*} more}
  {*} Four
{end}
{e}
{begin list  enum }
  {*} The one
  {*} Two
  {*} Three
    {list item|{*} inside {*} more}
  {*} Four
{end}

{section 2 sec_links|Links}

Local links:
{code e}
The {t|label} is a string for local {link local:sec_links|links}/references.
...
{section 2 sec_links|Links}
{e}
Other:
{code e}
There's a {link http://www.vim.org|Vim} syntax file.
{e}
but don't forget the {t|http://} because {q|{t|www.any-site.bouh}} can be
interpreted as a local (i.e. {t|./}) link.
{p}
A link may not have contents:
{code e}
{link http://seb.mondet.org}
{e}
Will give:
{link http://seb.mondet.org}

{section 2|Figures}

The syntax for images is:
{code e}
{image <src> [<w>px|<w>%] <label>|Caption text}
{e}

For example {link local:img:logo_candidate|this image}:
{code e}
{image
    logo.png
    100px
    img:logo_candidate
    |An image; for now it is the only logo candidate{...}}
{e}
{image
    logo.png
    100px
    img:logo_candidate
    |An image; for now it is the only logo candidate{...}}



{section 2|Tables}

For table we have two commands, the {t|table}:
{code e}
{table <nb-of-columns> <label> <default-align>|Caption and cells} 
{e}
and the cell:
{code e}
{c <format> <size>|content}
{e}
The {t|<format>} is the alignment ('l', 'r' or 'c'), the optional {q|is header
?} ('h'), in any order ({t|'_'} means {q|default}).{br}
The {t|<size>} argument is either the number of columns occupied or the total
size {i|r}x{i|c} (numbers of rows and columns).

Example:
{code endtablecode}
{begin table 4 tab:example r} 
{c|Simple cell} {c h|Header cell} {c rh|Header right cell} {c r|Right cell}
{c c|Center cell} {c l|Left cell} {c r 2|Right double cell} 
{c lh|Left header cell} {c c 2|Center double cell}  {c hl|Left header cell}
{c l 2x3|Two rows, three columns, left} {c|Default, fourth in the row}
                                        {c h|Header, 4th in the row}
{c|Default, 1st} {c|Default, 2nd} {c _ 2x2|2 rows, 2 columns, default} 
{c _ 2|Default, 1st and 2nd}                                           
{c|Simple cell} {c h|Header cell} {c rh|Header right cell} {c r|Right cell}
Caption of the table, default align is right
{end}
{endtablecode}

{begin table 4 tab:example r}
{c|Simple cell} {c h|Header cell} {c rh|Header right cell} {c r|Right cell}
{c c|Center cell} {c l|Left cell} {c r 2|Right double cell}
{c lh|Left header cell} {c c 2|Center double cell}  {c hl|Left header cell}
{c l 2x3|Two rows, three columns, left} {c|Default, fourth in the row}
                                        {c h|Header, 4th in the row}
{c|Default, 1st} {c|Default, 2nd} {c _ 2x2|2 rows, 2 columns, default}
{c _ 2|Default, 1st and 2nd}
{c|Simple cell} {c h|Header cell} {c rh|Header right cell} {c r|Right cell}
Caption of the table, default align is right
{end}

{p}

{b|Note:} The alignment doesn't seem to be in XHTML, so we use a {b|{t|style}}
attribute {i|and} a {b|{t|class}} attribute ({i|e.g.}
{t|<td class="centeralign" style="text-align:center;">}).

{section 2|Notes}

Notes are {t|\footnote}'s{note|In LaTeX} or {i|sidenotes}{note|In XHTML... with
a CSS}
{code e this_is_brtx_code}
Notes are {t|\footnote}'s{note|In LaTeX}
{e}

{section 1 sec_plugins|Post-processing plugin system}

With the {t|code} environment you can also prepare post-processing:
{code e brtxcode}
{code end_tag name_for_the_plugin}
A   non - parsed    {b|block}
{end_tag}
{e}
Will add {t|verbatimbegin/end} comments, {i|e.g.} for XHTML:
{code}
<!--verbatimbegin:name_for_the_plugin -->
<pre>
A   non - parsed    {b|block}
</pre>
<!--verbatimend:name_for_the_plugin -->
{end}
or for LaTeX{note|The space between '\' and 'end' is due the impossibility to
put '{t|\end{{}verbatim{}}}' in a LaTeX {t|verbatim} evironment}:
{code end latexcode}
%verbatimbegin:name_for_the_plugin
\begin{code}
A   non - parsed    {b|block}
\ end{code}
%verbatimend:name_for_the_plugin
{end}
Then you can post-process your output searching for those {q|comment-tags}.