WML FAQ - Frequently Asked Questions on WML
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?
- 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 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://...">