[LONG] Re: How to write a paper about WML in WML

[Denis Barbier <nospam@thanx>]

On 6 Sep 1999, Fritz Zaucker wrote:

> Hi,

Hi Fritz,

> I am trying to write an article about WML for an internal journal of
> our computer center. Of course, I want to publish it on our Web-site
> as well. This leads to the problem of presenting WML-example code on a
> WMl-generated page. This leads to some interesting problems with
> including verbatim code.
> 
> While one can fool WML with for example entering
> 
> < define-container foo>
> 
> and then in using area substition to get rid of the the blank between
> < and define, this is not particularly elegant. The problem with the
> verbatim-environment is that it is evaluated to late.
> 
> Ideally, one would like to put some WML example code into an include
> file and then include it once as verbatim and then a second time after
> being processed by WML. But I guess that would involve at least
> processing these include files separately once and then include the
> resulting .html file verbatim again.

You guess wrong ;-)
The macros below implement this feature in a one-shot trip. Of course,
in some cases strange problems may occur. 

I need these include files
   #use wml::std::tags
   #use wml::std::box
   #use wml::fmt::verbatim

The latest has been updated on 20-Aug-1999 and i realize there is still
a bug. Replace <pass=4-8> by <pass=4-9>, i don't see why i didn't
protect against the last pass.

Here is a macro to write your examples to a file
<define-container verbatim-write &unevalled &body vw-body>
<preserve file>
<set-var %attributes>
<:
{
    my $file = '<get-var file>';
    if ($file eq '') {
        my $tmpdir = $ENV{'TMPDIR'} || '/tmp';
        $file = $tmpdir . "/wml.verbfile";
    }
    my $buffer = <<'__EOT_VERBATIM__';
<subst-in-string
  <subst-in-string
    <get-var-once vw-body>
                        "<:" "&lt;:">
                        ":>" ":&gt;">
__EOT_VERBATIM__
    open(FP, ">$file") || die "Unable to open $file for writing";
    print FP $buffer;
    close(FP);
}
:>
<restore file>
</define-container>

The subst-in-string tags are needed to escape ePerl delimiters.
The ``&unevalled &body'' is a dirty trick from Meta-HTML. I hope i could
provide a better way one day. Meanwhile i see no other solution :-(
Use this feature only when there is no alternative, i will suppress it ASAP.

Now we can write WML code verbatim to a file. Next we have to show this
code and execute it.

<define-container example>
<preserve label>
<set-var %attributes>
#   Write text to a file
<verbatim-write file="/tmp/wml-example">
%body
</verbatim-write>
#   Print file contents
<box header="<font face=\"Arial, Helvetica\">Source code : <get-var label></font>" \
     bdcolor="#333399" bdwidth=2 bdspace=5 \
     bgcolor="#ccccff">
<protect pass=2>\
<:
    #   The <protect> tag is to needed because of => below.
    #   Don't know why, any idea?
    $_ = &wml_fmt_verbatim({ FILE => '/tmp/wml-example'});

    #   ePerl delimiters are coming back. The backslash prevents 
    #   expansion during pass 3.
    s|&amp;lt;:|<\:|sg;
    s|:&amp;gt;|:\>|sg;
    print;
:>\
</protect>
</box>
#   And show what it does
<p>
<box header="<font face=\"Arial, Helvetica\">Result : <get-var label></font>" \
     bdcolor="#993333" bdwidth=2 bdspace=5 \
     bgcolor="#ffcccc">
#   The line below seems to be equivalent to %body. It is not because of
#   wml_p5_divert constructions >>NAME..
#   With %body, angle brackets will close groups. With the line below this
#   problem those angle brackets do not interfere because the are part
#   of strings.
<concat %qbody>
</box>
<restore label>
</define-container>

Some examples? Ok, let's go

<example label="Test Pass 2">
<define-container test>
<box header="Test"
     bdcolor="#000000" bdwidth=2 bdspace=5
     bgcolor="#ccffcc">
<pre>
%body
</pre>
</box>
</define-container>
<test>
This is a test
</test>
</example>

<example label="Test Pass 3">
<:
sub isotime {
    my ($time) = @_;

    my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) =
        localtime($time);
    my ($str) = sprintf("%02d-%02d-%04d %02d:%02d:%02d",
        $mday, $mon+1, $year+1900, $hour, $min, $sec);
    return $str;
}
:>
Last modified on <:=&isotime(time()):>
</example>

<example label="Test Pass 4">
<m4>
m4_define(`forloop',
    `m4_pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')m4_dnl
     m4_popdef(`$1')')
m4_define(`_forloop',
    `$4`'m4_ifelse($1, `$3', ,
        `m4_define(`$1', m4_incr($1))m4_dnl
         _forloop(`$1', `$2', `$3', `$4')')')
forloop(`i', 1, 8, `i ')
</m4>
</example>

<example label="Test Pass 5">
<<HEADER>>
<<BODY>>
<<FOOTER>>
..FOOTER>>
<hr>Copyright (c) 1999 me@domain.com
<<..

..HEADER>>
<h2>Diversion Test</h2>
<<..

..BODY>><p>And here goes the body.<<..
</example>

<example label="Test Pass 6">
{: [[tr#[a-z]#[A-Z]#]]
Are all TheSe lEtterS iN upperCaSe?
:}
<p>
{: [[s#(href=")([^"]*)#\1../\2#g]][[s#(this)#that#g]]
Follow this <a href="link.html">link</a>
:}
</example>

Passes 1, 5 and 9 require special attention.
* To suppress pass 1 parsing, you must either add
  <protect pass=1>...</protect> around your code or read a file via pass
  2, 3 or 4, e.g.
<define-container example-pass1>
<preserve label>
<preserve file>
<set-var %attributes>
<box header="<font face=\"Arial, Helvetica\">Source code : <get-var label></font>" \
     bdcolor="#333399" bdwidth=2 bdspace=5 \
     bgcolor="#ccccff">
<verbatim-file src=<get-var file>>
</box>
<p>
<box header="<font face=\"Arial, Helvetica\">Result : <get-var label></font>" \
     bdcolor="#993333" bdwidth=2 bdspace=5 \
     bgcolor="#ffcccc">
<concat %qbody>
</box>
<restore file>
<restore label>
</define-container>

<example-pass1 file="pass1.ex">
#include 'pass1.ex' VAR=value ....
</example-pass1>

With pass 5, you have to take care of location names. All different
buffers should have different names.

I don't know how to show examples of pass 9. you may use pass 3 to
invoke wml:
   system('wml -q -o A:test.a -o B:test.b test.wml');
It will be awfully slow, and you certainly do not need to always
regenerate output files.

-- 
Denis Barbier
WML Maintainer





______________________________________________________________________
Website META Language (WML)                www.engelschall.com/sw/wml/
Official Support Mailing List                   sw-wml@engelschall.com
Automated List Manager                       majordomo@engelschall.com