Details of AoBane Syntax

# 1. At First. Backbone of AoBane is a PHP Markdown extension that is constructed by full set of [BlueFeather 0.41](http://ruby.morphball.net/bluefeather/doc/en/index.html) features, some [original PHP Markdown Extra](http://michelf.ca/projects/php-markdown/extra/) proposal spec and AoBane prorietary extended features.

This document is regarding to AoBane syntax. Some of them may be BlueFeather or original PHP Markdown Extra's one, but that's my recommended to use and I have pay serious attention to their RIGHTs.

AoBane means blue feather in Japanese. Pronounce [a-o-ba-ne].

2. Syntax of AoBane proprietary features.

2.1. Colored Pens in AoBane Markdown Style.

Did you want to use color characters, when you write Markdown documents? So, AoBane must be fit your hands. This function is realised by FONT TAG. What do you want to use by COLOR PEN? Color? Thickness? or Font? You can use all of these, not to say.

Straightaway, I introduce how to use color pen.

*[foo](color|fonts separated by "," / size of pen)

For instance,like this:

*[foo](red|Times,Arial/5)
This way represents, color is red and font face is Times (when a system don't have Times, Arial is adopted), size is 5.(size range is 1 to 7,as smaller to larger)

or

*[foo](red/+1)
This way, color is red,font size is default +1 size up, and font face is default.　You can ommit font face or font size or even color number,as you see.

or

*[foo](#ff0000/5)
You can specify a color by #------ style.

2.2. To Write a Complex Numerical Expression.

Did you want to write a numerical formula in Markdown documents? If you've been familiar with LaTeX expression which can express various numerical formulas with only plain texts, AoBane supports them by math_ml the rubygems. The math_ml is downloaded by AoBane gems, so you need not do anything for math_ml.

Here, I'll not explain about LaTeX expression. If you have not known about LaTeX, you should see here or here.

Now, I must introduce AoBane-LaTeX function (in other words, AoBane to math_ml bridge). You can use LaTeX expression in AoBane Markdown document,
like this:

\TeX{A=B\TeX}
Elements which surrounded by \TeX{ and \TeX} is passed to math_ml. And an expression is expanded by AoBane to math_ml bridge, and math_ml generates like below

<math xmlns='http://www.w3.org/1998/Math/MathML' display='inline'>
<mi>A</mi><mo stretchy='false'>=</mo><mi>B</mi></math>

As you see, A=B is a very short formula, but it exchanges a very long MathML seaquece. So, if you want to make HTML output file smaller, you should not use this frequently.

In the end of this section, I have to say that math_ml is not LaTeX a document preparation system, exactly. It's a LaTeX interpreter to MathML. So, It's not that you can express all of LaTeX syntax correctly. About this, you should see math_ml documentation before you use. And track updates of math_ml.

2.3. Auto Numbering Header

When you were writing Markdown, do you feel annoying to number to a section? For instance, next number is lost in your memory. Or have you want to write a monograph style document with Markdown? Then, you may take AoBane in your hand. Because AoBane has such function with very simple way which write only '%' seaquence.

If you want to use the Auto numbering header (ANH) function, you must write ANH specification before writing numbering header.
The header is like this:

{nrange:h2-h5}

Above syntax means that '%' is expand HTML as <h2> , and '%%%%' is <h5>, and also it shows that you can use header number is 1 digit to 5 - 2 + 1 = 4 digit.
like below:

{nrange:h2-h5}
................
% foo 1
........
%% foo 1.1
.......
%% foo 1.2
.......
%%% foo 1.2.1
.......
%%% foo 1.2.2
.......
%%%% foo 1.2.2.1
.......
% foo 2
.......
.......

Abobe one expand to HTML like below.

................
<h2 id="xxx1">1. foo 1</h2>
........
<h3 id="xxx2">1.1. foo 1.1</h3>
.......
<h3 id="xxx3">1.2. foo 1.2</h3>
.......
<h4 id="xxx4">1.2.1. foo 1.2.1</h4>
.......
<h4 id="xxx5">1.2.2. foo 1.2.2</h4>
.......
<h5 id="xxx6">1.2.2.1. foo 1.2.2.1</h5>
.......
<h2 id="xxx7">2. foo 2</h2>
.......
.......

This case, as you see, you can use h2 to h5 and 4digit number without pay any attention to numbers or headers. And if you set {toc} anotation the BlueFeather function, these headers ided individually, and each header was added as Table of Contents.

2.4. Fenced Box

Have you ever want to use box to emphasize sentences, or example or excercise as a special section? And want to use dotted style or color or Markdown syntax in a box? In [Regular Markdown](http://daringfireball.net/projects/markdown/syntax) or PHP Markdown syntax, you cannot use any Markdown writing just as you wanted in such a block elements, but Aobane Fenced Box has been able to use Markdown in enveloped lines by `|-:.......-----|`, surrounded lines by pipe( | ) , and ending by `|---...-----|`.
like this:

|-:b=2 solid gray w=300 rad=10-----------------|
### foo                                       
bar                                           
|______________________________________________|

This box's attributes are specified in first line. And second and third lines are characters in box. The end line of this box is delimiter of the fence. For example, this Fenced Box is expanded to HTML like this:

<div style="border:2px solid gray ; width:300px;border-radius:10px;">
<h3 id="xxx">foo</h3>
<p>bar</p>
</div>

The syntax of first line can be read as next:

|-:b=[width of borde line(px)] [Type of line] [Color of line] w=[width(px)|auto] h=[height(px)|auto] bg=[background color] lh=[line hight(% or em or px)] mg=[margine space(px)] al=[center|left|right|justify] rad=[border radius(px)]{className}--------|

You can ommit w,h,or bg and so on.
Note: You must separate each attributes by a white space.

2.4.1 Later v0.1.15 Additional Feature

There are specific changes.
1. Sentences needn't be surrounded by '|', because I felt it too much trouble.
2. The mark of the end of box is changed. form |-----| -> |______| Because, the program couldn't distinguish |----| between table separator sign and end of the box sign.
3. In a fenced box, each lines are connected as one line and white spaces at the end of line is compressed to one white space, because it couldn't control a layout of sentences as you see as you write.
4. This change is not just fenced box, I made "empty return" have a meaning as <br />.
If you want to box sentences in outer fenced box recursively, now you can box it. like as:

|-:b=2 solid gray w=300 rad=10-----------------|
outer foo
outer bar
|-:b=2 solid gray w=200 rad=10-------------|
inner foo
inner bar
|__________________________________________|
|______________________________________________|

Above is expanded below as HTML:

<div style="border:2px solid gray ; width:300px;border-radius:10px;">
<h3 id="xxx">outerfoo</h3>
<p>outerbar</p>
 <div style="border:2px solid gray ; width:200px;border-radius:10px;">
 <h3 id="xxx">innerfoo</h3>
 <p>innerbar</p>
 </div>
</div> 

And, you can write tables in fenced boxes.

2.5. Representing HTML Special Characters by Simple Way

To write a HTML special character is really annoying. It often disturb to write a Markdown document. Especially typo, when you only forgot typing one `;`, your HTML file become unsightly. And what you have to do next is that you must look for wrong character from a long Markdown document, like searching one grain of sand in the sea. I think that it is NOT human works. So, AoBane has human friendly anotations to be exchanged special characters of HTML. But this is not all of HTML special characters.
like below:

    -- — <=> ⇔  => ⇒ <= ⇐ ||^ ⇑ ||/ ⇓ <-> ↔

    -> → <- ← |^ ↑ |/ ↓  +_ ±

    != ≠ ~~ ≈ ~= ≅ <_ ≤ >_ ≥ |FA ∀ |EX ∃ (+) ⊕ (x) ⊗ (c) ©

    (R) ® (SS) § (TM) ™ !in ∉

2.6 Table Caption

Do you want to insert a caption to <table>? You can insert in AoBane.
Like this:

[foo]{#bar}
|fruits|price
|------|-----
|Apple|$0.5
|Orange|$0.3

the first line [foo]{#bar} and this table, expands HTML as below:

<table id="#bar">
<caption>foo</caption>
	<thead><tr>
		<th>fruits</th>
		<th>price</th>
	</tr></thead>
	<tbody>
		<tr>
			<td>Apple</td>
			<td>$0.5</td>
		</tr>
		<tr>
			<td>Orange</td>
			<td>$0.3</td>
		</tr>
	</tbody>
</table>

The "#bar" is adapted to table id, and "foo" is surrounded by <captin> and </caption> as elements in following table. When you put caption to a table, you should write `[Table 1](#Table1)` somewhere in your Markdown. So, you can jump to a table from the link.
Of course, you can omit this.

2.7 Abbreviation

Especially for not ASCII languagers, I need to study some more, perhaps about morphorogical analysis. So, if you use this function, you have to be careful.

This function is implementation of Abbreviations specifies in PHP Markdown Extra. And my some Idea which can make a UTF-8 textfile as other file definitions of abbreviation is implemented. In this case, Markdown is wrote like this:

{abbrnote:./dicSample.txt}
......

And dicSample.txt in same directory with Markdown—you can name as you like—is like below:

*[foo1]:bar
*[foo2]:barbar
*[foo3]:barbarbar
......

The reason why I set as this, you can create individual word set about your each Markdown files.And you may write like as:

{abbrnote:../share/dicSample.txt}
......
*[foo0]:foo

And ../share/dicSample.txt is

*[foo1]:bar
*[foo2]:barbar
*[foo3]:barbarbar
......

If you created files like this, you can controll a word set. For instance, foo0 is adapted only the above Markdown file, and foo1, foo2, foo3,...is adopted all Markdown files which is wrote {abbrnote:../share/dicSample.txt}.

Of course, you can use like PHP Markdown Extra. Incidentally,this function is not implemented on BlueFeather.

2.8 Insert TimeStamp at last modified

In writing documents, it's important when was the document last generated. You can manage this, only to write `$date` in your documents. like this:

<link href="../css/markdown.css" rel="stylesheet"></link>
# Pragmatic Programmer: From journeyman to master
$date
<a name="TOC">TOC</a>

This expand HTML like below:

<p><link href="../css/markdown.css" rel="stylesheet"></link></p>

<h1 id="bfheader-971940c29ad1294b0978972876362ec0">Pragmatic Programmer: From journeyman to master</h1>

<p>2013-04-24 00:19:48 +0900</p>

<p><a name="TOC">TOC</a></p>

This is trivial change,but important, I think...

3. In The End

This document explained about the AoBane Syntax. AoBane is based on MIT Lincense. So, you can republish as your new Markdown engine with modifying the source codes. But the time when you republish, let me know as much as you can.
And if you have new idea for AoBane, I'll respond your request as much and soon as possible. Then, I want to tell me too.
set.minami@gmail.com