spec.txt

! Spec.rb documentation
= Character escaping
You won't do much with special chars here: <>!@#$%^&*()_+[]\

= Comments
Every once a blue moon, you might need to comment out part of a document.
# i love this feature ;)
That's what lines starting with pound character (`#`) are for.

= Paragraphs
Each paragraph is separated by blank line.

So this is second one.

= Heading
Each heading is denoted by one or more `=` at the very beginning of line.

== So this is second level heading
Not surprising, huh?

= Lists:
Besides the free-form text you can have lists. Either unnumbered (ul):

* one
* two (with a link<#URLs>)
* three

or definition:

: HTML = HyperText Mark-up Language
: CSS = Cascading Style Sheets
: HTTP = HyperText Transfer Protocol

= Code blocks
Another possibility is to have code blocks:
{{{
while(1){
	printf("I am code, you know?\n");
}
}}}

Good thing on code block is, it behaves like "verbatim" in TeX and the
delimiters were selected to auto-fold in "vim".

Code blocks also contain possibility of JavaScript powered syntax highlighting:
{{{cpp
while(1){
	printf("I am code, you know?\n");
}
}}}

In order for this to work opening curly braces `{{{` must be followed
by name of the language used (`{{{cpp` in the example above).
See "highlight.js"<http://softwaremaniacs.org/soft/highlight/en/> for details.

= Inline code
All occurences of text within backslash (`) per single line is treated
as `inline code` block.

That, `of course, means` putting stray `backslash` on a line like this: ` has no effect.

= Highlighted text
All occurences of text within caret (^) per single line is treated
as ^highlighted text^.

That, ^of course, means^ putting stray ^caret^ on a line like this: ^ has no effect.

= Keywords
All occurences of FIXME, XXX, TODO are treated as keywords and marked as such.

= Non-breakable spaces
All occurences of tilde (`~`) will result in translation to non-breaking space: `&nbsp;`

= Explicit line-breaks
All occurences of two semicolons (`;``;`) will translate to;;explicit;;line;;break.

= URLs
You can also specify URLs. Either:
{{{
Ruby<http://ruby-lang.org/>
}}}
which will be: Ruby<http://ruby-lang.org/> or:
{{{
"Ruby on Rails"<http://rubyonrails.org/>
}}}
which will end up: "Ruby on Rails"<http://rubyonrails.org/>.

Supported schemes are (for now): http, https, ftp, mailto, news, irc.

Also supported is "relative link"<REL:spec.txt> scheme.

Also supported is "section link"<#:Hea> scheme (with "this variant"<#Hea>).

Also, you can use empty label to get the <http://wejn.org/> URL itself used
as the label. Not to mention "&@!#$!#@~*)!(^!#$&!()#$&)098$#&^!@#)$(*7<>!@#$$&*(^)"<http://google.com/> special chars shouldn't mess things up.

= Images
All lines beginning with at-sign are interpreted as image tag.

Syntax:
{{{
@ <url> [style]+
}}}

Ex1:
{{{
@ http://wejn.org/favicon.ico
}}}
@ http://wejn.org/favicon.ico

Ex2:
{{{
@ http://wejn.org/favicon.ico border: 2px solid red
}}}
@ http://wejn.org/favicon.ico border: 2px solid red

Ex3:
{{{
@ http://wejn.org/favicon.ico border: 2px solid green
@ http://wejn.org/favicon.ico border: 2px solid red
}}}
@ http://wejn.org/favicon.ico border: 2px solid green
@ http://wejn.org/favicon.ico border: 2px solid red

= Tables
All lines beginning with pipe (`|`) character denote table. All cells are
separated with pipe, too.

Heading row can be created using two pipes (`||`) at the beginning of line.
If you want first cell empty, use one non-breakable space: `|~|`.

||Name|Value
|One|2
|Two|3
|Three|5
|~|Empty space
||Name|Value
|Link|<#URLs>
|Inline|This TODO `should` ^also^ display

You could also align the table cells in your source, to look a bit prettier:

|| Numbers | here
|  One     | 1
|  Two     | 2
|  Three   | 3

And it is properly supported (heading/trailing space is deleted).

= Auto-TOC
Of course the system has automatically generated TOC, whose items are
pointing to appropriate headings in the spec.

= Alternative layout
By default there's hardcoded layout at the end of spec.rb ... which
is sometimes undesirable. You can specify alternative layout in two ways:
* by placing global layout file with name "layout.spec" in same dir as source
* by placing local (per-file) layout file with name "input.lsp" for "input.ext" file

Layout can contain normal HTML/XHTML markup with special tags in form: {{{{TAG_NAME}}}}.

Allowed/supported tag names are:
: CONTENT = Content of the spec file (final markup)
: TOC = Table of contents, including heading
: TOC_NO_HEADING = Table of contents, excluding heading
: TITLE = Title of the document
: NOW = Timestamp created by Time.now.to_s
: NOW_NUMERIC = Timestamp in form: "YYYY-MM-DD HH:MM:SS" (MySQL datetime format)
: FILENAME = Input filename

= That's it.
Not much, but for writing specs it's sufficient, IMHO.

Oh, and the HTML code should validate, IMHO.