FreeBMD HTML Preprocessing

Introduction

Static HTML pages within FreeBMD are run through a pre-processor call GTML every time the page is deployed. This pre-processor acts upon special commands within the page to generate standard HTML for FreeBMD pages. This is done so that: When writing a FreeBMD HTML page there are a number of standard components that are available through GTML and the FreeBMD GTML macro library. It is not necessary to understand GTML in order to use these facilities; they are described below.

Standard Elements for a Help page

When writing a FreeBMD help page there are only two Standard Elements that are mandatory, the header page macro with the the name of the page and the footer macro. The macros used for this page are
<<helppage(HTML Preprocessing)>>
...
<<pagefooter>>

with, obviously, the text of the page between them. The header produces the logo, the page background, the window title (FreeBMD Help) and the page title. The footer produces the link to the home page and everything following it. The help page macro includes the standard help style sheet in style/help.css.

So for a help page that is the minimum that is needed, although the Standard Elements described in Further Macros may also be of use. However, authors also need to consider the next section on testing but apart from that everything else is optional.

Testing a page

When using raw HTML, that is without the pre-processor, authors could validate their pages on their local PCs, indeed some text editors provide automatic facilities to achieve this. However, when using HTML with pre-processor commands the page will not display as it will on the web site. To overcome this a simple facility is available which allows authors to download a web page that is under construction to see what it will look like once it has been pre-processed. Go to Prepare Page, browse to the file containing the HTML of the page being constructed and click on View. The page will then be displayed as it will be once it has been pre-processed.

Note that a page displayed in this way has not been stored on the server. It will still need to be committed into the system using CVS.

To download the page as it is after it has been pre-processed click on Download.

Additional Style Data

So far we have described the standard header for help files. This can be customised by adding further style information as follows
<!-- ###define INCLUDESTYLE style information -->
where style information is either a reference to style sheet or actual css information; this is done using the following macros
stylereference(name)
add a reference to the style sheet file in style/name.css
sytleverbatim(css data)
add the css commands css data

These macros can be repeated and intermixed but there should not be a literal newline between (or in) the macro calls (see here).

An example of adding style information is:

<!-- ###define INCLUDESTYLE <<styleverbatim(img.scrap{margin-left:1cm})>> <<stylereference(quotation)>> -->
<<helppage(HTML Preprocessing)>>
which would add the style for img.scrap and a reference to style/quotation.css.

Further headers

The macro helppage described above uses a more general macro pageheading; this macro can be used to generate the heading for pages other than help pages. It has the following definition:
pageheading(pagetitle,windowtitle,styledata)
add a heading with a page title of pagetitle, a window title of windowtitle and with style information styledata.
The styledata can be created using the styleverbatim and stylereference macros described above. An example of this macro that would generate the page heading for this page is:
<<pageheading(HTML Preprocessing,FreeBMD Help,<<stylereference(help)>>)>>

If a page has no style information styledata can be omitted, thus:

<<pageheading(Freebmd,Mailing Lists)>>

Further macros

Almost all the constants in lib/BMD/Const.pm are automatically included as macros with names of the form:
BMD_CONST_variablename
where variablename can be found in lib/BMD/Const.pm.

However, there are relatively few such constants that would be of interest for constructing an HTML page, but the following are:

<<BMD_CONST_Support>>
the image that gives the support email address
<<BMD_CONST_InfoButtonText>>
the Info button icon structured to correctly fit in a text line
<<BMD_CONST_SystemLinkText>>
the System Link icon structured to correctly fit in a text line
<<BMD_CONST_PostemText>>
the Postem icon structured to correctly fit in a text line

In addition there are the following special constants

<<MEMBER>>
the short name of the machine on which the script resides
<<IMAGE_DOMAIN>>
the domain of the image servers

GTML

The pre-processor used is GTML. As used in FreeBMD this takes macro definitions (e.g. helppage) and expands them when they are found in the HTML. The standard macro definitions are held in gtml_lib/macros and are used for each FreeBMD page that is deployed. The constants are held in gtml_lib/constants. Both of these are included by reference from gtml_lib/includes. The manual for GTML can be found here. The following sections give additional information about the use of GTML.

Comments

An undocumented feature of GTML is that any line starting with # that is not recognised as a GTML command is considered to be a comment and dropped from the HTML. This does not occur when
#literal on
is in force so that is what the FreeBMD GTML library does for all FreeBMD HTML pages since there are a number of instances of lines starting with #.

Line ends

All GTML commands have to be contained on one line. However, it is possible to spread a line over several lines by ending each line (except the last) with backslash. This causes the newline to be ignored. The problem with this is that it is not possible to format data with line breaks. To overcome this GTML has been patched on FreeBMD so that ending a line with a double slash causes the output to contain a newline. Note that this can only be used on the final macro expansion; if it is used on a macro that is called by another macro it will not have the desired effect.

Modifications

The following modifications have been made to GTML for use in FreeBMD

Macro arguments

Within a macro definition the name of the macro is followed by a bracketed list of arguments. When the macro is invoked instances of these arguments within the macro expansion are replaced by the values given in the call. Care needs to be taken with the names of macro arguments since they are not differentiated from HTML constructs. For example giving an argument a name of href would cause instances in anchors (<a href="...) and elsewhere to be replaced by the argument value. In FreeBMD macros this issue is avoided by making all argument names begin and end with underscore.

Newlines and Tabs

An undocumented feature is that there are predefined macros <<__NEWLINE__>> and <<__TAB__>> which expand to newline and tab respectively (there are two underscore characters at the start and two at the end). Unfortunately these macros get expanded when they are declared so if used inside a macro that is called from another macro they have no effect. To overcome this the FreeBMD library includes the macro <<__NL__>> which is expanded on invocation and hence works in all macros.

Commas in parameters

Comma is the delimiter for parameters so a comma cannot appear in a parameter, for example in the heading of a page. To get round this limitation use the html code &44; in place of the comma.

Invoking GTML

GTML is invoked within FreeBMD in two ways:

Although hidden from most usage it should be noted that GTML cannot be invoked as a filter, that is taking its input from standard input and producing output on standard output. Instead it takes a parameter of a file that must have an extension of .gtml and produces, by default, a file of the same name but with the extension .html. The issues with this, for FreeBMD, are:

To simplify using GTML a script is provided (gtml_proc.sh) that acts as a filter and it is this script that is used to effect the processing described above.

FreeBMD Main Page


Search engine, layout and database Copyright © 1998-2017 Free UK Genealogy CIO, a charity registered in England and Wales, Number 1167484.
We make no warranty whatsoever as to the accuracy or completeness of the FreeBMD data.
Use of the FreeBMD website is conditional upon acceptance of the Terms and Conditions
Explore FreeBMD