xm-tool

XM to css html4

The xm-tool splits the handling of xml'ish tags and the actual html outline by using a css description. This is also recommended by the W3 consortium, but the xm-tool uses a little trick to combine the css-file and the xml-file into proper html4.

The script xm::css::mkhtml4 will also take a -css argument that hold layout information. If no such css-argument is present, it will look for a css file in the current or parent directory using a few heuristics based on matching the common head of the filename/dirname and the css filename

The css-file has a special format to be used with css::mkhtml4 - the mkhtml4 script will by default convert all xml-tags into "<span class="xm-tag">text</span>" so that the css-file should have a class-entry like " .xm-tag { color : green ; } ". However, the actual html-markup to be used can be exchanged by simply making it the css-markup description for the css-line, so it could read "tt .typotext { font-style : italic }". The css::mkhtml4 script would then generate "<tt class="typotext">sometext</tt>"

The current css:html4 is written so that it will by default put the css-lines into a <style>-section in the header of this html-file, i.e. it will not put a link-reference in there. Luckily, it will not copy the whole css layout file (which may be rather large for having layout information for all docbook tags) instead it copies only those lines whose classes or markups have been used during converting the xm-file to html4. The advantage is, that the resulting file can be copied everywhere, and it will keep its look even if there is no internet-connection available the nearby css-file has been forgotten to be copied. The downside is, that the file gets a little larger - by experience about ten lines of css layout information are copied which should be a number that is generally acceptable.

The heart of the css::mkhtml4 generation is the css file reader and finder. As always in xm-tool these scripts can be called seperately to do some diagnostic checks - try to call xm-perl xm::css::find myfile.type and it should show you the css file it has found. The output of xm-perl xm::css::sheet docbook.css is the result of sourcing the css-file to an internal database of css entries, and showing you all entries registered in there sorted by the class field.

The internal database is using the class-entry of a css-line as the primary key - and if no class-entry is present, it uses a pseudo key named "/body" for a body-css-entry. A css file may contain comments in C-notation "/*...*/" and if there are multiple lines with the same class-key (or a htmlmarkup w/o class) then the later one will be used to store it to the internal database.

The non-classed entry for the body htmlmarkup can be used to pass information about the general body-layout, e.g. background colors and background images. The htmlmarkups for "a:link" and "a:visited" are also recognized for the output of mkhtml4

The generation of markups offers a few codified customizations using a pseudo css-layoutinfo under the xm : coded subkey. Using xm : table will generate a borderless 100%-width table around the relevant text-section. As an example, try to use programListing with the provided docbook.css-example, so that <programListing>sometext</programListing> will show you this:

sometext

If there is no useful codification of yet-another behaviour, the xm-recognition will fall back to use it as a reference to a sequence of htmlmarkups to be actually used, i.e. xm : b.i allows you to generate double-htmlmarkups for a single xml-markup. Of course this is not very useful given the power of css, the place that actually has a good use for it revolves around the netscape4 background-color weakness: a background-color given to a text will only be put under the text-chars, i.e. it will not fill the paragraph rectangle on the screen. This is very ugly, so whenever you use a background-color, it is recommended to specify either xm : span or xm : table

And now, have a look at the shipped docbook.css for a few example about useful css-lines. The list is still incomplete, so please send any additions to the xm-tool mailinglist - the actual users of a docbook-markup will best know what looks nicely in a generated html-page.