                     
                     Errors in the XM format doucmentation
                     

                                Zvika Ben-Haim
                         zvikabh@aluf.technion.ac.il
                      http://www.technion.ac.il/~zvikabh


                                            "Real programmers don't document.
                                             If it was hard to write,
                                             it should be hard to understand."


This document refers to the file XM.DOC which comes with FastTracker, and is
the official file specification for the XM format. I came across several errors
in this document, and am publishing them in the hope that others won't have to
waste as much time as I did finding mistakes in the XM documentation. The
original document was written by Mr.H of Triton, who was also one of the
programmers who wrote FastTracker.

All of these errors are serious enough to cause FT2 to misinterpret a file.
Mr.H of Triton, who wrote the documentation, apparently took the joke about
programmers who don't document ("If it was hard to write, it should be hard
to understand") too seriously.

The volume column in the pattern list contains a value which is larger by 0x10
than the actual value displayed in FT2. That is, to get 0 volume you would put
0x10 in the volume byte in the file, and to get volume 40h (maximum) you would
put 0x50 in the file.

In the beginning of the file, the text should be 'Extended Module: ', and
_NOT_ 'Extended module: ' (note the capitalization). Otherwise FT2 thinks your
file is a MOD and reads it as gibberish. It took me _hours_ to figure out
why all the XMs generated by me couldn't be read by FT2 until I realized what
was going on.

In the XM header description, at offset 70d, the description should read
'Number of highest pattern in file', and _NOT_ 'Number of patterns in file'.
That is, if there are 5 patterns numbered 0 thru 4, this location should
contain the value 4. This one also caused me a lot of frustrating debug time,
since an incorrect value here causes FT2 to quit with an unhandled exception
error.

The actual version number (file header, offset 58) is 0x0104, and not 0x0103
as specified in the file description, though this doesn't really make a big
difference.

To get a "note off" command (you know, the wide bar thingy), type in a note
number 0x61 in the appropriate position in the pattern. You will usually do
this without any effect or anything, so the full command for that position
in the pattern will be 81 61 hex. (See information on pattern format packing
in the original XM documentation).

In the many "headers" in the file, a "header length" or "data size" value is
included, but usually it is not clear whether the size includes the header,
whether it includes the size word, etc. So, here is a list of all header sizes
(they are the same anyway for all XM files):
File header, offset 60: "Header size" is 0x114.
Pattern header, offset 0: "Pattern header length" is 9.
Instrument header, offset 0: "Instrument size" is 0x107, for all instruments.
Sample header, offset 0: "Sample header size" is 0x28.
