m4: Frozen file format
1
1 15.2 Frozen file format
1 =======================
1
1 Frozen files are sharable across architectures. It is safe to write a
1 frozen file on one machine and read it on another, given that the second
1 machine uses the same or newer version of GNU 'm4'. It is conventional,
1 but not required, to give a frozen file the suffix of '.m4f'.
1
1 These are simple (editable) text files, made up of directives, each
1 starting with a capital letter and ending with a newline (<NL>).
1 Wherever a directive is expected, the character '#' introduces a comment
1 line; empty lines are also ignored if they are not part of an embedded
1 string. In the following descriptions, each LEN refers to the length of
1 the corresponding strings STR in the next line of input. Numbers are
1 always expressed in decimal. There are no escape characters. The
1 directives are:
1
1 'C LEN1 , LEN2 <NL> STR1 STR2 <NL>'
1 Uses STR1 and STR2 as the begin-comment and end-comment strings.
1 If omitted, then '#' and <NL> are the comment delimiters.
1
1 'D NUMBER, LEN <NL> STR <NL>'
1 Selects diversion NUMBER, making it current, then copy STR in the
1 current diversion. NUMBER may be a negative number for a
1 non-existing diversion. To merely specify an active selection, use
1 this command with an empty STR. With 0 as the diversion NUMBER,
1 STR will be issued on standard output at reload time. GNU 'm4'
1 will not produce the 'D' directive with non-zero length for
1 diversion 0, but this can be done with manual edits. This
1 directive may appear more than once for the same diversion, in
1 which case the diversion is the concatenation of the various uses.
1 If omitted, then diversion 0 is current.
1
1 'F LEN1 , LEN2 <NL> STR1 STR2 <NL>'
1 Defines, through 'pushdef', a definition for STR1 expanding to the
1 function whose builtin name is STR2. If the builtin does not exist
1 (for example, if the frozen file was produced by a copy of 'm4'
1 compiled with changeword support, but the version of 'm4' reloading
1 was compiled without it), the reload is silent, but any subsequent
1 use of the definition of STR1 will result in a warning. This
1 directive may appear more than once for the same name, and its
1 order, along with 'T', is important. If omitted, you will have no
1 access to any builtins.
1
1 'Q LEN1 , LEN2 <NL> STR1 STR2 <NL>'
1 Uses STR1 and STR2 as the begin-quote and end-quote strings. If
1 omitted, then '`' and ''' are the quote delimiters.
1
1 'T LEN1 , LEN2 <NL> STR1 STR2 <NL>'
1 Defines, though 'pushdef', a definition for STR1 expanding to the
1 text given by STR2. This directive may appear more than once for
1 the same name, and its order, along with 'F', is important.
1
1 'V NUMBER <NL>'
1 Confirms the format of the file. 'm4' 1.4.18 only creates and
1 understands frozen files where NUMBER is 1. This directive must be
1 the first non-comment in the file, and may not appear more than
1 once.
1