Ubuntu Manpage: WML - Website META Language

NAME

       WML - Website META Language

VERSION

       2.12.2

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(1) 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_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