! 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" 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: ` `
= Explicit line-breaks
All occurences of two semicolons (`;``;`) will translate to;;explicit;;line;;break.
= URLs
You can also specify URLs. Either:
{{{
Ruby
}}}
which will be: Ruby or:
{{{
"Ruby on Rails"
}}}
which will end up: "Ruby on Rails".
Supported schemes are (for now): http, https, ftp, mailto, news, irc.
Also supported is "relative link" scheme.
Also supported is "section link"<#:Hea> scheme (with "this variant"<#Hea>).
Also, you can use empty label to get the URL itself used
as the label. Not to mention "&@!#$!#@~*)!(^!#$&!()#$&)098$#&^!@#)$(*7<>!@#$$&*(^)" special chars shouldn't mess things up.
= Images
All lines beginning with at-sign are interpreted as image tag.
Syntax:
{{{
@ [style]+
}}}
Ex1:
{{{
@ https://wejn.org/favicon.ico
}}}
@ https://wejn.org/favicon.ico
Ex2:
{{{
@ https://wejn.org/favicon.ico border: 2px solid red
}}}
@ https://wejn.org/favicon.ico border: 2px solid red
Ex3:
{{{
@ https://wejn.org/favicon.ico border: 2px solid green
@ https://wejn.org/favicon.ico border: 2px solid red
}}}
@ https://wejn.org/favicon.ico border: 2px solid green
@ https://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.