README(1)

📦 version 0.4.11, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 README(1) — Html2Wml Documentation 🌸

okay bestie, sit down, grab a strawberry, because we're about to learn Html2Wml — the program that can convert HTML pages to WML pages 💅

✨ NAME ✨

Html2Wml — a program that can convert HTML pages to WML pages. that's it, that's the whole job, and it ate.

✨ SYNOPSIS ✨

Html2Wml can be used as either a shell command:

$ html2wml file.html

or as a CGI:

/cgi-bin/html2wml.cgi?url=/index.html

In both cases, the file can be either a local file or a URL. yes queen, flexible 🦋

✨ DESCRIPTION ✨

Html2Wml converts HTML pages to WML decks, suitable for being viewed on a Wap device. The program can be launched from a shell to statically convert a set of pages, or as a CGI to convert a particular (potentially dynamic) HTML resource. lowkey two icons in one 💖

Althought the result is not guarantied to be valid WML, it should be the case for most pages. Good HTML pages will most probably produce valid WML decks. To check and correct your pages, you can use W3C's software: the HTML Validator, available online at http://validator.w3.org, and HTML Tidy, written by Dave Raggett. validation besties stay winning ✨

Html2Wml provides the following features:

  • translation of the links
  • limitation of the cards size by splitting the result into several cards
  • inclusion of files (similar to the SSI)
  • compilation of the result (using the WML Tools, see the section on "LINKS")
  • a debug mode to check the result using validation functions

it's giving feature-rich. periodt. 💅

✨ OPTIONS ✨

Please note that most of these options are also available when calling Html2Wml as a CGI. In this case, boolean options are given the value "1" or "0", and other options simply receive the value they expect. For example, --ascii becomes ?ascii=1 or ?a=1. See the file t/form.html for an example on how to call Html2Wml as a CGI. 👑

🌈 Conversion Options 🌈

  • -a, --ascii — When this option is on, named HTML entities and non-ASCII characters are converted to US-ASCII characters using the same 7 bit approximations as Lynx. For example, © is translated to "(c)", and ß is translated to "ss". This option is off by default.
  • --[no]collapse — This option tells Html2Wml to collapse redundant whitespaces, tabulations, carriage returns, lines feeds and empty paragraphs. The aim is to reduce the size of the WML document as much as possible. Collapsing empty paragraphs is necessary for two reasons. First, this avoids empty screens (and on a device with only 4 lines of display, an empty screen can be quite ennoying). Second, Html2wml creates many empty paragraphs when converting, because of the way the syntax reconstructor is programmed. Deleting these empty paragraphs is necessary like cleaning the kitchen :-) 🧚

If this really bother you, you can deactivate this behaviour with the --nocollapse option.

  • --ignore-images — This option tells Html2Wml to completely ignore all image links. bye bye pictures 🫶
  • --[no]img-alt-text — This option tells Html2Wml to replace the image tags with their corresponding alternative text (as with a text mode web browser). This option is on by default.
  • --[no]linearize — This option is on by default. This makes Html2Wml flattens the HTML tables (they are linearized), as Lynx does. I think this is better than trying to use the native WML tables. First, they have extremely limited features and possibilities compared to HTML tables. In particular, they can't be nested. In fact this is normal because Wap devices are not supposed to have a big CPU running at some zillions-hertz, and the calculations needed to render the tables are the most complicated and CPU-hogger part of HTML. 😭

Second, as they can't be nested, and as typical HTML pages heavily use imbricated tables to create their layout, it's impossible to decide which one could be kept. So the best thing is to keep none of them.

[Note] Although you can deactivate this behaviour, and although there is internal support for tables, the unlinearized mode has not been heavily tested with nested tables, and it may produce unexpected results. 💀
  • -n, --numeric-non-ascii — This option tells Html2wml to convert all non-ASCII characters to numeric entities, i.e., "e" becomes é, and "ss" becomes ß. By default, this option is off.
  • -p, --nopre — This options tells Html2Wml not to use the <pre> tag. This option was added because the compiler from WML Tools 0.0.4 doesn't support this tag. rude of it tbh 🙈
  • --hreftmpl=TEMPLATE — This options sets the template that will be used to reconstruct the href-type links. See the section on "LINKS RECONSTRUCTION" for more information.
  • --srctmpl=TEMPLATE — This option sets the template that will be used to reconstruct the src-type links. See the section on "LINKS RECONSTRUCTION" for more information.

