WebLord

WebLord 1.2.3

The Site Construction Power Tool

Solving Problems

Debugging Levels
Increase the debugging level for increasingly detailed information on processing details.
Unexpectedly Missing Text on a Page
Determining causes for text "gone missing."
External files
Using the contents of external files dynamically.
Runnaway Recursion
Tackling runnaway recursion problems.
Using HTML 4.0 features
Document relational links and default (cascading) style sheets.
Memory Allocation Problems
Out of memory: what to do.

Debugging Levels

WebLord has several debugging levels, set with the DEBUG=n argument. Each debugging level includes the output of all lesser levels.

WARNING: Debug levels 6 or higher can produce hundreds of kilobytes of output! It is highly recommended that output be redirected to a file, then examined with a text editor or similar tool.

0Set either with DEBUG=0 (or QUIET)
Suppresses all output except errors.
1The default output/verbosity level
Adds progress feedback as pages are being processed and written to disk.
2Set with DEBUG=2
Adds feedback on if/ifdef/ifndef decisions being made and other minor revelations.
3(currently the same as 2)
4(currently the same as 2)
5Set with DEBUG=5
Adds feedback on objects read from the input definition.
6(currently the same as 5)
7Set with DEBUG=7
Adds lots(!) of details on individual tokens retrieved from the input file. Be careful with this one, as it can produce hundreds of kilobytes of output!
8(currently the same as 7)
9Set with DEBUG=9
The highest possible, most verbose debug level; this is currently equivalent to level 7


Unexpectedly Missing Text on a Page

Most likely this is due to some conditionals (if / ifdef / ifndef) resolving to an unexpected value. You should try debug level 2 to determine if all conditionals resolve to the values that you expect.


External Files

From the first, WebLord has supported externally supplied data for object definitions. But beginning with WebLord 1.1 and further enhanced with 1.2 comes the ability to perform dynamic replacements of inherited properties in this external data. In plain english this means that you can specify "variables" in external data and inherited data will replace these when the data becomes an object's value.

Consider this example:


	page = myPage
	{
		value			= header body footer;
		output			= "mypage.html";
		body			= input-file;		# use object below
		file			= "mypage.text";	# define the filename
		sig			= "Text:.sig";
	}

	text = input-file	# a "generic" file-input object that inherits
				# the name of the file from property 'file'
	{
		value			= file;
		value-in-file		= "yes";
		file-has-variables	= "yes";
	}

Notice that the PAGE object defines a 'body' property that references the 'input-file' property. It also defines the 'file' property with a value "mypage.text".

The 'input-file' property inherits its 'value' from the 'file' property defined by the parent object (myPage PAGE object) but defines 'value-in-file' so that this value is actually the name of an input file. It also defines 'file-has-variables' such that ${...} sequences in this input file are evaluated.

Let us now examine the contents of the "mypage.text" file:


	<H1>Raymond Luxury Yacht</H1>
	<P>"Hello, and welcome to the programme. Today we are talking to a man with
	an unusual name. He is Raymond Luxury Yacht---"</P>
	<P>"No, no, no! It's SPELLED Raymond Luxury Yacht, but it's PRONOUNCED
	Throatwarbler Mangrove!"</P>
	<EM>Alas, this sketch is much too silly to continue!</EM>
	<HR>
	<PRE>${(include)sig}</PRE>

Notice the last, rather non-silly line. There is a ${(include)sig} sequence, which causes "sig" to be evaluated (to the string constant Text:.sig) and the file by that name is then inserted at that spot. Provided that this file exists, of course.

Let's assume that the Text:.sig file contains:


	This silly page was built by R.L.Y.

Aside from the 'header' and 'footer' definitions referenced in the PAGE object 'myPage' above, the value of the 'input-file' object as referenced by the 'myPage' object is then:


	<H1>Raymond Luxury Yacht</H1>
	<P>"Hello, and welcome to the programme. Today we are talking to a man with
	an unusual name. He is Raymond Luxury Yacht---"</P>
	<P>"No, no, no! It's SPELLED Raymond Luxury Yacht, but it's PRONOUNCED
	Throatwarbler Mangrove!"</P>
	<EM>Alas, this sketch is much too silly to continue!</EM>
	<HR>
	<PRE>This silly page was built by R.L.Y.</PRE>

But what would have happened if we had specified <PRE>${sig}</PRE> for that fateful last line? (Notice the absence of the modifier list with an 'include' modifier)

