docs: Include files are always searched at standard location, too.
This removes the need to specify the location where yml2 was unpacked or
installed as YML_PATH. So this now works:
YML_PATH=/foo ./yml2proc --xml2yml
The standard system location <prefix>/share/yml2 is now always appended to
the include search path. If this path does not exist, the directory one
above the `backend.py` file is added, allowing the same behaviour for
uninstalled yml2.
In the Makefile enforce the .ysl2 files to be searched in the current
directory first.
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)¬
}
}