Documentation: Core / WML

Introduction Frontends Backends Includes Auxilliaries
WML - Website META Language

NAME

WML - Website META Language

VERSION

2.0.11 (19-Aug-2006)

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





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 wml_p9_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


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:






        -o (ALL-LANG_*)+LANG_DE:%BASE.de.html





Data Protection Container Tag



WML provides an own internal container tag named <protect
[pass=SPEC]E<gt>...</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>
   </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>
   </protect>













AUTHORS


 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com




 Denis Barbier
 barbier@engelschall.com










SEEALSO


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