Provided by: wml_2.0.11ds2-1build1_i386 bug

NAME

       WML FAQ - Frequently Asked Questions on WML

DESCRIPTION

       This is the Frequently Asked Question (FAQ) list with answers on WML.
       It is divided into question/answer parts, each answering one particular
       topic.

   General questions:
       G01: What is WML?
       G02: WML is distributed as free software, does this mean I also can use
       it free of charge?
       G03: Why is WML a toolkit of disjunct programs instead of one big
       integrated program?
       G04: Which tools are included in the WML distribution?
       G05: WML is as powerful as it can, but are there even any restrictions?
       G06: Where do I find documentation?
       G07: Is there any official support for WML?
       G08: How I can I send a bug report to the author?
       G09: I really want to use WML for textprocessing because it's such
       powerful, isn't it?

   Questions about passes:
       P01: How can I avoid conflicts with a particular WML pass?
       P02: How can I avoid conflicts with a particular WML pass for only some
       areas of the input file?
       P03: Is there a way to change pass order?
       P04: Why shall I not change original pass order?

   Questions about include files:
       I01: How can I install or activate my own include files?
       I02: How can I overwrite the knowledge of the info-tag from
       wml::std:info?
       I03: How can I combine the gfont- with the href-tag?
       I04: How can I combine the gfont- with the rollover-tag?

   Error messages:
       E01: Cannot load "/tmp/wml..." for unprotection
       E02: ePerl:Error: Perl runtime error

   GENERAL QUESTIONS
       G01: What is WML?
            WML is a free and extensible Webdesigner's off-line HTML
            generation toolkit for Unix, distributed under the GNU General
            Public License (GPL v2).

            WML consists of a control frontend driving up to nine backends in
            a sequential pass-oriented filtering scheme. Each backend provides
            one particular core language. For maximum power WML additionally
            ships with a well-suited set of include files which provide
            higher-level features build on top of the backends core languages.
            While not trivial and idiot proof WML provides most of the core
            features real hackers always wanted for HTML generation.

       G02: WML is distributed as free software, does this mean I also can use
       it free of charge?
            Yes, WML can be distributed free of charge and used free of charge
            without any exceptions. You can even use WML to generate a
            commercial website, no problem.  But please give credit to the
            author where credit is due. Either by using wml::std::info(3)
            which includes a WML identifier or by explicitly saying somewhere
            on the generated website that you used WML. This just would be
            fair.

       G03: Why is WML a toolkit of disjunct programs instead of one big
       integrated program?
            The first reason is because WML was born out of the need to
            generate a huge webarea in spring 1997
            (http://www.engelschall.com/sw/) and an appropriate tool had to be
            found in finite time. So the author decided to use maximum
            software leverage and just compiled a toolkit of existing programs
            and only programmed the missing stuff itself.

            After this approach showed that WML is flexible and powerful
            enough as the solution to generate huge webareas, the author
            started to compactify it and stripped the toolkit to its essential
            parts. But it is still a toolkit, even when you have only one
            frontend to control the parts.

       G04: Which tools are included in the WML distribution?
            Well, you certainly know "wml", the front-end for WML.  But there
            are other cool front-ends for the most useful tasks:

            "wmk" - Website META Language Make
                Build your web pages without writing Makefiles.

            "wmd" - Website META Language Documentation Browser
                This is your visa for all the documentation you want.

            "wmb" - Website META Language Bug Reporting Tool
                The preferred way to report a bug, this tool will send a mail
                to the maintainer with your problem and the characteristics of
                your installation.

            "wmu" - Website META Language Upgrade Utility
                Upgrade and build new versions of WML like a charm, with the
                same options as those of your current installation.

       G05: WML is as powerful as it can, but are there even any restrictions?
            Sure, WML has some restrictions which cannot be eliminated easily.

            o there is no real debugging mode which makes tracing back of
              problems very hard, especially for the ePerl pass.  Currently
              the best way to debug is to use the -p option with args `1',
              then `12' then `123' etc.  and comparing the result in each
              step.

            o the WML language is very complex because of the 9 independent
              languages which are used intermixed. Because of this WML is not
              easy to understand and use for the average webdesigner.

       G06: Where do I find documentation?
            o Invoke the Documentation Browser by typing wmd and navigate
              through the installed documentation.

            o The WML Online documentation is located at

                http://www.engelschall.com/sw/wml/docs

              The webpages are the same as the ones viewed with wmd.

       G07: Is there any official support for WML?
            Yes, there is. First there is an official support mailing list for
            WML users:

              sw-wml@engelschall.com

            Here you can reach the WML author Ralf S. Engelschall, the current
            maintainer Denis Barbier, and the other people who use WML and
            which can help you in case of problems. Use this forum to spread
            your WML-related ideas and suggestion, too. Feel free to ask
            anything WML-related you want.

            To subscribe to this Majordomo-controlled mailing list, just send
            an E-mail to majordomo@engelschall.com with only

              subscribe sw-wml you@domain.dom

            in the body (leave the subject empty). After sending this,
            Majordomo will respond with an authentication challenge which has
            to send back again for security reasons (to avoid that others
            subscribe you without your ok). Now you are successfully
            subscribed to this list.

            Second you can directly contact Ralf S. Engelschall
            <rse@engelschall.com> or Denis Barbier <barbier@engelschall.com>
            via E-mail in case of very important problems.

       G08: How can I send a bug report to the author?
            You have four options:

            Bug Reporting Tool WMb
                This is the recommended way because it automatically includes
                all parameters of your WML installation in the bug report
                which (most of the time) is essentially for the author to be
                able to successfully solve your problem.  Just run the wmb
                program and enter your problem description. But make sure you
                have at least a workable E-mail link to the Internet, because
                WMb wants to send the bug report via E-mail to
                rse@engelschall.com.

            Bug Reporting Webpage
                This is the general bug report webpage on

                  http://www.engelschall.com/sw/bugreport/

                for all programs from Ralf S. Engelschall. Please include your
                `wml -V3' output, too.

            Mailing List
                This is the official support mailing list for WML which can be
                contacted via

                  sw-wml@engelschall.com

            Direct Contact
                This is the last chance, if all others failed. Just send your
                problem directly to the maintainer via barbier@engelschall.com

       G09: I really want to use WML for textprocessing because it's such
       powerful, isn't it?
            Yes, WML is, but only for HTML generation.

            Although WML provides a lot of hot features (like Slicing or
            Diversion) one often also wants for textprocessing, WML is not a
            general textprocessing language.  WML is HTML-dependend at a lot
            of edges and it lacks features which a text-processor really needs
            (like paragraph formatting, footnote support, etc). And even if
            you really decide to use WML for writing other stuff than HTML,
            you should be as crazy as you have time. Because WML is slow
            compared with any general textprocessing tool like TeX or even
            SGML-Tools. For its target format HTML this was and is never a
            problem, because the largest Webpage is never greater then
            approximately 10-100 KB. But for real textprocessing this size is
            peanuts.

            So, please don't think about using WML for text-processing, even
            if one of your primary target formats is HTML. Instead use a
            language like LaTeX2HTML, SDF or SGML-Tools to create the HTML
            format and only post-process this via WML. In other words: Use WML
            only for the dirty work of including the generated HTML stuff into
            your webpages. But don't think any longer about using WML as a
            text-processor.

   QUESTIONS ABOUT PASSES
       P01: How can I avoid conflicts with a particular WML pass?
            When you are sure you don't need this particular pass, you can use
            WML option -p and just leave out the number of the pass.

       P02: How can I avoid conflicts with a particular WML pass for only some
       areas of the input file?
            Use the internal "<protect>" container tag which entirely protects
            its body from evaluation by any pass. To protect the body from
            evaluation by a particular pass only, you can use "<protect
            pass=N>".

       P03: Is there a way to change pass order?
            Yes, since WML 1.7.3, you may change it with the -p flag. But you
            are warned this should be used by WML gurus only and for very
            particular reasons. For some internal reasons, processing will
            always stop after pass 9, even if you specify additional passes.
            This is a feature and is not subject to change on future releases.

       P04: Why shall I not change original pass order?
            WML has been designed to use passes in numerical order. This
            feature has a strong influence on how WML include files are
            written and there is no warranty these include files will still
            work when changing pass order.

   QUESTIONS ABOUT INCLUDE FILES
       I01: How can I install or activate my own include files?
            There are many ways, but the most elegant and useful way is the
            following: First create a directory named $HOME/.wml/ and then a
            directory named $HOME/.wml/home/ via

              $ cd $HOME
              $ mkdir .wml
              $ mkdir .wml/home

            Then create a $HOME/.wmlrc file with at least the following
            contents:

              -I .wml
              -D HOME~.

            Now just install your private include file foo.tmpl as
            $HOME/.wml/home/foo.tmpl and you are automatically be able to use
            it via

              #use tmpl::home::foo

            from within any WML source.

       I02: How can I overwrite the knowledge of the info-tag from
       wml::std:info?
            Because the "<info>" tag constructs its information out of
            "WML_GEN_XXXX" variables which theirself can be overwritten by the
            -D option, you can just do this in your $HOME/.wmlrc file. For
            instance the authors $HOME/.wmlrc file contains the following
            three lines:

              -D WML_GEN_REALNAME="Ralf S. Engelschall"
              -D WML_GEN_USERNAME=rse
              -D WML_GEN_HOSTNAME=engelschall.com

            The most important one here is "WML_SRC_HOSTNAME" for the
            construction of the email address. Because WML cannot know the
            email domainname we really have to help it here.

       I03: How can I combine the gfont- with the href-tag?
            Just put the "<gfont>" tag directly into the "name" attribute of
            "<href>":

              <href name="<gfont>The Hyperlink Text</gfont>"
                    url="http://...">

       I04: How can I combine the gfont- with the rollover-tag?
            Use "<gfont>"'s "notag" in combination with its "file" attribute
            as follows:

              <gfont file=button-n.gif bgcolor="#ffffff" notag>Text</gfont>
              <gfont file=button-o.gif bgcolor="#ccccff" notag>Text</gfont>
              <rollover src=button-n.gif oversrc=button-o.gif url="http://...">

   ERROR MESSAGES
       E01: Cannot load "/tmp/wml..." for unprotection
            One pass did not produce any output. This message certainly
            indicates a WML's bug, and so should be reported.

       E02: ePerl:Error: Perl runtime error
            An error occurred during pass 3 ("eperl"). The contents of the
            standard error channel is printed and may contain useful
            information for debugging.

SEE ALSO

       wml_intro(7), wml_tutorial(7), wml_tags(7), wml(1), wml::all(3).