Language Reference

MHTML Language Reference Anderson Santana de Oliveira, Christophe Masson August 31, 2005 Abstract MHTML stands for Modular HyperText Markup Language. As its name implies, it is an extension of HTML and XHTML that introduces modularity in those languages as a pre-processing stage, consequently preserving compatibility with W3C standards. To fulfil this goal, MHTML extends the host language with a set of markups that are fully XML-compliant. Internally, MHTML heavily relies on TOM available at http://tom.loria.fr and lies on the works of Ms. H´el`ene KIRCHNER, Mr. Claude KIRCHNER and Mr. Anderson SANTANA DE OLIVEIRA.

1

An MHTML file

An MHTML file is a text file containing specific MHTML language constructs as well as classic HTML or XHTML markups. The name of an MHTML file must always end with the “.mhtml” (without double quotes) extension. Each MHTML file has “module” as its root element which takes the filename as its “name” attribute. That is, a MHTML file must always start with <module name=“filename”> and end with . Last but not least, MHTML outputs its result in UTF-8 meaning that it is readable by the majority of internet browsers across the world. Depending on whether you want MHTML to produce HTML or XHTML code, there are some particularities to care for.

1.1

HTML

Apart from the aforementioned advice, writing HTML inside an MHTML module is quite straightforward. Just make sure that you respect the MHTML syntax described below and write your HTML code just like you would in a classic HTML file, except for the DOCTYPE element that MHTML automatically adds at the end of the processing.

1.2

XHTML

As XHTML is less lenient than HTML, writing XHTML-compliant code may need some additional effort on your part. But the robustness of the result is worth it. Firstly, the MHTML file must be XML 1.0 standard-compliant. That is, it must: • start with an XML declaration (such as , • have a closing tag for each XHTML element, • respect the case, • have all of its elements properly nested, and • have “module” for its root element. Additionally, your code must comply with XHTML 1.0 transitional (references available at http: //www.w3.org/TR/xhtml1/) and the MHTML syntax described below. In XHTML processing mode, MHTML performs additional checks for well formedness and automatically validates the result against XHTML 1.0 transitional standard. As such, any failed attempt to meet the above criteria will trigger an error. Lastly, like in HTML mode, MHTML will take care of the DOCTYPE element. 1

2

MHTML syntax

2.1

The basics

Basically, MHTML introduces the two following markups: 2.1.1

The “module” markup

<module name="filename"> MHTML file’s content (...) As we have already seen, this element characterizes a MHTML file as it is its root element. The “name” attribute is required and must have the current file’s name (without the “.mhtml” extension) for its value. 2.1.2

The “import” markup

moduleName This is the main element of MHTML and certainly one that is used the most as it allows to import the content of another MHTML file (hence a module) to the currently processed one. I.e. when MHTML encounters such a markup, it resolves moduleName to the corresponding system filename and then copies the content of this file in substitution of the construction. Note the path of the file to import must be relative to the one of the currently processed MHTMLfile. Please note as well that the directory separator is the character ‘/’. moduleName designates a file whose path is relative to the MHTML file that declares it. E.g. if one wants to import a file h1.mhtml in a “header” subdirectory, the import will look like header/h1.mhtml or header/h1 as the “.mhtml” extension is optional. Optionally, the import element admits a mode attribute that can take the following values: “raw” (default value when mode is not explicitly declared): no check is ever performed on the imported file, it is the most failsafe option “wellformed” the imported file is checked for well formedness. Basically, a well formed file is an XML compliant file. If the file to be imported is not well formed, the process is aborted and an error is displayed. “valid” the imported file is checked against XHTML 1.0 standard. If the module is not XHTML compliant, the process is aborted and an error is displayed. “local-only” the imported file cannot use remote references, i.e. all of its links must point to local resources. Should you want to specify multiple modes, you can do so by using the ‘+’ operator (e.g. mode=¨raw+localonly¨). Please note that some modes aren’t compatible with other ones. In that case, running MHTML in such cases will display an error message. Here is a short example: // file index.mhtml <module name="index"> world 2

// end of file index.mhtml // file world.mhtml, in the same directory: <module name="world"> Hello world ! // end of file world.mhtml Launching MHTML on index.mhtml produces the following file: // file index.html Hello world ! // end of file index.html

2.2

Advanced use: the templates

Additionally, MHTML provides a way to use parameterized modules by using templates. Typically, a template consists of two things: • a definition which provides the template body as well as a list of expected formal parameters and their use in the template, • and an instantation which “calls” the template by giving it actual parameters. Like any other MHTML file, template definition and instantiation each have a “module” for their root element. With templates come new markups to implement them, these fall into two categories: 2.2.1

Template definition markups

Firstly, one has to declare parameters in order to use them in the template body. Thus, a template definition must have a “params” element that takes no attribute and that has one or more “param” elements as its children. Each “param” element corresponds to one parameter with an unique name. <params> <param [mode="raw"|"wellformed"|"valid"|"local-only"] [optional="true">] parameterName1 [<param [mode="raw"|"wellformed"|"valid"|"local-only"] [optional="true">] parameterName2 ] [<param [mode="raw"|"wellformed"|"valid"|"local-only"] [optional="true">] parameterName3 ] param supports the following attributes: “mode” that works like its “import” homograph by enforcing some kind of check upon the designed parameter. If no such attribute is provided, it defaults to “raw”.

3

“optional” that specifies, in case of it being “true”, that the parameter does not require to be valued at instantiation time. It it isn’t valued, the corresponding “use” markup(s) (see below) will be ignored. Any other value than “true” for this attribute will not be taken into account. As soon as these parameters are declared, they can be used in the template body via the “use” element: <use> parameterName Where parameterName references a previously declared parameter. When instantiating this template, MHTML will remove the “params” element and will resolve each “use” element to their corresponding actual parameters. 2.2.2

Template instantiation markups

Now that we have a template body, all that is left is to instantiate it. Like everything in MHTML up until now, the instantiation takes place in a module and consists of the following elements: templateFilename filename [ filename ] At compile time these elements are replaced by the template definition body loaded from the templateFilename. To each declared parameter a value must be given by using “actualparam” which takes as its “fp” (for Formal Parameter) attribute the parameter name paramName and that encloses as its value the filename of the module to load in the place of the corresponding “use” element. As “actions speak louder than words”, let’s have a look at the following example: // file template_definition.mhtml <module name="template_definition"> <params> <param mode="wellformed"> mycontent <param> mymenu <param mode="raw"> mytitle <use> mymenu <use> mycontent // end of file template_definition.mhtml // file instantiation.mhtml <module name="instantiation">

4

template_definition title content menu // end of file instantiation.mhtml Running MHTML on this example (java -jar mhtml.jar instantiation.mhtml index.html) will load instantiation.mhtml and process it by effectively instantiating template definition.mhtml. That is, for each encoutered formal parameter, it will give look for the corresponding value and import the designated module using the chosen mode.

5