🌈 Splitting Options 🌈

  • -s, --max-card-size=SIZE — This option allows you to limit the size (in bytes) of the generated cards. Default is 1,500 bytes, which should be small enough to be loaded on most Wap devices. See the section on "DECK SLICING" for more information.
  • -t, --card-split-threshold=SIZE — This option sets the threshold of the split event, which can occur when the size of the current card is between max-card-size - card-split-threshold and max-card-size. Default value is 50. See the section on "DECK SLICING" for more information.
  • --next-card-label=STRING — This options sets the label of the link that points to the next card. Default is "[&gt;&gt;]", which whill be rendered as "[>>]". 👉
  • --prev-card-label=STRING — This options sets the label of the link that points to the previous card. Default is "[&lt;&lt;]", which whill be rendered as "[<<]". 👈

🌈 HTTP Authentication 🌈

  • -U, --http-user=USERNAME — Use this option to set the username for an authenticated request. 🕵️
  • -P, --http-passwd=PASSWORD — Use this option to set the password for an authenticated request. shhh bestie, that's secret 🤫

🌈 Proxy Support 🌈

  • -[no]Y, --[no]proxy — Use this option to activate proxy support. By default, proxy support is activated. See the section on "PROXY SUPPORT".

🌈 Output Options 🌈

  • -k, --compile — Setting this option tells Html2Wml to use the compiler from WML Tools to compile the WML deck. If you want to create a real Wap site, you should seriously use this option in order to reduce the size of the WML decks. Remember that Wap devices have very little amount of memory. If this is not enough, use the splitting options. 🔥

Take a look in wml_compilation/ for more information on how to use a WML compiler with Html2Wml.

  • -o, --output — Use this option (in shell mode) to specify an output file. By default, Html2Wml prints the result to standard output.

🌈 Debugging Options 🌈

  • -d, --debug[=LEVEL] — This option activates the debug mode. This prints the output result with line numbering and with the result of the XML check. If the WML compiler was called, the result is also printed in hexadecimal an ascii forms. When called as a CGI, all of this is printed as HTML, so that can use any web browser for that purpose. main character energy, honestly 🔍
  • --xmlcheck — When this option is on, it send the WML output to XML::Parser to check its well-formedness. ✨

to be continued, bestie… part 2 is coming 💜

✨ DECK SLICING ✨

okay so bestie, picture this: most Wap devices are out here running on, like, no memory 😭. A lot of them literally cannot handle cards bigger than 2,000 bytes. So for your cards to be viewable on every Wap device, they gotta be small enough. Deck slicing is the Html2Wml feature built exactly for this vibe check.

So what you do is compile your WML deck — that alone shrinks the deck by 50% — but even then your cards might still be too thicc. And that's where deck slicing comes in: it lets you limit the size of the cards. Currently this only works before the compilation stage, just so you know. 🎀

🌸 Slice by cards or by decks 🌸

Some Wap phones are extra, ngl. On those, slicing the deck is not sufficient — the WML browser still tries to download the whole entire deck instead of just grabbing one card at a time. The glow-up fix? Slice the WML document by decks. See the figure below, she's iconic:

     _____________          _____________
    ⎪    deck     ⎪        ⎪   deck #1   ⎪
    ⎪  _________  ⎪        ⎪  _________  ⎪
    ⎪ ⎪ card #1 ⎪ ⎪        ⎪ ⎪  card   ⎪ ⎪
    ⎪ ⎪_________⎪ ⎪        ⎪ ⎪_________⎪ ⎪
    ⎪  _________  ⎪        ⎪_____________⎪
    ⎪ ⎪ card #2 ⎪ ⎪
    ⎪ ⎪_________⎪ ⎪             . . .
    ⎪  _________  ⎪
    ⎪ ⎪   ...   ⎪ ⎪         _____________
    ⎪ ⎪_________⎪ ⎪        ⎪   deck #n   ⎪
    ⎪  _________  ⎪        ⎪  _________  ⎪
    ⎪ ⎪ card #n ⎪ ⎪        ⎪ ⎪  card   ⎪ ⎪
    ⎪ ⎪_________⎪ ⎪        ⎪ ⎪_________⎪ ⎪
    ⎪_____________⎪        ⎪_____________⎪

      WML document           WML document
    sliced by cards        sliced by decks

What this means, fr fr: Html2Wml generates several WML documents. In CGI mode, only the appropriate deck gets sent, selected by the id you give in the parameter. And if no id was given? The first deck gets sent. Simple as. 💅

🦋 Note on size calculation 🦋

