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. 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)
• 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:

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<http://ruby-lang.org/>

which will be: Ruby or:

"Ruby on Rails"<http://rubyonrails.org/>

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 scheme (with this variant).

Also, you can use empty label to get the https://wejn.org/ 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:

@ <url> [style]+

Ex1:

@ https://wejn.org/favicon.ico

Ex2:

@ 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

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.