Ubuntu Manpage: WML FAQ - Frequently Asked Questions on WML

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

<https://thewml.github.io/>

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 shlomif@shlomifish.org .

Bug Reporting Webpage
This is the general bug report webpage on

<https://github.com/thewml/website-meta-language/issues>

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:

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.

NAME

DESCRIPTION

SEE ALSO