In the process of making the HTML files, WML implements a text diversion filter. That bit of jargon means that a section of text can be created in one place in a file, or in a completely separate file, and then included somewhere else within the HTML. This is most helpful with templates, because a template is an HTML file that usually defines the outer HTML (the top, sides, and bottom), and the inner HTML (the page contents) is in a separate file.
This is one syntax to create a diversion:
..DIVERSION>>This is the diversion text<<..
The marker ..DIVERSION>> begins the text. The name DIVERSION is all uppercase by convention. The diversion does not have to be named DIVERSION; it can be named anything you want as long as the name begins with an alpha and is followed by zero or more alphas, digits, or underscores, upper-or lowercase. The text in the diversion continues until the end-of-diversion marker <<.. is found.
To use the diversion later (or even before its definition) use this:
<<DIVERSION>>
This causes the text in the definition to be included at this point.
An example can be found in /var/wwwl/wml/diversion.wml:
..NAME>>John Doe<<.. Hello <<NAME>>! <br> Here is my message: <<MSG>> ..MSG>> WML is cool! <<..
The example starts with a diversion definition for NAME, "John Doe." The next line uses the diversion <<NAME>> in the text:
Hello <<NAME>>!
This line becomes this, after WML is finished processing:
Hello John Doe!
The definition of NAME comes before its use. That's fine. The next line, however, uses a diversion not yet defined:
Here is my message: <<MSG>>
The diversion for MSG is defined after it is used. That's kosherbecause WML is a multipass process, the definition can be before or after. This definition:
..MSG>> WML is cool! <<..
spans multiple lines. That's fine tooyou are free to add whitespace as needed or desired.
To build the HTML, make the WML in the usual fashion:
$ wmk diversion.wml wml -n -o diversionl diversion.wml
The resulting HTML file is:
Hello John Doe! <br> Here is my message: WML is cool!
If you want to see this example, check out http://localhost/wml/diversionl or www.opensourcewebbook.com/wml/diversionl.
There are other diversion syntaxes as well. One such syntax is:
# create the diversion to use later
{#NAME#:
John Doe
:##}
# use the diversion
My name is: {#NAME#}!
This is another syntax, which requires the use of wml::std::tags:
#use wml::std::tags <divert NAME>John Doe</divert> My name is: <dump NAME>!
We most often use the ..NAME>> ... <<.. syntax, but on occasion we use the <divert NAME> ... </divert> syntaxTMTOWTDI (in WML as well as in Perl and most things LAMP).