__ ___ __ _ \ \ / / \/ | | \ \ /\ / / |\/| | | \ V V /| | | | |___ ``WML is the Unix toolkit for getting \_/\_/ |_| |_|_____| your webdesigner's HTML job done.'' Website META Language, CHANGES INTRODUCED BY MP4H 22 May 2000 Denis Barbier Introduction ============ This document describes implications of the replacement of Meta-HTML by mp4h for macro expansion. I tried to minimize this impact, but some issues can not be handled automagically and will be discussed below. If you followed recommendations on good WML writing, all macros definitions are grouped into templates files, and those files only need attention. So again i believe this change has very limited consequences. How to update without breaking everything? ========================================== After reading next paragraphs, you may fear that upgrading templates will break everything. Fortunately, there is a solution to write templates which are compatible both with WML 1.x and WML 2.0. In WML 1.x, the -I and -S option flags are read from left to right on command line, whereas they are read from right to left in WML 2.0 Thus if your templates reside in a directory called `templates', create a directory named `templates-2.0' and replace in top .wmlrc -I templates by -I templates -I templates-2.0 -i wml::sys::compat1 and create an empty file templates/sys/compat1.wml. So your site may be built with WML 1.x, and when you want to try to use WML 2.x, you just have to check which templates have to be modified, copy these files into templates-2.0 and perform appropriate changes. What was wrong with Meta-HTML? ============================== There were several points which decided me to give it away. One important point was its license. Meta-HTML is undoubtedly free software, but its license restricts hacking, which i do not like, and make this license incompatible with the GNU GPL (do not ask me why a program supported by the GNU project has a licence incompatible with the GNU GPL). Ralf and i were contacted in summer 1999 by the FSF to include WML into the GNU project, so this legal issue was quite important IMHO. There are technical reasons too. I was asked several times how to pass attributes with expressions like > With WML 1.x, the ``name'' attribute has an empty value. This is not a bug in Meta-HTML, but a problem with our modified version. I could not let it work without breaking backward compatibility. Any person who wrote macros to show examples of WML code know that this is a painful task. I wanted a syntax which is elegant and clear. So what has changed? ==================== a. Functions MACRO DEFINITION Mp4h provides only one tag for macro definition : Here is how to transform Meta-HTML tags within mp4h. Meta-HTML mp4h define-container define-tag endtag=required defmacro define-tag endtag=required defsubst define-tag NOTE: the define-function and defun tags are not supported, but it is fairly easy to replace them by define-tag. The defweakmacro is not supported and will never unless someone points me to its advantages. ARITHMETIC OPERATORS Meta-HTML defines the
tag for arithmetic division. This is a very bad idea since this tag is already defined in HTML 4.0. The following arithmetic operators have been changed: Meta-HTML mp4h div divide sub substract mul multiply mod modulo GROUPING The and tags are replaced by . In Meta-HTML, is a synonym for . But there is an important difference between Meta-HTML and mp4h about the tag. With Meta-HTML, all spaces were preserved (including tabulations and newlines), but mp4h gobbles them. EVALUATION The <%%eval> tag is obsolete, because expansion scheme is different in Meta-HTML and mp4h. You may safely remove this tag. NOTE: the wml::sys::compat1 module provides backward compatibility with WML 1.x. This module defines the tags which have been removed and listed above, except for defun, define-function, div and %%eval. PACKAGES AND ASSOCIATIVE LISTS Mp4h does not contain any support for packages and associative lists. As WML never uses these features, they have been removed. ARRAYS The tag has been renamed into . Arguments of (a.k.a array-push), , and are not handled the same way with Meta-HTML and mp4h. Within mp4h, first argument is always the name of the variable containing the array this tag acts on. MISCELLANEOUS The and tags have been removed too. They are easy to implement, and i will if there is demand. The has been renamed into . b. Special strings In replacement text, some strings have a special meaning. Meta-HTML uses the following strings: %body, %qbody, %xbody, %attributes. In mp4h, the %qbody and %xbody are obsolete, but are still recognized for compatibility reason. Documentation explains that %body must be escaped in nested definitions, like foo body: %body bar body:%\body With mp4h, it is more intuitive, percent signs are escaped with %, so example above becomes foo body: %body bar body:%%body Meta-HTML use special & expressions when defining new tags. These expressions are _not_ supported by mp4h, and macros that are defined with these expressions have to be rewritten. The &unevalled key is replaced by ``attributes=verbatim'', and expressions for named parameters (&optional, &key, &body) are replaced by the / mechanism. c. Implicit variables There are two cases where ``'' could be replaced by ``i'' with Meta-HTML: inside arithmetic expression (e.g. ) and array indices (e.g. ). Mp4h implements the latter for compatibility reasons, but its use is discouraged. d. Input expansion How tokens are read and expanded is completely different in Meta-HTML and mp4h. I will not explain what this scheme is with Meta-HTML, since i had no clear idea about it. But i will focus on some problems i encounter when migrating to mp4h. e. Trailing slash in attributes Mp4h recognizes a trailing slash in attributes to conform to XHTML syntax. ESCAPED QUOTES Double quotes within strings must be escaped with Meta-HTML, like in ==" "W " "Z "> With mp4h, escaped double quotes are used only when this sign must appear on output. You do not have to escape them in the previous example, because tokens are expanded from inner to outer. So one may write with mp4h: ==" "W " "Z "> Another example: Arg1:%1 Attrs:%attributes!! " y> gives Arg1:y Attrs "x Arg1:"2" Attrs \"1\" \"2\"!!" y!! Quotes are removed in % expressions, but not in %attributes!? With mp4h, Arg1:%1 Attrs:%attributes!! " y> gives Arg1:y Attrs:x Arg1:2 Attrs:1 2!! y!! In one word, unescape all double quotes when quotes are used to group characters into expressions. UNKNOWN TAGS Meta-HTML is smart enough to allow expressions like > or even > The ``<: ... :>'' tag is considered as a single expression. But consider now 0; :>> {"name"}; :>> {"name"}; :>> Give it a try and you will conclude that this is more complicated that it looks. In mp4h, unknown tags are handled in a different way. When a left angle bracket is followed by an invalid name (i.e. characters which can not produce a valid name), it is considered like normal text. So > will only print <:> after pass 2 and thus cause an error in pass 3. On the other hand, unknown tags which are valid (i.e. whose name allow them to be defined) are treated like single tags, and their attributes are expanded (note: with -X flag, it is possible to define unknown tags as being complex). So > will give the desired output.