include homepage.en.yhtml2
page "Using YML 2" {
p >>
YML 2 is a smart ¬http://en.wikipedia.org/wiki/Template_processor template language¬ and
¬http://en.wikipedia.org/wiki/Domain-specific_language DSL concept¬. This guide will give
you a feeling, for what it's worth.
>>
h2 id=wiki > Creating a Wiki like language for writing documentation
p >>
Let's say, we want to define a small Wiki system, which should be translated from a Wiki
like language into HTML. This guide is written in one using YML 2. I call it ƒYHTML. You can
view the ¬homepage.en.yhtml2 source code of what you're reading now¬. It's about writing
web pages like that:
>>
Code {
||
page "Hello, world" {
p ¬features#blockquote >>¬
Hello, world! I can link here, say:
||
>
] ¬http://en.wikipedia.org to Wikipedia¬
> \n
||
¬features#blockquote >>¬
p ¬features#blockquote >>¬
||
>
] This is ƒemphasized. And this is «code».
> \n
||
¬features#blockquote >>¬
}
||
}
p >>
Prerequisite: knowing how ¬http://en.wikipedia.org/wiki/Html#Markup HTML¬ works.
>>
h2 id=how > How does that work?
p >>
YML 2 is a template language. That means, you can define ¬http://en.wikipedia.org/wiki/Recursion recursive¬
templates of what's to be generated. This is ¬homepage.en.yhtml2 the code¬; just click on underlined things
to get an explanation:
>>
Code {
||
¬features#quotethrough <¬?xml version="1.0" encoding="UTF-8"?¬features#quotethrough >¬
¬features#quotethrough <¬!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"¬features#quotethrough >¬
¬features#decl decl¬ pageContent ¬features#alias alias¬ body ¬features#defaultbody {¬
a name¬features#named =¬"top";
¬features#including include¬ ¬heading.en.yhtml2 heading.en.yhtml2¬;
div id¬features#named =¬"entries"
¬features#contentfc content¬;
¬features#defaultbody }¬;
¬features#decl decl¬ page(¬features#pointer *title¬, lang¬features#defaultattr =¬"en", xml:lang¬features#defaultattr =¬"en", xmlns¬features#defaultattr =¬"http://www.w3.org/1999/xhtml")
¬features#alias alias¬ html ¬features#defaultbody {¬
head ¬features#subtree {¬
title ¬features#pointer *title¬;
meta http-equiv¬features#named =¬"Content-Type", content¬features#named =¬"text/html;charset=UTF-8";
link rel¬features#named =¬"stylesheet", type¬features#named =¬"text/css", href¬features#named =¬"format.css";
¬features#subtree }¬
pageContent
¬features#contentfc content¬;
¬features#defaultbody }¬;
||
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"¬\s*(.*?)\s+(.*?)\s*¬"</a>
> ¬features#userop as¬ a href¬features#named =¬"%1" ¬features#quote >¬ %2
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"«(.*?)»"</a>
> ¬features#userop as¬ code ¬features#quote >¬ %1
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"ƒ(\S+)"</a>
> ¬features#userop as¬ em ¬features#quote >¬ %1
}
h2 id=details > Details, please!
h3 > Starting with XHTML headers
p >>
Because HTML headers are boring and annoying, I'm copying them from document to document. And at last,
they ended here ;-) If you already have things in angle brackets, you can just add them to your YML 2
document “as is”, because everything which starts with an opening angle bracket will be a “give through”
for the YML 2 toolchain. So our first two lines are:
>>
Code
||
¬features#quotethrough <¬?xml version="1.0" encoding="UTF-8"?¬features#quotethrough >¬
¬features#quotethrough <¬!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"¬features#quotethrough >¬
||
h3 > Defining the document structure
p >>
A Webpage usually has a structure: it has a specific title and content. Beside that, technical things
have to be encoded. A Webpage in XHTML is XML text, setting xmlns to the right name space. That's how we
do that in YML 2:
>>
Code
||
¬features#decl decl¬ page(¬features#pointer *title¬, lang¬features#defaultattr =¬"en", xml:lang¬features#defaultattr =¬"en", xmlns¬features#defaultattr =¬"http://www.w3.org/1999/xhtml")
¬features#alias alias¬ html ¬features#defaultbody {¬
||
p >>
First we ¬features#decl declare¬ the «page» function. It's ¬features#alias aliased to¬ «html», so it will
generate a «html» tag, not a «page» tag.
>>
p >>
The first parameter, «*title», is a placeholder for the title of the document. The content of what we give
here later will be repeated at any place we're putting «*title» into our template. This technique is called
¬features#pointer Pointers¬.
>>
p >>
The two other attributes have ¬features#defaultattr Default Values¬, so they're generated each time the
«page» function will be called.
>>
h3 > The Document content
p >>
The document content is what is in the «{ ... }» block:
>>
Code
||
¬features#defaultbody {¬
head ¬features#subtree {¬
title ¬features#pointer *title¬;
meta http-equiv¬features#named =¬"Content-Type", content¬features#named =¬"text/html;charset=UTF-8";
link rel¬features#named =¬"stylesheet", type¬features#named =¬"text/css", href¬features#named =¬"format.css";
¬features#subtree }¬
pageContent
¬features#contentfc content¬;
¬features#defaultbody }¬;
||
p >>
This reflects, that each HTML document has a «head» and a «body» section. Of course, we insert the «*title»
pointer value in the «title» tag. Then some meta data and a link to a nice
¬http://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS¬ ;-)
>>
p >>
For the «body» section, we have a little helper function, «pageContent». The function named «content» is
a ¬features#contentfc placeholder¬, where the content of the page will be placed, when our «page» function
will be called.
>>
h3 > Generating the «body» with the «pageContent» function
p >>
The «pageContent» function is used for generating the «body» with standard elements; therefore, it's
¬features#alias aliased¬ to «body»:
>>
Code
||
¬features#decl decl¬ pageContent ¬features#alias alias¬ body ¬features#defaultbody {¬
a name¬features#named =¬"top";
¬features#including include¬ ¬heading.en.yhtml2 heading.en.yhtml2¬;
div id¬features#named =¬"entries"
¬features#contentfc content¬;
¬features#defaultbody }¬;
||
p >>
It first sets an HTML anchor, so links can reference the top of the page:
>>
Code | a name¬features#named =¬"top";
p >>
Then a file with heading and navigation (the menu to the right on the page here) is being
¬features#including included¬:
>>
Code | ¬features#including include¬ ¬heading.en.yhtml2 heading.en.yhtml2¬;
p >>
At last, the page content is being put in, surrounded by a «div» named «entries», so it can be referenced
later, too:
>>
Code ||
div id¬features#named =¬"entries"
¬features#contentfc content¬;
||
p >>
If you'll have a look on the included ¬heading.en.yhtml2 heading.en.yhtml2¬ file, then you'll see the
the static head and navigation sections hard coded. With the ¬format.css CSS file¬ everything is brought
to the right place.
>>
h3 > Defining some operators for the Wiki like language
p >>
The trick with a Wiki like language is, that one can write plain text, and adding structural things
to it, like links i.e.
>>
p >>
So we need language constructs, which let us structure. In YML 2 these are called
¬features#userop User defined in-text Operators¬:
>>
Code {
> ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"¬\s*(.*?)\s+(.*?)\s*¬"</a>
> ¬features#userop as¬ a href¬features#named =¬"%1" ¬features#quote >¬ %2
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"«(.*?)»"</a>
> ¬features#userop as¬ code ¬features#quote >¬ %1
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"ƒ(\S+)"</a>
> ¬features#userop as¬ em ¬features#quote >¬ %1
}
p >>
They look somewhat disturbing, if you're not familiar with
¬http://en.wikipedia.org/wiki/Regular_expression Regex¬, so I will explain.
>>
p >>
First we define a link:
>>
Code {
> ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"¬\s*(.*?)\s+(.*?)\s*¬"</a>
> ¬features#userop as¬ a href¬features#named =¬"%1" ¬features#quote >¬ %2
}
p >>
The keyword «define operator» starts the definition. Then there is the Regex:
>>
Code | "¬\s*(.*?)\s+(.*?)\s*¬"
p {
"I decided I want to have the special character " "¬" " surrounding each link like this: "
code ] ¬http://en.wikipedia.org go to Wikipedia¬
". This is just like what ¬http://www.mediawiki.org MediaWiki¬ does with brackets; here the "
"same would read: «[http://en.wikipedia.org go to Wikipedia]»."
}
p >>
I like using such special characters. This is because I'm using a
¬http://www.apple.com/mac/ Mac¬ and ¬http://en.wikipedia.org/wiki/GNU/Linux GNU/Linux¬.
If you're using ¬http://www.microsoft.com/windows/ Windows¬, I really can recommend
¬http://www.autohotkey.com/docs/Hotkeys.htm AutoHotkey¬. It's a great piece of software to expand the
keyboard capabilities of Windows (and much more).
>>
p {
> How does this Regex stuff work? It's a ¬http://en.wikipedia.org/wiki/Pattern_matching pattern matching¬ language consuming characters with each
> command. Well, we want to have the following: The first thing between the
] ¬
> markers shell be the link target URL. All other things shell be the name of the link shown.
>>
For that case, we're first consuming whitespace with «\s*» – the «\s» means “an arbitrary whitespace
character” (like blank, newline, etc.). The asterisk «*» means “some of them or none”, so this
consumes all whitespace which is there (and gives no error if there is none).
>>
}
p >>
Second, we open a group with parentheses «( )» This first group we can later reference as «%1»
when substituting.
>>
p >>
Inside this group, we're telling that we want anything in it, no matter what it is. For this case,
we're using a dot «.» which means “any character”, followed by asterisk questionmark «*?», which is
the code for “consume as much as you can, but only up to the next code in the Regex”. The total
«(.*?)» consumes the target URL (without checking it).
>>
p >>
Then we're consuming some whitespace again, this time with «\s+». Using a plus «+» instead of an
asterisk «*» or asterisk questionmark «*?» means: there has to be at least one whitespace character.
And we want whitespace between the URL and the name, right? ;-)
>>
p >>
Now we're consuming the second group. We're consuming whatever is there – it's the name of the
link. We're using another «(.*?)» group for it. It will be group 2, and we can reference it with
this in the substitution: «%2».
>>
p {
> At last we're consuming redundant whitespace with «\s*», and our Regex is closed by another
] ¬
> character. And that makes the total Regex:
}
Code ] "¬\s*(.*?)\s+(.*?)\s*¬"
p >>
So what can we do with it? What we want are «<a href="..." />» tags. And that means, we want to
call a function like this: «a href="..." > ...»
>>
p >>
As «href» we want to have the result of group 1,
because this is the link target. After the ¬features#quote Quote operator¬ «>» we want to have
what is the name of the link, that is the result of group 2. That we can write literally:
>>
Code | a href="%1" > %2
p >>
Our first User defined in-text Operator is ready :-)
>>
p >>
Maybe you would prefer using brackets. So just do it ;-) Change the Regex to this, and you
can use brackets for links like in MediaWiki; we have to escape the brackets «[ ]» with a
backslash «\\», because brackets are also codes in Regex, and we don't want the code, we really
want brackets:
>>
Code | "\[\s*(.*?)\s+(.*?)\s*\]"
p >>
The other two operators should now be easy to understand:
>>
Code {
> ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"«(.*?)»"</a>
> ¬features#userop as¬ code ¬features#quote >¬ %1
br; > ¬features#userop define operator¬
] <a href="http://docs.python.org/library/re.html">"ƒ(\S+)"</a>
> ¬features#userop as¬ em ¬features#quote >¬ %1
}
p >>
A tip: the code with an upper case letter S «\S» means, that only non-whitespace characters shell
be consumed.
>>
h2 id=using > Using it
p >>
How to write a new web page with our templates? Here's a ¬hello.en.yhtml2 hello world¬. We can use
¬features#blockquote Block Quotes¬ for entering text, and our new self defined operators:
>>
Code {
||
¬features#including include¬ homepage.en.yhtml2
page "Hello, world" {
p ¬features#blockquote >>¬
Hello, world! I can link here, say:
||
>
] ¬http://en.wikipedia.org to Wikipedia¬
> \n
||
¬features#blockquote >>¬
p ¬features#blockquote >>¬
||
>
] This is ƒemphasized. And this is «code».
> \n
||
¬features#blockquote >>¬
}
||
}
p >>
The result you can ¬hello see here¬:
>>
iframe src="hello", width="100%", height=300 > ¬hello see here¬
div id=bottom {
> ¬index << back to Introduction¬
> ¬#top ^Top^¬
> ¬features >> The Features¬
> ¬programming.en.yhtml2 (source)¬
}
}