Right now, Html2Wml estimates the size of the card on the fly, by summing up the length of the strings that make up the WML output — texts and tags. Notice I said "estimates" and not "calculates" 👀 because computing the exact size would take so many more calculations than the way it's done now.

Now someone might be like "but bestie, there are only additions happening, that's correct" — and yes, that's true, but knowing the exact size isn't actually necessary. Because when you compile the WML, most of the strings of the tags get removed... but not all of them.

For example, take an image tag: <img src="images/dog.jpg" alt="Photo of a dog">. When it's compiled, the string "img" gets replaced by a one byte value. Same energy for the strings "src" and "alt", and the spaces, double quotes and equal signs all get stripped. Only the text between double quotes gets preserved... but not in every case. Because to go a step further, the compiler can also encode parts of the arguments as binary. Like, the string "http://www." can be encoded as a single byte (8F in this case). Or, if the attribute is href, the string href="http:// can become the byte 4B.

So as you can see, it genuinely doesn't matter to know the exact size of the textual form of the WML, because it will always be far superior to the size of the compiled form. That's why all the characters that may actually be written don't get counted. 🫶

Also it's because I'm quite lazy ;-)

👑 Why compiling the WML deck? 👑

If you intend to create real WML pages, you should really consider always compiling them. Not convinced? Here's an illustration, bestie.

Take the following WML code snipet:

<a href='http://www.yahoo.com/'>Yahoo!</a>

It's the basic and classical way to code an hyperlink, and it takes 42 bytes to code this, because it's presented in a human-readable form.

The WAP Forum has defined a compact binary representation of WML in its specification, which is called "compiled WML". It's a binary format, so you — a mere human — can't read that, but your computer can. And it's much faster for it to read a binary format than to read a textual format. Slay.

The previous example would be, once compiled (and printed here as hexadecimal):

1C 4A 8F 03 y a h o o 00 85 01 03 Y a h o o ! 00 01

This only takes 21 bytes. Half the size of the human-readable form. For a Wap device, this means both less to download, and easier things to read. So the processing of the document can be achieved in a short time compared to the textual version of the same document. 🌈

And there's a last argument, and not the less important one: many Wap devices only read binary WML. periodt.

💜 ACTIONS 💜

Actions are a feature similar to (but with far less functionalities!) the SSI (Server Side Includes) you get on good servers like Apache. And in order not to interfere with the real SSI, but to keep the syntax easy to learn, it differs in very few points.

✨ Syntax ✨

Basically, the syntax to execute an action is:

<!-- [action param1="value" param2='value'] -->

Note that the angle brackets are part of the syntax. Except for that one point, Actions syntax is very similar to SSI syntax. iykyk.

🎀 Available actions 🎀

Only few actions are currently available, but more can be implemented on request. 💖

include

  • Description — Includes a file in the document at the current point. Please note that Html2Wml doesn't check nor parse the file, and if the file cannot be found, will silently die 💀 (this is the same behavior as SSI).
  • Parameters
    • virtual=url — The file is get by http.
    • file=path — The file is read from the local disk.

fsize

  • Description — Returns the size of a file at the current point of the document.
  • Parameters
    • virtual=url — The file is get by http.
    • file=path — The file is read from the local disk.
  • Notes — If you use the file parameter, an absolute path is recommend.

skip

  • Description — Skips everything until the first end_skip action.

🌸 Generic parameters 🌸

The following parameters can be used for any action.

  • for=output format — This parameter restricts the action for the given output format. Currently, the only available format is "wml" (when using html2chtml the format is "chtml").

🦋 Examples 🦋

If you want to share a navigation bar between several WML pages, you can include it this way:

<!-- [include virtual="nav.wml"] -->

Of course, you have to write this navigation bar first :-)

If you want to use your current HTML pages for creating your WML pages, but they contain complex tables, or unnecessary navigation tables, etc, you can simply skip the complex parts and keep the rest.

<body>
<!--[skip for="wml"]-->
unnecessary parts for the WML pages
<!--[end_skip]-->
useful parts for the WML pages
</body>

The links reconstruction engine is IMHO the most important part of Html2Wml, because it's this engine that lets you reconstruct the links of the HTML document being converted. It has two modes, depending on whether Html2Wml was launched from the shell or as a CGI. 👑

When used as a CGI, this engine will reconstructs the links of the HTML document so that all the urls will be passed to Html2Wml in order to convert the pointed files (pages or images). This is completely automatic and can't be customized for now (but I don't think it would be really useful).

