NAME

       wml::std::lang - Multi-Lingual Support

SYNOPSIS

        #use wml::std::lang

        <lang:new id=xx [short]>

        <lang:area>
        (xx) ... (yy) ...
        </lang:area>

        <lang:set-wildcard ...>

        <lang:star: ...*..>
        <lang:star:href: index.*.html|index.html>
        <lang:star:slice: index.*.html>

        <lang:xx>...</lang:xx>
        <lang:xx: ...>

        <xx>...</xx>
        <xx: ...>

        <lang:current>
        <lang:list>

DESCRIPTION

       This include file provides high-level multi-lingual support via Slices.  Its purpose is to
       define the slices ``"LANG_XX"'' according to the multi-lingual selection tags.

       The general intend of this slice-based approach is to use the defined slices in Pass 9
       (Slice) via WMLs -o option.  A typical shebang-line example for the use with a webserver's
       content negotiation feature is:

         #!wml -o (ALL-LANG_*)+LANG_EN:index.html.en \
               -o (ALL-LANG_*)+LANG_DE:index.html.de

       Since WML 1.7.0, the "<lang:star:slice:>" tag is an alternative to this shebang-line.

       Before you can use a language, you have to define the corresponding tags via "<lang:new>".
       For instance when you want to use the languages english and german, use:

        <lang:new id=en>
        <lang:new id=de>

       Then the following tags are defined:

        <lang:en>...</lang:en>
        <lang:de>...</lang:de>
        <lang:en: ...>
        <lang:de: ...>

       i.e. for both languages a container tag and a simple tag is defined. The container tag is
       more readable while the simple tag is nicer for short variants. When the names "lang:xx"
       are still to large for you, you can use the "short" attribute to "<lang:new>"

        <lang:new id=en short>
        <lang:new id=de short>

       when then leads to the defintion of the shortcut variants:

        <en>...</en>
        <de>...</de>
        <en: ...>
        <de: ...>

       Additionally you always have the "<lang:area>"..."</lang:area>" container tag available
       which provides an alternative way of selecting the language in its body. It automatically
       surrounds the data between `"(xx)"' start tags with the corresponding "LANG_XX" slice.

       The following are equal:

        <lang:xx: Foo><lang:yy Bar>
        <lang:xx>Foo</lang:xx><lang:yy>Bar</lang:yy>
        <lang:area>(xx)Foo(yy)Bar</lang:area>

       Because these three lines internally get expanded to

        [LANG_XX:Foo:][LANG_YY:Bar:]
        [LANG_XX:Foo:][LANG_YY:Bar:]
        [LANG_XX:Foo:][LANG_YY:Bar:]

       There is one additional special tag: "<lang:star:>".  This tag expands its attribute line
       like the "<lang:xx:>" tags but multiple times. Actually as much as defined languages
       exists ("<lang:new>"!).  And in each expansion the asterisks (=stars) in the data gets
       replaced by the language identifier.

       Is is sometimes convenient to use another wildcard, e.g. when defining navigation bars.
       The "<lang:set-wildcard>" tag does the job.  The attribute becomes the wildcard used in
       future substitutions. Without attribute, the default value is restored. You may specify
       any regular expression, and do not forget to escape special characters (the astersisk is
       in fact ``\\*'').

         <lang:set-wildcard "%">
         <lang:star: index.%.html>
         <lang:set-wildcard>

       There is a more specialized variant named "<lang:star:href:>" which is similar to
       "<lang:star:>" but treats its attribute value as a URL part and tries to check if it
       already exists. If it doesn't exist the tag expands the value without the star or an
       alternative value which can be appended with ``|alt-value''.

       The "<lang:star:slice:>" is another variant to help writing multi-lingual files quickly.
       It must come after all occurences of "<lang:new>" tags.

         <lang:star:slice: index.html.*>

       The `%BASE' form is recognized (see wml(1)) and an empty argument is equivalent to the
       string `"%BASE.*.html"'.  But note that the use of this tag instead of the WML shebang
       line prevents WMk from doing its job, because WMk can not guess output filenames in this
       case.

       For complex multi-lingual documents, you may want to know in which language text is
       currently processed.  This is achieved with

         <lang:current>

       which always returns current language (as defined in "<lang:new>" or an empty string when
       outside of any language portion. The macro

         <lang:list>

       prints the newline separated list of defined languages.

EXAMPLE

       The following is an example of a webpage "index.wml" with a multi-lingual header and
       hyperlink:

        #use wml::std::lang
        #use wml::std::href

        <lang:new id=en short>
        <lang:new id=de short>
        <lang:star:slice: index.html.*>

        <h1><en: Welcome><de: Willkommen></h1>

        <href name="The Hyperlink" url="<lang:star: index.*.html>">
        <href name="The Hyperlink" url="<lang:star:href: index2.*.html|index2.html>">

       When processed via

         $ wml index.wml

       The following two output files are generated (assuming that index2.html and only
       index2.de.html exists):

       index.html.en:

         <h1>Welcome</h1>
         <a href="index.en.html">The Hyperlink</a>
         <a href="index2.html">The Hyperlink</a>

       index.html.de:

         <h1>Willkommen</h1>
         <a href="index.de.html">The Hyperlink</a>
         <a href="index2.de.html">The Hyperlink</a>

AUTHOR

        Ralf S. Engelschall
        rse@engelschall.com
        www.engelschall.com

        Denis Barbier
        barbier@engelschall.com

REQUIRES

        Internal: P1, P2, P6, P9
        External: --

SEE ALSO

       slice(1)