WML(1)

💖 WML — Website META Language 💖

okay bestie, sit down, hydrate, because this one is a whole toolkit and we're gonna get through it together 🫶

version: 2.32.0 — yes she has a version, she's official 👑

---

✨ 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 🌸

so. this is the control program of the Website META Language — aka WML — which is a free HTML generation toolkit for Unix, and internally it's literally 9 independent languages all vibing together. nine. languages. one command. the multitasking is giving main character energy fr 💅

the whole idea? a sequential filtering scheme where each of those 9 languages handles exactly one of 9 processing passes. so wml reads your inputfile (or from stdin if inputfile is a dash, or if it's just... not there at all 🙈), runs passes 1-9 on it — or only the passes you picked with -p — and then spits out one or more output files. that's the pipeline, that's the vibe. ✨

want the full lore? go read the WML Introduction under wml_intro(7) and the WML Tutorial under wml_tutorial(7). both iconic, both worth it 📚

---

🎀 OPTIONS 🎀

• -I, --include=PATH — adds a directory to the list of user include paths. use this one to set up the runtime environment for pass 1. more deets live in wml_p1_ipp(1) 💖
• -i, --includefile=PATH — pre-loads a specific include file, which basically means it virtually drops a

#include "PATH"

at the very top of inputfile. perfect for auto-including your default user include files. now, if you wanna include a system include file you gotta wrap the PATH in angle brackets — like use `"-i" "<foo/bar.wml>"` to pull in foo/bar.wml from the system include area. or you can use the special syntax `"wml::foo::bar"` exactly like you would with the #use directive. your choice, both slay 🦋

• -D, --define=NAME=STR — defines a variable, and that variable 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". and there's a special variant — --define=NAME=UNDEF — that does the opposite: it deletes previous definitions. and heads up, that may not be the same as just undefining those variables, e.g. with system defined variables. sneaky but useful 👀
• -D, --define=NAME~PATH — same energy as the above, except the variable holds a pathname that gets autoadjusted (see below). interpolates exactly the same ways as the "NAME=STR" variant up there ⬆️
• -n, --noshebang — forces WML to ignore a possibly contained shebang line in inputfile. usually WMk is the one using this, because WMk already parsed that line and handed the options over to WML itself. teamwork 🤝
• -r, --norcfile — forces WML to ignore all .wmlrc files. every single one. no cap 💀
• -c, --nocd — when WML processes an input file from another directory, it jumps into that directory before parsing .wmlrc files, then jumps back to the current directory after. but if this option is set, no directory change happens at all and .wmlrc files get read relative to the current working directory instead. (yes, "reative" is in the original, we're keeping the typo, it's canon now 🙈)
• -O, --optimize=NUM — the optimization option, passed directly to pass 8 (htmlfix). it controls how much optimization/stripping gets applied to the generated HTML markup code. less markup = more slay ✨
• -o, --outputfile=SLICETERM:outputfile[@CHMODOPT] — redirects the output to a file. normally the whole file goes to stdout (same as "ALL:-"). you can use this option more than once to output to more than one file, using the SLICETERM as a set theory term of slices to figure out which contents go into each particular output file. the optional CHMODOPT is for specifying options for a finally applied chmod command — for instance use `"u+x"` to create a file with the execution bit set (that's Apache's XBitHack feature, iykyk). see slice(1) for more details 👑
• -P, --prolog=PATH — runs a 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. that's the deal, no negotiating 🫶
• -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 honestly you can specify any program 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 actually want to modify output files. read that twice bestie.
• -t, --settime — sets the modification time of all output files to the modification time of intputfile plus 1 second. why? because webservers generate "Last-Modified" headers, and there the editing time matters more than the generation time. and that 1 second offset? it's for the dependencies of Makefiles. thoughtful, honestly 💅
• -M, --depend[=OPTIONS] — outputs a rule suitable for make describing the dependencies of each output file, exactly like gcc does. it only makes 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 actually get applied at 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 isn't part of STR, the resulting output gets written to STDOUT. default is the string `"1-9"` — so like, everything, by default 🌈
• -W, --passoption=NUM,STR — sets option STR for the pass NUM. that's it, that's the whole thing 🎯
• -s, --safe — this disables some Perl hacks inside WML that speed up 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 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. and yeah, experience showed it works great — but the theoretical problem is still there: this approach is somewhat risky due to internal Perl variable conflicts. 😭

so use this option to disable those speedups and force WML to use the safe "fork()" approach instead. safety first, bestie 🛡️

• -v, --verbose[=NUM] — sets verbose mode (from 1 to 9), where some processing information gets shown on the console. so 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 — sets quiet mode, where the processing prop is no longer displayed. use this when running wml as a batch job. and fun fact: this option is automatically forced when inputfile is missing — in that case WML automatically reads from stdin in quiet mode. she's polite like that 🎀
• -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 to get a brief description of your installed WML system — especially when reporting bugs to the author. they need the receipts, bestie 🧾
• -h, --help — prints the usage summary page. the classic. the icon 💖

---

🌈 ENVIRONMENT 🌈

DEFINED VARIABLES

these variables are always defined by wml at runtime, and are usually interpolated via <"get-var NAME"> inside Pass 2 and via $NAME in Pass 3. so many of them. all yours. enjoy 💅

• 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. super useful when running wml on a bulk of files and include files 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. clean ✂️
• WML_SRC_TIME — the last modification time of inputfile in "time()" format. useful inside footers when a 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 a 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. so meta of her 💖

USED VARIABLES

• "WMLOPTS" — this variable can contain a string of options. usually it's 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. set it once, forget it, live your life ✨

• "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'. 🗂️

---

<div align="center">✨ 🎀 🦋 to be continued, bestie 🦋 🎀 ✨</div>

📂 USER FILES 💖

Okay so bestie, you also got these 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. Slay.

🎀 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).

---

That's the whole vibe check, bestie. This iconic page is from EN Tools, dated 2020-11-29, and it's WML(1) — periodt. 💅✨