How the PPF file format works
=============================

 The overall syntax is simple, but there's 2 different parsers now- the
original one built into Patel, and one in "libPPF". The original will
refuse some files that libPPF will accept (and AFAIR vice-versa), but
anything that libPPF *produces* is equally acceptable to both parsers.
The libPPF interpretation of the format will probably be favoured in
future.

 PPF files are line-oriented, with empty lines, lines of just whitespace,
and lines beginning with a # ignored. Both PPF parsers consider the
carriage-return and linefeed symbols to be equivalent, and each starts
a new line (so if you have a PPF file with DOS-style newlines, the parsers
shouldn't mind).

 The PPF format can be considered procedural; the actual meaning conveyed
by PPF files is given in 2 ways: variable setting, and commands.
 A line beginning with a lower-case letter sets a "variable", the variable
in question given by that letter. The value to give that variable is given
by 1 to 8 (upper-case) hexadecimal digits following immediately after. The
digits should then be followed by a newline (or whitespace?).
 A line beginning with an upper-case letter issues a "command", the command
being given by that letter. It must be alone on the line (except perhaps
by whitespace, depending on which parser). When the command is processed,
the values of some set of variables are often used with it. These are the
only points that the variable settings have an effect. The PPF format does
not specify how the commands are interpreted, that is wholly application-
specific.

 The number of digits each variable expects is defined by the semantics the
parser is told to use for the mode. EG: Patel's header mode expects the
'c' variable to have 1-digit values, and the 'i' variable to have 2-digits.
In its "instrument" mode, it expects a different number of digits for the
'i' variable (but currently that variable isn't properly defined and is
not to be used). If you use PPF files for some other purpose outside of
Patel, you might have totally different sizes for each variable.

 Similarily, which variables each command uses is also defined by the
semantics the parser is told to use for the mode. EG: In Patel's
instrument mode, the 'H' command uses the w, n, and v variables, and the
'F' command uses the w, p, f, q, and m variables; the song mode expects
a totally different set of commands, which each use different variables.

 As an example of how PPF works, see here:
#This is valid PPF data but
#Patel won't understand it
a8F

b21
N
c9
E

rB41A
a70
Q
#Remember, blank lines are ignored like comments

 In our made-up PPF mode, the N command uses the 'a' variable, the E command
uses the 'b' and 'c' variables, and the Q command uses the 'a' 'b' and 'r'
variables.
You would then find, the N command gives 'a' as 8F, the E command gives
'b' as 21 and 'c' as 9, and the Q command gives 'a' as 70, 'b' as 21
and 'r' as B41A.
 Note that variables can be set long before they're used, and their values
persist even after they're used, until they're explicitly set to something
different. Before a value has been set at all, they have a default value
of 0. Note that when the parsers change modes, they will normally reset
all their variables to 0 as well.


 NB: This was originally in the FAQ but then I realised it was far too huge
and warranted a file of its own.

Working with PPF files

PPF was designed with flexibility and ease of parsing/producing in mind-
ease for the programmer, that is! It may not be easy for the user to write
anything with fluently, but it's reasonably straightforward to make code
that produces it, given an understanding of what commands and variables
are relevant to the task in question; and libPPF makes it a fair bit easier
to reliably rewrite a PPF file with modifications (it does such things as
bounds checking of values and other error detection, and gives the caller
self-contained command packets to work with).

The libPPF library will be documented in future, but currently has so few
functions that reading the headers (and the comments therein) should be
fairly clear in the meantime. It is primarily of use where a program is to
read PPF data as well as writing it; where a program only writes it, it
is relatively simple to do without (see later).

There was also work done previously on a PPF module for Perl, designed
along much the same lines as the C based libPPF, but this turned out to
have some terrible bugs that I couldn't properly understand so that was
abandoned. Even without the bugs, it was unfinished. The only Perl-based
PPF utility I made ("notestoppf.pl") didn't use it at all, and simply
wrote lines of PPF data directly- the most complex part of that was
calculating the appropriate numbers (as understood by Patel) for different
musical notes.

