Update FAQ about SD2 files.

1 files changed, 59 insertions, 35 deletions

diff --git a/doc/FAQ.html b/doc/FAQ.html
index bc77f12..68cf266 100644
--- a/doc/FAQ.html
+++ b/doc/FAQ.html
@@ -32,9 +32,9 @@
 	writing them back changes some sample values. Why?</A><BR>
 <A HREF="#Q011">Q11 : I'm having problems with u-law encoded WAV files generated by
 	libsndfile in Winamp. Why?</A><BR>
-<A HREF="#Q012">Q12 : What are samples? What are frames?</A><BR>
-<A HREF="#Q013">Q13 : Would it be possible to support Sound Designer II (SD2)
-	files?</A><BR>
+<A HREF="#Q012">Q12 : I'm loking at sf_read*. What are items? What are frames?</A><BR>
+<A HREF="#Q013">Q13 : Why can't libsndfile open this Sound Designer II (SD2)
+	file?</A><BR>
 <A HREF="#Q014">Q14 : I'd like to statically link libsndfile to my closed source
 	application. Can I buy a license so that this is possible?</A><BR>
 <HR>
@@ -374,67 +374,91 @@ is the risk of breaking something that currently works.
 <!-- ========================================================================= -->
 
 <A NAME="Q012"></A>
-<H2><BR><B>Q12 : What are samples? What are frames?
+<H2><BR><B>Q12 : I'm loking at sf_read*. What are items? What are frames?
 </B></H2>
 
 <P>
-For a sound file with only one channel, a frame is the same as a sample.
+For a sound file with only one channel, a frame is the same as a item.
 </P>
 <P>
-For multi channel sound files, a single frame contains a single sample for
+For multi channel sound files, a single frame contains a single item for
 each channel.
 </P>
 
 <!-- ========================================================================= -->
 
 <A NAME="Q013"></A>
-<H2><BR><B>Q13 : Would it be possible to support Sound Designer II (SD2) files?
+<H2><BR><B>Q13 : Why can't libsndfile open this Sound Designer II (SD2) file?
 </B></H2>
 
 <P>
-Theoretically yes, but there are a couple of complications.
+This is somewhat complicated.
+First some background.
 </P>
 
 <P>
-SD2 files are native to the Macintosh platform and use features of the Mac
-filesystem (file resource forks) to store the file's sample rate, number of
-channels, sample width and more.
+SD2 files are native to the Apple Macintosh platform and use features of
+the Mac filesystem (file resource forks) to store the file's sample rate,
+number of channels, sample width and more.
+When you look at a file and its resource fork on Mac OSX it looks like
+this:
+</P>
+
+<PRE>
+        -rw-r--r--  1 erikd erikd   46512 Oct 18 22:57 file.sd2
+        -rw-r--r--  1 erikd erikd     538 Oct 18 22:57 file.sd2/rsrc
+</PRE>
+
+<P>
+Notice how the file itself looks like a directory containing a single file
+named <B>rsrc</B>.
+When libsndfile is compiled for MacOSX, it should open SD2 file with
+resource forks like this without any problems.
 </P>
 
 <P>
 When SD2 files are moved to other platforms, the resource fork of the file
-is usually dropped altogether.
+can sometimes be dropped altogether.
 All that remains is the raw audio data and no information about the number
-of channels, samplerate or bitwidth.
-That means that there is little libsndfile can do other than read the file
-as SF_FORMAT_RAW.
-It might however be possible to write some code to write code to analyze
-the audio data and guess the format parameters (bitwidth and channels),
-but this may not always be reliable.
+of channels, sample rate or bit width which makes it a little difficult for
+libsndfile to open the file.
 </P>
 
 <P>
-Ocasionally, when SD2 files are moved to other systems, the file is
-	<A HREF="http://www.macdisk.com/binhexen.php3">BinHexed</A>
-which wraps the resource fork and the data fork together.
-For these files, it would be possible to write a BinHex parser but
-there is not a lot to gain considering how rare these BinHexed SD2
-files are.
+However, it is possible to safely move an SD2 file to a Linux or Windows
+machine.
+For instance, when an SD2 file is copied from inside MacOSX to a windows
+shared directory or a Samba share (ie Linux), MacOSX is clever enough to
+store the resource fork of the file in a separate hidden file in the
+same directory like this:
+</P>
+<PRE>
+        -rw-r--r--  1 erikd erikd     538 Oct 18 22:57 ._file.sd2
+        -rw-r--r--  1 erikd erikd   46512 Oct 18 22:57 file.sd2
+</PRE>
+
+<P>
+Regardless of what platform it is running on, when libsndfile is asked to
+open a file named <B>"foo"</B> and it can't recognize the file type from
+the data in the file, it then tries to open a file named <B>"._foo"</B>
+to see if the file has a valid resource fork.
 </P>
 
 <P>
-It would also be possible to provide MacOS specific support SD2 files
-but I am somewhat adverse to providing features that are only available
-on one of the platforms libsndfile supports.
+In short, libsndfile should open SD2 files with a valid resource fork on
+all of the platforms that libsndfile supports.
+If a file has lost its resource fork, the only option is the open the file
+using the SF_FORMAT_RAW option and guessing its sample rate, channel count
+and bit width.
 </P>
 
 <P>
-Basically this means that there won't be SD2 support any time soon.
-However, if someone cares sufficiently about this issue they can
-either provide LGPL compatible code or
-	<A HREF="m&#97;ilt&#111;:&#101;rikd&#64;&#109;eg&#97;-&#110;erd.&#99;om">
-	contract me</A>
-to write it.
+Occasionally, when SD2 files are moved to other systems, the file is
+	<A HREF="http://www.macdisk.com/binhexen.php3">BinHexed</A>
+which wraps the resource fork and the data fork together.
+For these files, it would be possible to write a BinHex parser but
+there is not a lot to gain considering how rare these BinHexed SD2
+files are.
 </P>
 
 <!-- ========================================================================= -->
@@ -444,8 +468,8 @@ to write it.
 </B></H2>
 
 <P>
-Unfortunately no. 
-libsndfile contains code written by other people who have agreed that their 
+Unfortunately no.
+libsndfile contains code written by other people who have agreed that their
 code be used under the GNU LGPL but no more.
 Even if they were to agree, there would be significant difficulties in
 dividing up the payments fairly.