When used from the shell, this engine reconstructs the links with the given templates. Note that absolute URLs will be left untouched. The templates can be customized using the following syntax.

💅 Templates 💅

  • HREF Template — This template controls the reconstruction of the href attribute of the A tag. Its value can be changed using the --hreftmpl option. Default value is "{FILEPATH}{FILENAME}{$FILETYPE =~ s/s?html?/wml/o; $FILETYPE}".
  • Image Source Template — This template controls the reconstruction of the src attribute of the IMG tag. Its value can be changed using the --srctmpl option. Default value is "{FILEPATH}{FILENAME}{$FILETYPE =~ s/gif⎪png⎪jpe?g/wbmp/o; $FILETYPE}"

✨ Syntax ✨

The template is a string that contains the new URL. More precisely, it's a Text::Template template. Parameters can be interpolated as a constant or as a variable. The template is embraced between curcly bracets, and can contain any valid Perl code.

The simplest form of a template is {PARAM} which just returns the value of PARAM. If you want to do something more complex, you can use the corresponding variable; for example {"foo $PARAM bar"}, or {join "_", split " ", PARAM}.

You may read the Text::Template manpage for more information on what is possible within a template. 📖

If the original URL contained a query part or a fragment part, then they will be appended to the result of the template.

🌈 Available parameters 🌈

  • URL — This parameter contains the original URL from the href or src attribute.
  • FILENAME — This parameter contains the base name of the file.
  • FILEPATH — This parameter contains the leading path of the file.
  • FILETYPE — This parameter contains the suffix of the file.

This can be resumed this way:

 URL = http://www.server.net/path/to/my/page.html
                            ------------^^^^ ----
                                ⎪        ⎪     \
                                ⎪        ⎪      \
                             FILEPATH FILENAME FILETYPE

Note that FILETYPE contains all the extensions of the file, so if its name is index.html.fr for example, FILETYPE contains ".html.fr". 🙈

🎀 Examples 🎀

To add a path option:

{URL}$wap

Using Apache, you can then add a Rewrite directive so that URL ending with $wap will be redirected to Html2Wml:

RewriteRule  ^(/.*)\$wap$  /cgi-bin/html2wml.cgi?url=$1

To change the extension of an image:

{FILEPATH}{FILENAME}.wbmp

🌸 PROXY SUPPORT 🌸

okay so Html2Wml is lowkey plugged into LWP's built-in proxy support, and it's on by default bestie, no setup needed. It just reads the proxy settings out of your environment variables, using the exact same variable names that a million other programs use. Every protocol (http, ftp, etc) can get its own proxy server by setting a variable shaped like PROTOCOL_proxy. So like, http_proxy defines the proxy for http access, ftp_proxy for ftp access. In the shell it's literally just... defining the variable. that's it. that's the whole thing 💅

For Bourne shell:

$ export http_proxy="http://proxy.domain.com:8080/"

For C-shell:

% setenv http_proxy "http://proxy.domain.com:8080/"

And under Apache, you can drop this directive into your config file:

SetEnv http_proxy "http://proxy.domain.com:8080"
but ngl this one has a catch: another CGI, or another program, can use this to access external resources. so a better way is to edit Html2Wml itself and fill the proxy-server option with the appropriate value. cleaner. safer. periodt. 🫶

💀 CAVEATS 💀

Html2Wml really does try to make correct WML documents, but bestie, the well-formedness and the validity of the document are not guarantied. like, no promises, okay? 😭

Inverted tags — the classic "<b>bold <i>italic</b></i>" situation — may produce unexpected results. But only bad software does bad stuff like this, so. 🤷♀️

🎀 Download 🎀

✨ Html2Wml ✨

This is the web site of the Html2Wml project, hosted by SourceForge.net. All the stable releases can be downloaded from this site.

http://www.html2wml.org/

✨ Nutialand ✨

This is the web site of the author, where you can find the archives of all the releases of Html2Wml.

http://www.maddingue.org/softwares/

🎀 Resources 🎀

✨ The WAP Forum ✨

This is the official site of the WAP Forum. You can find some technical information there, like the specifications of all the technologies associated with the WAP.

http://www.wapforum.org/

✨ WAP.com ✨

This site has some useful information and links. In particular, it has a quite well done FAQ.

http://www.wap.com/

✨ The World Wide Web Consortium ✨

Although not directly related to the Wap stuff, you may find it useful to read the specifications of XML (WML is an XML application), and the specifications of the different stylesheet languages (CSS and XSL), which include support for low-resolution devices.

