Open Source Web Development with LAMP Using Linux, Apache, MySQL, Perl, and PHP [Electronic resources] نسخه متنی

6.3 The Basics

First we discuss some basic ideas of WMLhow the files are built and how WML processes them to make the resultant web page. This is important to our understanding of the capabilities and limitations of WML.

6.3.1 Building the HTML Files

WML source files are named with a .wml extension (e.g., example.wml). These files are not HTML but the WML code that is used to generate the HTML that the browser interprets. To create the HTML from the wml code, use the WML make program wmk.

$ wmk example.wml 
wml -n -o examplel example.wml 

This builds the HTML file examplel. The -o examplel option means that this is the output file to be generated.

To recursively build all the WML files in a directory and its subdirectories, use the -a option:

$ wmk -a . 

This command builds all the files that end in .wml. If we don't want to build all the files, but only the files named index.wml, we can execute the following command:

$ find . -name index.wml -exec wmk {} \; 

6.3.2 WML Phases

WML compilation is a nine-pass process. This is only a brief overview of the phases, but wmd describes the process completely.

Pass 1: Source reading and include file expansion
Reads all files that are either included or used. The specified file is read from either the current directory or a directory indicated with the -I option to the wml command. The -I option can be set in the WML resource file .wmlrc. (We discuss resource file options later.) Also, the special strings __FILE__ and __LINE__ are expanded (more on this later, too). Either do a man wml_p1_ipp(1) or use the wmd browser for more information.

Pass 2: High-level macro construct expansion
Processes the defined macros and expands them. We discuss this in detail later, but a simple example looks like this:

<define-tag myname>John Doe</define-tag> 
My name is <myname>. 

The result of this little example is the text "My name is John Doe." See wml_p2_mp4h(1).

Pass 3: Programming construct expansion
Executes the embedded Perl code (aka eperl
[1]) in the file. (We discuss this later as well.) eperl code can be placed between the <perl> ... </perl>, the <: ... :>, or the <:= ... :> tags. Here is a simple example:

#use wml::std::tags 
<perl> 
sub print_name { 
my($name) = @_; 
print "Hi, my name is $name!"; 
} 
</perl> 
The message is: <: print_name("John Doe") :> 

Chapter 10.

This example generates "The message is: Hi, my name is John Doe!" See wml_p3_eperl(1).

Pass 4: Low-level macro construct expansion
Uses a low-level macro processor for low-level programming. We don't talk much about this phase, so if you want more information, see wml_p4_gm4(1).

Pass 5: Diversion filter
Allows us to create locations using syntax such as #FOO# or <divert FOO> ... </divert>, or ..NAME>>foo<<.., and <<FOO>> or <dump FOO> to slurp them in later. We talk about this in detail in a later section, but here is a simple example:

..NAME>>John Doe<<.. 
My name is: <<NAME>>! 

This example generates "My name is: John Doe!" See wml_p5_divert(1).

Pass 6: Character and string substitution
Substitutes characters and substrings within {: ... :} to support international and special characters. We don't talk about this (because in our experience it isn't used that much), so for details see wml_p6_asubst(1).

Pass 7: Markup code fixup
Repairs HTML code, a real help for programmers. Have you ever forgotten those double quotes for your attribute values? This pass adds them in. Have you ever forgotten your HEIGHT and WIDTH attributes in your <img> tag? Fear not, this pass adds them in. Often-forgotten attributes (ALT for images, SUMMARY for tables) are also added. Lazy programmers like us appreciate this phase. See wml_p7_htmlfix(1).

Pass 8: Markup code stripping
Removes unneeded characters. HTML files often contain extra whitespace characters that do nothing but add unneeded bytes, which someone has to wait to download. This pass strips those out, as well as other unneeded HTML characters. If you have a section of text that you do not want to be stripped, you can use the <nostrip> ... </nostrip> tags, and Pass 8 leaves them alone except for the <nostrip> tags themselves. See wml_p8_htmlfix(1).

Pass 9: Markup code splitting and output generation
Allows splitting the output among more than one file, also known as a slice. This is handy if you need to generate one HTML file in English and another in German, for instance. This capability is useful but advanced for us, so for further information, see wml_p9_slice(1).

6.3.3 The <protect> Tag

Sometimes we don't want WML to process all of the code. An instance of this would be a listing of a shell scriptWML would see the comments in the shell script and strip them out. These sections can be wrapped in <protect>...</protect> tags, and WML will not process them except for removing the <protect>...</protect> tag.