NAME¶
WML - Website META Language
VERSION¶
2.0.12 (16-Apr-2008)
SYNOPSIS¶
wml [
-I PATH] [
-i PATH] [
-D
NAME =STR] [
-D NAME~PATH] [
-n] [
-r] [
-O level] [
-o
[
SLICETERM":"]
PATH[
@CHMODOPT]] [
-P PATH] [
-E PATH] [
-t] [
-p
STR] [
-W STR] [
-s] [
-v [
NUM]] [
-q] [
inputfile]
wml [
-V [
NUM]] [
-h]
DESCRIPTION¶
This is the control program of the
Website META Language (WML), a free
HTML generation toolkit for Unix, internally consisting of 9 independent
languages.
The main idea of WML is a sequential filtering scheme where each language
provides one of 9 processing passes. So
wml reads
inputfile (or
from
stdin if
inputfile is a dash or completely missing),
applies passes 1-9 (or only the passes specified by
-p) and finally
produces one or more
outputfiles.
For more details on this processing scheme read the
WML Introduction
under
wml_intro(7) and the
WML Tutorial under
wml_tutorial(7).
OPTIONS¶
- -I, --include=PATH
- Adds a directory to the list of user include paths.
Use this option to set the runtime environment for pass 1. See
wml_p1_ipp(3) for more details.
- -i, --includefile=PATH
- Pre-loads a particular include file, i.e. virtually
adds a
#include "PATH"
at the top of inputfile. Use this to automatically include default
user include files. If you want to include a systems include file you have
to surround the PATH with angle brackets, for instance use
``"-i" "<foo/bar.wml>"'' to include the file
foo/bar.wml from the system include area. Alternatively you can use
the special syntax ``"wml::foo::bar"'' as with the
"#use" directive.
- -D,
--define=NAME=STR
- Defines a variable which can be interpolated in pass 1
(IPP) via "$(NAME)", in pass 2 (mp4h) via <"get-var
NAME">, in pass 3 (ePerl) via "<:=$NAME:>" and in
pass 4 (GNU m4) via "m4_NAME". A special variant
--define= NAME=UNDEF does the opposite, it deletes
previous definitions (which may be different than undefining these
variables, e.g. with system defined variables).
- -D,
--define=NAME~PATH
- Similar to the above but defines a variable holding a
pathname which is autoadjusted (see below). It can be interpolated in the
same ways as the "NAME=STR" variant from above.
- -n, --noshebang
- This forces WML to ignore a possibly contained shebang line
in inputfile. This is usually used by WMk, because WMk already
parsed this line and supplied the options to WML.
- -r, --norcfile
- This forces WML to ignore all .wmlrc files.
- -c, --nocd
- When WML processes an input file from another directory, it
jumps into that directory before parsing .wmlrc files, and jump
back to current directory after. If this option is set, no directory
change is made and .wmlrc files are read reative to current working
directory.
- -O, --optimize=NUM
- This is the optimization option which is passed directly to
pass 8 ( htmlfix). It controls the amount of optimization/stripping
which is applied to the generated HTML markup code.
- -o,
--outputfile=SLICETERM:outputfile[
@CHMODOPT]
- This redirects the output to a file. Usually the whole file
will be send to stdout (same as "ALL:-"). You can use
this option more than once to output to more than one file while using the
SLICETERM as a set theory term of slices to determine which
contents will be included into each particular output file. The optional
CHMODOPT is intended for specifying options for a finally applied
chmod command. For instance use ``"u+x"'' to create a
file with the execution bit set (Apache's XBitHack feature). See
slice(1) for more details.
- -P, --prolog=PATH
- Runs an prolog filter over the input file. This program
receives the data to act on as STDIN and has to produce the filtered data
on STDOUT.
- -E, --epilog=PATH
- Runs an epilogue program over the finally resulting output
files. Currently the following WML-specific programs are known:
htmlinfo, linklint, tidy and weblint. But you
can specify any program which is available in your "PATH". This
program receives the file to act on as its first command line argument.
Notice that output is not redirected to this file, so you have to use a
wrapper or program specific flags if you want to modify output files.
- -t, --settime
- This sets the modification time of all output files to the
modification time of intputfile plus 1 second. This is useful
because Webservers will generate "Last-Modified" headers and
there the editing time is more important than the generation time. The 1
second offset is for the dependencies of Makefiles.
- -M, --depend[=OPTIONS]
- Output a rule suitable for `make' describing the
dependencies of each output file, as `gcc' does. It has only sense when
the -o option is used. No processing is done except for the first
pass.
The D flag option writes the rule to a dependency file. The name of
this file is obtained by replacing the suffix of the output file by
".d".
The M flag option deletes the system files from the list of
dependencies.
- -p, --pass=STR
- Specifies which of the passes described above are actually
applied under runtime. The argument STR is a comma-separated list
of pass numbers with one special case: You can write "X-Y" for
all passes "X...Y". When pass 9 is not part of STR the
resulting output is written to STDOUT. Default is the string
``"1-9"''.
- -W, --passoption=NUM,STR
- Set option STR for the pass NUM.
- -s, --safe
- This disables some Perl hacks inside WML which speedup
processing by reducing the forking overhead when running the various
passes.
Without this option WML pre-compiles the passes 1,5,6,7,8 (which are written
in Perl!) into a different namespace of the currently running Perl
interpreter instead of running them externally via "system()".
The effect is that these programs are run from within the same Perl
interpreter thus saving five CPU- and time-intensive "fork()"'s.
The actual gain is between 2 and 4 seconds of processing time. Although
experience showed that it works great, the theoretical problem still is,
that this approach is somewhat risky due to internal Perl variable
conflicts.
Use this option to disable these speedups by forcing WML to use the safe
"fork()" approach.
- -v, --verbose[=NUM]
- This sets verbose mode (from 1 to 9) where some processing
information will be given on the console. Useful for debugging. This
option also gets passed to some of the filtering programs. Default is no
verbosity and just -v means -v1.
- -q, --quiet
- This sets quiet mode where the processing prop is no longer
displayed. Use this option when running wml as a batch job. This
option is automatically forced when inputfile is missing. Then WML
automatically reads from stdin in quiet mode.
- -V, --version[=NUM]
- Gives the version identification string and disclaimer (no
NUM or NUM >= 1), the WML build information ( NUM
>= 2) and the Perl build information ( NUM >= 3). Use this
option to get a brief description of your installed WML system, especially
when reporting bugs to the author.
- -h, --help
- Prints the usage summary page.
ENVIRONMENT¶
DEFINED VARIABLES¶
The following variables are always defined by
wml under runtime and are
usually interpolated via <"get-var NAME"> inside Pass 2 and
via $NAME in Pass 3.
- WML_SRC_DIRNAME
- The current working directory from where wml was
started. An absolute Unix filesystem path.
- WML_SRC_FILENAME
- The name of the inputfile from the command line.
Useful when running wml on a bulk of files and includefiles have to
determine in which they are included.
- WML_SRC_BASENAME
- The basename of the inputfile, i.e. the
"WML_SRC_FILENAME", but with the extension already
stripped.
- WML_SRC_TIME
- The last modification time of inputfile in
"time()" format. Useful inside footers when customized date
format is needed.
- WML_SRC_CTIME
- The last modification time of inputfile in
"ctime()" format. Useful inside footers include files.
- WML_SRC_ISOTIME
- The last modification time of inputfile in ISO
"yyyy-mm-dd hh:mm:ss" format. Useful inside footers include
files.
- WML_SRC_USERNAME
- The Unix username of the user who own
inputfile.
- WML_SRC_REALNAME
- The realname of the user who own inputfile.
- WML_GEN_TIME
- The current time of generation in "time()"
format. Useful inside footers when customized date format is needed.
- WML_GEN_CTIME
- The current time of generation in "ctime()"
format. Useful inside footers include files.
- WML_GEN_ISOTIME
- The current time of generation in ISO "yyyy-mm-dd
hh:mm:ss" format. Useful inside footers include files.
- WML_GEN_USERNAME
- The Unix username of the user who runs the wml
process.
- WML_GEN_REALNAME
- The realname of the user who runs the wml
process.
- WML_GEN_HOSTNAME
- The name of the host on which the wml command
runs.
- WML_LOC_PREFIX
- The location prefix where WML was installed to at built
time.
- WML_LOC_BINDIR
- The directory where WML's binaries were installed to at
built time.
- WML_LOC_LIBDIR
- The directory where WML's library files were installed to
at built time.
- WML_LOC_DATADIR
- The directory where WML's data files were installed to at
built time.
- WML_LOC_MANDIR
- The directory where WML's manual pages were installed to at
built time.
- WML_VERSION
- The version identification string of WML. Use this for
instance in HTML comments inside header includes to identify the
generation tools version.
USED VARIABLES¶
- "WMLOPTS"
- This variable can contain a string of options. Usually this
is used by Bourne-Shell users like
$ WMLOPTS="-DNAME1=VALUE2 -DNAME2=VALUE2"
$ export WMLOPTS
and by C-Shell users like
$ setenv WMLOPTS "-DNAME1=VALUE2 -DNAME2=VALUE2"
to make sure some variables are defined for all runs of wml.
- "PAGER"
- This variable contains the pager WML is to use. WML uses a
pager when called with the --verbose=NUM or
-vNUM option respectively and NUM is 3 or higher and
therefore showing the processed data after each pass. Default is
'more'.
- "TMPDIR"
- This variable contains the directory WML stores its
temporary files in. Default is '/tmp'.
USER FILES¶
- $HOME/.wmlrc and
(../)*.wmlrc
- These files can also contain option strings, one option per
line. Usually the contents is one or more -D options, especially
auto-adjusted ones:
-DROOTREL~.
-DROOTABS=http://thishost/thisarea/
:
-DNAME1=VALUE1
-DNAME2=VALUE2
:
STANDARD INCLUDE FILES¶
WML is shipped with a standard set of include files. You can directly include
them via
#use wml::category::name
and read their own documentation via
$ man wml::category::name
See
wml::all(3) for a description of all available include files.
SPECIAL FEATURES¶
The WML control frontend provides a few special features on its own:
- Shebang Line Support
- WML recognizes a shebang line (``"#!wml"
options'') in the .wml files and automatically adds
options to its command line. This line is also used by WMk. Two
special features in contrast to shebang lines for the Unix loader are
available: WML's shebang line can be continued via a backslash character
and the constructs %DIR and %<BASE> are interpolated (where %DIR is
the path to the directory the source while resides and %BASE is the
filename of the source file without any extension).
Example:
#!wml -o (ALL-LANG_*)+LANG_EN:%BASE.en.html \
-o (ALL-LANG_*)+LANG_DE:%BASE.de.html
- Data Protection Container Tag
- WML provides an own internal container tag named
"<protect [pass=SPEC]>"..."</protect>"
which can be used to protect any type of data from being processed by any
WML pass. When no "pass" attribute is given SPEC defaults
to "1-9". When you use "pass" then SPEC can be
either "#-", "-#", "#-#" or a comma
separated list of passes, while "#" can be between 1 and 9.
Example:
<script language="JavaScript">
<protect pass=2>
...
output = "<PRE><DIV ALIGN=\"CENTER\"><B>" + help_string + "</B></DIV></PRE>"
...
</protect>
</script>
Warning:
Since WML 2.0.3, pass 1 includes extra stuff to help keeping information
about line numbers relevant (a la cpp). So when writing
<protect pass=2>
#include 'foo'
</protect>
these extra commands will not be interpreted during pass 2 and will remain
on output. To suppress them, either compile with "-W1,-N" flag,
or write
<protect pass=2>
#include 'foo' IPP_NOSYNCLINES
</protect>
AUTHORS¶
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
Denis Barbier
barbier@engelschall.com
SEE ALSO¶
wmd(1),
wml_faq(7),
wml_intro(7),
wml_tutorial(7),
wml_tags(7),
wml::all(3).