IPW macros are simple text macros used to place information into certain types of text files in the IPW software. Each use of an IPW macro in a text file is known as a macro call. There are two types of macro calls:
Type of IPW macro call | Format |
---|---|
Without arguments | %macro |
With arguments | %macro(argument,...) |
Each macro call is replaced with the definition of the named macro, which is simply a string of text.
Macros without arguments
Macros without arguments are the more common variety of IPW macros. The definition of this type of macro is simply a fixed string of text; therefore, each call to a particular macro is replaced with the same string.
A common example of an argument-less macro is found in the source files for the manual pages for IPW commands. Throughout the source file for a command's manual page, the IPW macro
%nameappears everywhere the command's name would appear. Each call to this macro is replaced with the command's name as it is specified in the command's
Makefile
. The use of this macro in the manual page's source
file allows the command to be easily renamed by simply changing its
Makefile
, and by not requiring any changes to the source file
for the manual page.
Macros with arguments
The less common, but more powerful type of IPW macros has a list of arguments that affect the string substituted for each macro call. Each reference to an argument in the macro's definition is replaced with the actual argument. An argument reference in a macro's definition has one of two formats:
%n or %{n}where
n
is an unsigned integer. This integer is the
number of the argument being referred to. The first argument is argument 1,
the second argument is argument 2, and so on. For example, every
occurence of "%1"
in the macro's definition is replaced with
the first argument.
This type of macro is typically used in the generation of the HTML documentation for IPW software. Each HTML document has a standard format which includes a <HEAD> section that specifies the document's title, followed by the start of the <BODY> section that begins with a level-one heading (i.e., a <H1> heading).
To ensure all the HTML documents have this same format, there is an IPW
macro called "%Title_And_H1"
which takes two arguments:
the document's title and its level-one heading. As an example, here
is the macro call used to produce the section in the User's Guide about
the format of IPW image headers:
%Title_And_H1(IPW Header Format,Format of IPW Image Headers)In most instances, a document's title and level-one heading are the same; therefore, there is another macro called
"%Title"
that
takes one argument using it as both title and heading:
%Title is defined as "%Title_And_H1(%1,%1)"
Macro processor "ipwMacro"
IPW macros are processed by a Perl script called "ipwMacro"
.
Various include
files used in IPW Makefiles invoke this
auxiliary script. For more detailed information about IPW macros,
consult the source file for this script:
"$IPW/make/src/ipwMacro.pl"
.
"IPWmacros"
file
Many IPW macros are derived from information specified in various Makefiles
throughout IPW's source directory. In these instances, the "make"
utility automatically generates a file called "IPWmacros"
which contains the macros' definitions (e.g., %name
).
In those directories where this file exists, the ipwMacro
script uses the file whenever it's invoked.