GSP-MACROS(7) Miscellaneous Information Manual GSP-MACROS(7)

gsp-macros — macro system for GSP documents

Macros offer a means to dynamically generate output using external executables. Arguments are passed from a macro invocation to the underlying macro executable by means of environment variables and the standard input allowing for the easy extension of GSP documents from any programming language.

For details on the syntax of macros as well as the differences between regular and verbatim macros, see gsp(7).

The manner in which macros are resolved is implementation-defined. When using the standard gsp(1) GSP to HTML transpiler, a macro ‘$foo’ or ‘$$foo’ will be resolved by searching the macro search path for the first file with the name foo. When a conflict arises, the first match in the macro search path is used.

Macros receive their body content via the standard input, and are replaced in the document by their standard output.

Because it is often important for syntactical reasons to know if the body is a regular body or a textual body, the GSP_TEXT_P environment variable will be set to ‘1’ when the macro body is a text body, and ‘0’ otherwise.

It is also important when producing generated output that attribute values and node text bodies properly escape metacharacters. For this purpose it may be useful to make use of the gspesc(1) tool that ships with the standard GSP distribution.

It is possible to pass additional parameters from the GSP document to macros through the use of attributes. Attributes provided to a macro are uppercased, prefixed with ‘GSP_’ and inserted into the macros environment. Additionally all hyphens (‘-’) in the attribute name are replaced with underscores (‘_’). When an attribute is provided without a value, the corresponding environment variable will be set with a null value.

The following is a list of example translations between node attributes and the exposed environment variables:

data-name="~tvoss"
disabled
lang="en"

The following environment variables are set in the environment of user macros:

Set to the path of the file being processed, or ‘-’ if the standard input is being processed.
Set to ‘1’ if the macro node was given a text body and ‘0’ otherwise.

The following macro expands into a ‘time’ node representing the current date and time in the specified timezone. If no timezone is specified, it defaults to the local timezone.

#!/bin/sh
# File saved as ‘now’ in the macro search path

[ -n "$GSP_TZ" ] && export TZ="$GSP_TZ"

cat <<EOF
time datetime="$(date '+%Y-%m-%dT%T')" {-
	$(date '+%H:%M &ndash; %A, %e %B %Y')
}
EOF

The above macro can then be used in a GSP document like so:

p {- Published at @$now tz="Europe/Stockholm" {}}

The following macro generates a section header with an auto-generated ID:

#!/bin/sh

if [ "$GSP_TEXT_P" -eq 0 ]
then
	>&2 printf 'header: macro only accepts text bodies\n'
	exit 1
fi

title="$(cat)"
id="$(
	echo "$title"            \
	| sed 's/^ *//; s/ *$//' \
	| tr 'A-Z_ ' 'a-z--'     \
	| tr -dc 'a-z--'
)"

# Important that we use ‘{=’ here to respect the user’s original
# whitespace control settings.  If the user used ‘{-’ the input
# will already have been trimmed for us.
printf 'h2 #%s {=%s}' "$id" "$title"

The above macro can then be used in a GSP document like so:

article {
	$header {- GSP Macro Reference }
	p {-
		Macros offer a means to dynamically generate output
		using external executables.
	}
}

gsp(1), gspesc(1), sh(1), gsp(7)

Thomas Voss <mail@thomasvoss.com>

May 5, 2026 GSP 4.2