USDA ARS

IPW Macros

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

    %name
appears 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.


IPW documentation / Last revised 20 May 2009 / IPW web site