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:
There is a common structure to FreeBMD pages
FreeBMD pages conform to HTML standards
Common text (e.g. the footer) can be changed easily
Standard icons can be easily incorporated into pages
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
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).
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:
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
GTML has been patched so that a double backslash at the end of a line preserves
the newline
GTML has been patched so that with #literal on in force embedded
GTML commands (within SGML comments <!-- and -->)
are still actioned (the stated need for #literal on is to
handle c pre-processor files which contain the same commands as gtml,
e.g. #ifdef)
a macro <<__NL__>> is included automatically which
allows newlines to be included in macros
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:
every .html or .shtml is processed by GTML during the handoff - if such a file
does not contain GTML commands it is unchanged but this does mean it is very
simple to change a file to make it compliant to FreeBMD GTML standards (as
described above)
a GTML file can be tested using the test page as described
above
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:
we would need to change all the file names for pages that contained gtml which
would involve a signficant amount of CVS activity if we wanted to have every html
page pre-processed
in order to handle .shtml files such files would need to have a GTML command
added to change the extension of the output file
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.
HTML Preprocessing