{ Avocet: A Primer }

Avocet is a structured text language, along the lines of Markdown
{http://daringfireball.net/projects/markdown/} or reST
{http://docutils.sourceforge.net/rst.html}, which allows you to more easily
write documents for the web. This document gives a quick introduction to the
format with examples, to get you started as quickly as possible.

{{ Introduction }}

Most of the basic features of Avocet will be familiar to anybody who has used a
structured text language such as those found in a wiki or weblog software. For
example, paragraphs are written like HTML paragraph elements but without the
enclosing \<p> and \</p> tags. Lists can be written by prefixing each of the
list items with "* ", "+ ", or "- ". Emphasis can be done by enclosing text
with single asterisks, *, or underscores, _; and strong emphasis can be done by
enclosing text with double asterisks, **, and underscores, __. For example,
this Avocet source:

{{{
"Hello there", she said. "Would you like to see my... 
*website*?" He didn't reply, only continued to write 
his shopping list for the day:

* 3 Onions
* Cabbage
* Chocolate
}}}

Turns into this HTML:

{{{
<p>"Hello there", she said. "Would you like to see my... 
<em>website</em>?" He didn't reply, only continued to write 
his shopping list for the day:</p>

<ul>
<li>3 Onions</li>
<li>Cabbage</li>
<li>Chocolate</li>
</ul>
}}}

{{ Preformatting }}

Where it starts to get interesting is with features such as Easy Preformatting.
Preformatted sections are those in which you want whitespace to be preserved,
so it follows that they likely have particular detectable configurations of
whitespace. For example, consider this code:

def hello(*args): 
   for name in args: 
      print "Hello %s!" % name

Why must it be preformatted? Because of the whitespace on the second and third
lines. The rules that Avocet uses for detecting preformatting are: if a block
contains two spaces anywhere (except at the end), or any line starting with a
space, "# ", "/* ", or "// ", then it's preformatted. Just in case this isn't
enough, you can also delimit preformatted sections with "{{{" and "}}}" on
single lines.

If you have several Easy Preformatting sections together, they'll have a single
\<pre> element wrapping them. For example, this Avocet input:

def hello(): 
   print "Hello, world!"

if __name__ == '__main__': 
   main()

Becomes this HTML:

{{{
<pre>
def hello(): 
   print "Hello, world!"

if __name__ == '__main__': 
   main()
</pre>
}}}

{{ Ordered Lists, Headings, and Blockquotes }}

Ordered lists, converting to \<ol>, are done like this: 

{{{
1. This is the first list item.
2. This is the second list item.
}}}

You may also use 1), 2), et seq. style instead.

Headings can be done in either of two ways:

{{{
{ Level One Heading }

{{ Level Two Heading }}

{{{ Level Three Heading }}}
}}}

Or:

{{{
Level One Heading
#################

Level Two Heading
=====

Level Three Heading
-----------------------
}}}

You have to use at least three underline characters in the second kind. Both of
these convert to the following HTML:

{{{
<h1>Level One Heading</h1>

<h2>Level Two Heading</h2>

<h3>Level Three Heading</h3>
}}}