NAME

WML Tutorial - Understanding WML step-by-step

DESCRIPTION

This tutorial gives you a step-by-step introduction to the features of
WML, separated into tiny lessons. Each lesson shows one particular
aspect or feature of WML. The order of lessons go from easy and
trivial to hard and complex.

IMPLICITMARKUPPROCESSING

LESSON:PlainDataThroughput
In this lesson we first learn that WML is 95% of the time transparent
to its input, i.e. we can pass through any data without corruption.
Input:
1| foo
2| <bar>
3| quux
Output:
1| foo
2| <bar>
3| quux
This is because per default there are neither definitions for symbols
"foo" or "quux" nor a defined HTML tag named "<bar>". And because there
are no unnecessary whitespaces in this example, the input cannot be
stripped in any case.
LESSON:ProtectedMarkupCode
Sometimes situations can occur where some of your markup code or page
contents conflicts with WML due to overlapping tagnames, etc. Here WML
interprets some stuff you actually don't want to be interpreted.
Input:
1| foo: foo.c
2| $(CC) -o foo foo.c
Output:
1| foo: foo.c
2| -o foo foo.c
Here the `"$(CC)"' was expanded to an empty string because IPP uses the
same syntax for variable interpolation like make. To avoid this just
surround the critical part with the WML-internal "<protect>" container
tag.
Input:
1| foo: foo.c
2| <protect>$(CC)</protect> -o foo foo.c
Output:
1| foo: foo.c
2| $(CC) -o foo foo.c
LESSON:Stripped-DownMarkupCode
Now let's try an example which has unnecessary whitespaces. Be careful,
`unnecessary' here means they can be stripped as long as the resulting
Webpage displays the same in a Webbrowser as the original.
Input:
1| <body>
2|
3| <img src = "file.gif" alt=" test " >
4| <pre>
5|
6| Preformatted Text
7| </pre>
8| Not Preformatted Text
9| </body>
Output:
1| <body>
2| <img src="file.gif" alt=" test ">
4| <pre>
5|
6| Preformatted Text
7| </pre>
8| Not Preformatted Text
9| </body>
Here we see that line 2 is completely removed because empty lines have
no effect in HTML. The whitespaces between the attribute "src" and its
value are removed, too. And all double whitespaces are replaced by a
single whitespace character. But not inside preformatted areas.
LESSON:FixedAndAdjustedMarkupCode
Now assume that we have an image.gif file containing a GIF image with a
size of 500x400 pixels and the following input page:
1| <body>
2| <center>
3| <font color=336699>Headline:</font><br>
4| <img src="image.gif">
5| </center>
6| </body>
Although this is valid HTML code, WML can enhance it to make it more
portable, speed up it rendering in the Webbrowser and make Lynx users
more happy. So WML recognizes the "<img>" tag and automatically adds
missing information and replaces obsolete tags with up-to-date
variants:
1| <body>
2| <div align=center>
3| <font color="#336699">Headline:</font><br>
4| <img src="image.gif" alt="" width="500" height="400">
5| </div>
6| </body>
As you can see, WML first replaced the proprietary "<center>" tag with
the HTML 3.2 pedant "<div align=center>", second it fixed the "color"
attribute of "<font>". And third it added missing "alt" and
"width"/"height" attributes.

STRUCTURINGTHEMARKUPCODE

LESSON:UsingIncludeFiles
One of the most useful features of WML is the ability to move commonly
used stuff into include files which can be selectively read in at later
steps.
Assume we have an include file bar.wml...
1| bar
2| The value of bar is: $(bar:-unknown)
...and the following input file:
1| foo
3| #include 'bar.wml' bar="FooBar"
2| #include 'bar.wml'
5| quux
Then the output is:
1| foo
2| bar
3| The value of bar is: Foobar
4| bar
5| The value of bar is: unknown
6| quux
As you can see, the "#include" directive is replaced by the contents of
the corresponding file. And this included contents can contain
variables which are interpolated when they are defined, inclusive
default values.
There is also a way to create simple constructs similar to an if-then-
else just by using variable interpolation:
1| The value of bar is $(bar:+set)$(bar:*unset).
Here the `"$(bar:+set)$(bar:*unset)"' construct emulates the following
semantics:
if (isdefined(bar))
expandto("set")
if (not isdefined(bar))
expandto("unset")
LESSON:ConcatenatingLines
Although HTML usually does not care about whitespaces and newlines,
sometimes it is very frustrating to create preformatted areas or write
own tags (see later) without the ability to spread the code over more
than one line while it should be actually one single line. For this a
lot of languages use a line concatenation/continuation character `"\"',
as does WML.
Input:
1| foo\
2| bar \
3| quux
Output:
1| foobar quux
The line concatenation strips whitespaces from the begin of
concatenated lines but preserves whitespaces at the end of them, i.e.
you can use leading whitespaces for structuring your input nicely but
still use appended whitespaces for real ones.
LESSON:DivertingToLocations
One of the most powerful features of WML is the ability to divert data
at any point to locations defined at any other point.
Input:
1| {#BAR#:this is:##}
2| foo
3| {#BAR#}
4| quux
5| {#BAR#: bar:##}
6| foobar
7| {#BAR#}
Output:
1| foo
2| this is bar
3| quux
4| foobar
5| this is bar
Here in line 3 the location "BAR" is already dumped, but filled at
lines 1 and 5. And as you can see a location can be dumped at any
point and even more than once. And you can accumulate the contents for
a location by subsequent fills (line 1 and 5). This works because in
WML first all locations are filled in a first pass and then dumped in a
second pass.
With the use of the high-level tags from wml::std::tags we also could
write the example above in a little bit more human readable way:
1| #use wml::std::tags
2| <divert BAR>this is</divert>
3| foo
4| <dump BAR>
5| quux
6| <divert BAR> bar</divert>
7| foobar
8| <dump BAR>
LESSON:DefiningOutputSlices
Often one needs more than one output file. Usually although 90% of the
contents is the same, one needs a way to select the remaining 10%.
WML's approach here is to write these 10% directly in the input file
but separate the variants by defining slices which later can be used to
create the different output files.
1| <html>
2| <head>
3| <title>[EN:Titleline:][DE:Titelzeile:]</title>
4| </head>
5| <body>
6| <h1>[EN:Headerline:][DE:Ueberschrift:]</h1>
7| </body>
8| </html>
Now assume the above page is in file index.wml, then the command
$ wml -o UNDEF+EN:index.html.en \
-o UNDEF+DE:index.html.de index.wml
generates the output file "index.html.en" containing the union of all
undefined areas and the slices `"EN"'...
1| <html>
2| <head>
3| <title>Titleline</title>
4| </head>
5| <body>
6| <h1>Headerline</h1>
7| </body>
8| </html>
...and the output file "index.html.de" containing the union of all
undefined areas and the slices `"DE"':
1| <html>
2| <head>
3| <title>Titelzeile</title>
4| </head>
5| <body>
6| <h1>Ueberschrift</h1>
7| </body>
8| </html>

MOREINFORMATION

Now you've seen the various core languages of WML in action. For the
gory details of what each language provides either read the all-in-one
WML Introduction in wml_intro(7) or step through the particular
manpages of the core languages. Start here with the frontend wml(1).
Additionally can can step through the set of available standard include
files WML ships with. Start with the top-level include file
wml::all(3).