http://www.w3.org/

✨ TuxMobil ✨

This web site is dedicated to Mobile UniX systems. It leads you to a lot of useful hands-on information about installing and running Linux and BSD on laptops, PDAs and other mobile computer devices.

http://www.tuxmobil.org/

🎀 Programmers utilities 🎀

✨ HTML Tidy ✨

This is a very handful utility which corrects your HTML files so that they conform to W3C standards.

http://www.w3.org/People/Raggett/tidy

✨ Kannel ✨

Kannel is an open source Wap and SMS gateway. A WML compiler is included in the distribution.

http://www.kannel.org/

✨ WML Tools ✨

This is a collection of utilities for WML programmers. This include a compiler, a decompiler, a viewer and a WBMP converter.

http://pwot.co.uk/wml/

🎀 WML browsers and Wap emulators 🎀

✨ Opera ✨

Opera is originaly a Web browser, but the version 5 has a good support for XML and WML. Opera is available for free for several systems.

http://www.opera.com/

✨ wApua ✨

wApua is an open source WML browser written in Perl/Tk. It's easy to install and to use. Its support for WML is incomplete, but sufficient for testing purpose.

http://fsinfo.cs.uni-sb.de/~abe/wApua/

✨ Tofoa ✨

Tofoa is an open source Wap emulator written in Python. Its installation is quite difficult, and its incomplete WML support makes it produce strange results, even with valid WML documents.

http://tofoa.free-system.com/

✨ EzWAP ✨

EzWAP, from EZOS, is a commercial WML browser freely available for Windows 9x, NT, 2000 and CE. Compared to others Windows WML browsers, it requires very few resources, and is quite stable. Its support for the WML specs seems quite complete. A very good software. 👑

http://www.ezos.com/

✨ Deck-It ✨

Deck-It is a commercial Wap phone emulator, available for Windows and Linux/Intel only. It's a very good piece of software which really show how WML pages are rendered on a Wap phone, but one of its major default is that it cannot read local files. 😭

http://www.pyweb.com/tools/

✨ Klondike WAP Browser ✨

Klondike WAP Browser is a commercial WAP browser available for Windows and PocketPC.

http://www.apachesoftware.com/

✨ WinWAP ✨

WinWAP is a commercial Wap browser, freely available for Windows.

http://www.winwap.org/

✨ WAPman ✨

WAPman from EdgeMatrix, is a commercial WAP browser available for Windows and PalmOS.

http://www.edgematrix.com/edge/control/MainContentBean?page=downloads

✨ Wireless Companion ✨

Wireless Companion, from YourWap.com, is a WAP emulator available for Windows.

http://www.yourwap.com/

✨ Mobilizer ✨

Mobilizer is a Wap emulator available for Windows and Unix.

http://mobilizer.sourceforge.net/

✨ QWmlBrowser ✨

QWmlBrowser (formerly known as WML BRowser) is an open source WML browser, written using the Qt toolkit.

http://www.wmlbrowser.org/

✨ Wapsody ✨

Wapsody, developed by IBM, is a freely available simulation environment that implements the WAP specification. It also features a WML browser which can be run stand-alone. As Wapsody is written in Java/Swing, it should work on any system.

http://alphaworks.ibm.com/aw.nsf/techmain/wapsody

✨ WAPreview ✨

WAPreview is a Wap emulator written in Java. As it uses an HTML based UI and needs a local web proxy, it runs quite slowly.

http://wapreview.sourceforge.net

✨ PicoWap ✨

PicoWap is a small WML browser made by three French students. 🇫🇷

http://membres.lycos.fr/picowap/

🫶 ACKNOWLEDGEMENTS 🫶

  • Werner Heuser, for his numerous ideas, advices and his help for the debugging 🐛
  • Igor Khristophorov, for his numerous suggestions and patches
  • And all the people that send me bug reports: Daniele Frijia, Axel Jerabek, Ouyang — absolute icons, every single one of them 💖

👑 AUTHOR 👑

Sebastien Aperghis-Tramoni <sebastien@aperghis.net<gt>

Copyright (C)2000, 2001, 2002 Sebastien Aperghis-Tramoni

This program is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License, version 2 or later. periodt. ✨

and that's the whole thing bestie, we ate 🍓 this page came to you from the 3rd Berkeley Distribution, version 0.4.11, as README(1) — go forth and convert HTML to WML, you main character 👑💅🦋

📦 where this page comes from