Easy! Instead of the contents of the file named by the (inherited) 'sig' property, the value of the property 'sig' would have been included. The last line would have ended up as:


	<PRE>Text:.sig</PRE>

Another option to consider is the literal argument. If the last line in the file had been:


	<PRE>${(include,literal)sig}</PRE>

then the string sig would not have been resolved as a symbol and instead have been considered as an exact, literal filename. Considering the entire example above, the following two lines would produce the same result, although the first offers more flexibility because you can reference the file with different, inherited, values for the sig symbol:


	<PRE>${(include)sig}</PRE>
	<PRE>${(include,literal)Text:.sig}</PRE>

This feature is quite powerful. Working within the framework of WebLord, it makes sense to move any larger property values into external files, thereby cleaning up large and "messy" site description files. You can reference any number of properties in such files without the need to watch out for and "escape" embedded quotation marks.

Want to know a secret? The documentation you are reading was built with exactly this feature. In fact the exact same set of files is made to serve as documentation for Amiga, Linux, and Solaris systems (or any other platform that WebLord supports.) Rather clever of me, don't you thnk? ;-)


Runnaway Recursion

Once WebLord has descended 1000 levels or deeper (if this ever happens, you almost certainly have a problem!!) into resolving object values, it begins to issue warnings, printing to the output the symbols to be resolved for approximately 10 recursion levels. After about 10 levels, it stops, and begins again at 1250, 1500, 1750, 2000, etc.

Future versions of WebLord will provide enhanced recursion detection and provide diagnostics as to the problem's cause. You are currently left to determine the problem on your own. Some of the following may be of assistance:

  1. If you make any reference to 'name' (or an object being referenced makes itself a reference to 'name', etc.) then you may be inadvertently referencing the wrong value and might cause WebLord to resolve an infinitely recursive definition. See the Misconceptions and Pitfalls section for an explanation on this particular issue.

    Any object referencing another, which in turn somewhere "down the line" references back upon the same list of references will also cause infinite recursion. Example: Object A references object B. Object B then references object C, and object C references object A again.

Debug level 2 may also shed some light on the matter.


Using HTML 4.0 Features

With the introduction of HTML 4.0, some new features have become available to the web page designer. Although WebLord itself does not concern itself with HTML, the include file global.wl defines some useful constructs to create HTML documents.

In particular, if you use HTML 4.0 features you should define a property html-version = "4.0"; in the SITE object so that the page header properly reflects this requirement. If you do not, then the header will continue to define the document as HTML 3.2 compliant.

Further, your document may be part of a set of pages and should define its relation to the other pages in the set. The global.wl include file uses certain settings of a page to build HTML 4.0 compliant <LINK> tags for the document header:

  • link-index-href
    The URI of the index page of which the current page is a part.

  • link-index-hreflang
    The language of the index page. (optional)

  • link-index-hrefdir
    The direction of the text on the index page. (optional)

  • link-index-charset
    The character set of the text on the index page. (optional)

There are other properties defined, but the above are the most important. For the index link, there also are properties for the prev (sequentially preceding/previous) document, and the next (sequentially succeeding/next) document, as well as the begin (beginning or first) document in the current set.

If you have a need for additional <LINK> tags in the document header, a PAGE may define an other-header-elements property whose value is added to the HTML headers as-is.

An additional new property that your PAGE object may specify is the stylesheet-href property which defines the URI of a stylesheet whose contents defines the default cascading style sheet (CSS) for the page.


Memory Allocation Problems

It is possible that many requests for dynamic memory allocation and subsequent releases of this memory have resulted in a high degree of fragmentation of the available free memory. Depending on the degree of this fragmentation, the largest consecutive block of memory may be comparatively small.

WebLord requires memory in comparatively large blocks (as much as twice the size of your largest page), so when memory is seriously fragmented, an allocation may fail and WebLord will be unable to proceed.

WebLord's own impact on the system's memory fragmentation is either minor or non-existent due to its use of memory pools, which are allocated and extended in large chunks.

Once memory is significantly fragmented there are two methods to getting WebLord to function: quit all other programs, thereby giving the system a chance to consolidate memory into larger chunks again. If this is not successful (it not always is) then rebooting your system is the only remaining solution.


WebLord is Copyright © 1997,1998 Udo K Schuermann. The latest versions of the software and (this) documentation can be obtained from the WebLord Home Page (the link will only function if you are connected to the internet.) This page has last been updated on Wednesday, January 21, 1998.