Wusage: Silly Name, Serious Stats!

Wusage 8.0 Manual

Report Macro Language

Unlike previous versions, Wusage 7.0 and above use a flexible report macro language to create reports. This allows users to make many different changes to the presentation of reports. Translating reports from English to other languages is straightforward, as in previous releases. However, it is also possible to change the structure of reports, replacing our standard Wusage 7.0 frames-based approach with another layout. And, of course, the aesthetics of the reports are very much under the user's control.

The report macro language is designed to be simple and straightforward, but most users will not need to fully understand it in order to make useful changes, such as translation or aesthetic improvement. Complete understanding of the report macro language is only necessary for those who wish to reorganize the reports in dramatic ways.

"How do I get started?"

A collection of standard report macros are used to generate all of the normal HTML and email reports of Wusage 7.0 and above. Normally, these macros are fetched from an internal copy. However, users who wish to do so can easily replace them.

Unix Users

Beginning with Wusage 7.0, you can simply copy the .rmc files provided in the macros subdirectory of the Wusage distribution into a subdirectory of your home directory called wusage-macros. For instance, if you run the Wusage program under the Unix account httpd, the subdirectory containing your customized macros will typically be called /home/httpd/wusage-macros.
You can also create customized macros for individual report directories by placing those macro files directly in the report directory itself. As a rule, if a report macro file can be found in the report directory, that file is used instead of the wusage-macros directory. If a report macro file cannot be found in either location, the built-in version is used.

Once you have copied the .rmc files, you can immediately begin making changes. You may freely change any English text you encounter, and you can change the HTML tags as well, although it is recommended that you become familiar with HTML before doing so.

As a general rule, if you prefer not to learn the report macro language, don't change any portion of the .rmc file that you do not understand. And, of course, keep the original .rmc files around as a backup. These simple rules will keep you out of trouble!

"How does the report macro language work?"

Anything that appears in a .rmc file is considered to be HTML (or EML for email reports), and is output directly as part of the report, unless it appears between the [@ and @] markers.

"What can appear between [@ and @]?"

The following commands can appear immediately following the [@ sequence. Anything else that appears immediately after [@ is the name of a macro, and should be immediately followed by @]. That macro will be expanded and inserted into the report at that point. Any additional macro commands in the body of the macro will then be expanded in turn.

Note to advanced users: macro names, as used in the ifset and set commands, can themselves be the result of a macro expansion. However, the macro expansion should result in a single word without spaces. Filenames for use by the openfile command can also be the result of a macro expansion. However, the filename given to the include command cannot be the result of a macro expansion.
CommandSyntaxMeaning
set [@set macroname macrovalue@] Sets the named macro to the specified value. The value can extend for as many lines as the author desires. Once a macro has been set, it can be expanded using the syntax [@macroname@]. A macro cannot have the same name as a command. If a macro is set twice, the new value replaces the old value.
unset [@unset macroname@] Unsets the named macro. The macro no longer has a value. The ifset command will consider it to be unknown.
ifset [@ifset macroname text@] If the named macro is set, then the text will be inserted into the report. The text can extend for as many lines as desired. If the macro has been unset using the unset command, the text is not inserted.
ifunset [@ifunset macroname text@] If the named macro is NOT set, then the text will be inserted into the report. The text can extend for as many lines as desired. If the macro has been unset using the unset command, the text is not inserted. New in 8.0.
openfile [@openfile filename@] The specified file is created, and all subsequent report text is written to that file instead of to the original report file, until the closefile command is used, or until the openfile command is used again. The openfile command does not nest; that is, if you open one file, then open another, and then use the closefile command, you are now writing to the initial report file.
closefile [@closefile@] Closes a report file opened by [@openfile@]. Subsequent output is written to the initial report file.
include [@include filename@] Reads additional text and/or macros from the specified file, exactly as if the contents of the file appeared at this point in the original report macro file. This facility provides a way to break up a complicated report macro file into several files.
open [@open@] Inserts the literal characters [@ into the report. This is an "escape mechanism" for those who must use the string [@ for some other purpose.
close [@close@] Inserts the literal characters @] into the report. This is an "escape mechanism" for those who must use the string @] for some other purpose.
jsq [@jsq macroname@] The text of the named macro is inserted into the report in a format compatible with Javascript quoted strings. That is, the " character is escaped as \", and the \ character is escaped as \\. The 8.0 versions of the documents and directories reports use this feature to store those reports very efficiently in arrays of Javascript strings.

Previous: Customizing Wusage Output
Next: Email Markup Language (EML)
Table of Contents
Topical Configuration Editor Reference
Alphabetical Configuration Editor Reference
Alphabetical Configuration File Reference
Glossary of Frequently Used Terms
Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, Boutell.Com, Inc.
wusage@boutell.com
Boutell.Com, Inc - PO Box 16716, Seattle WA, 98116, USA
Phone/Fax +1 206 658-8176
Copyright Statement

All material, including images, on this web site is Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, Boutell.Com, Inc. unless otherwise noted.
Need more information? Wondering who to contact? Visit our whom page.

Boutell.Com, Inc.
PO Box 16716
Seattle WA 98116
USA
+1 206 658 8176