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