** @name cdifile.txt Description of CD-i File Extractor program.
* 
* @section Copyright (c) 2009, CD-i Fan
* You are free to distribute the cdifile program for non-commercial purposes,
* provided you include this documentation file.
*
* The source for cdifile is not currently available, but it will at some
* point be released under the GNU General Public License, version 2.
*
* The cdifile program incorporates source code from MAME/MESS (specifically,
* the lib/util directory and parts of the osd and osd/windows directories)
* that is used subject to the following conditions:
*
*   Copyright Aaron Giles
*   All rights reserved.
*
*   Redistribution and use in source and binary forms, with or without
*   modification, are permitted provided that the following conditions are
*   met:
*
*       * Redistributions of source code must retain the above copyright
*         notice, this list of conditions and the following disclaimer.
*       * Redistributions in binary form must reproduce the above copyright
*         notice, this list of conditions and the following disclaimer in
*         the documentation and/or other materials provided with the
*         distribution.
*       * Neither the name 'MAME' nor the names of its contributors may be
*         used to endorse or promote products derived from this software
*         without specific prior written permission.
*
*   THIS SOFTWARE IS PROVIDED BY AARON GILES ''AS IS'' AND ANY EXPRESS OR
*   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
*   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
*   DISCLAIMED. IN NO EVENT SHALL AARON GILES BE LIABLE FOR ANY DIRECT,
*   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
*   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
*   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
*   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
*   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
*   IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
*   POSSIBILITY OF SUCH DAMAGE.
*
* @author CD-i Fan
*
* @version 0.5.1
*
* @history
* @rev 2009/10/24 cdifan Created.

The purpose of the CD-i File Extractor program (cdifile) is to extract
data from CD-i files.

With the current version of cdifile you can extract the following from
any CD-i disc image file that is supported by CD-i Emulator:
- raw file in mode2_raw format with 2352 bytes/sector
- cue file compatible with chdman (chd management tool from MAME/MESS)
- chd file compatible with MAME/MESS (requires chdman)

CD-i Emulator supports "raw disc image" file formats with sector
sizes of 2448, 2352, 2340, 2336 and 2332 bytes, with or without
two-second pregap and/or scrambling. This should cover all the "raw
disc image" file formats out there. In particular, the Nero (.nrg) file
format for track-at-once images is supported, as well as the IsoBuster
(.bin) and CloneCD (.img) files. A future version of CD-i Emulator will
also support MAME/MESS compressed hunk data (.chd) files; cdifile already
supports such files and can be used to extract data from them.

A future versions of cdifile will allow the extraction of files from a
disc image and the extraction of data, audio and video (with format
conversions) from real-time files and CD-i IFF files; it will also
support an interactive mode to browse disc images and real-time files.

To convert a CD-i disc image file to chd format:

	cdifile CDIFILE -createcd

This will create a temporary .cue$ file and (if necessary) .raw$ file,
call chdman to convert this to a .chd file and delete the temporaries.

As of version 0.5.1, cdifile supports the following options:

-writeraw [[NAME].EXT]

	Writes a raw disc image file in mode2_raw format with 2352 bytes/sector.
	This is the most basic kind of disc image file (also the largest),
	supported by almost any program that handles disc image files.

	The name of the file defaults to the input file name with the extension
	replaced with .raw; you can specify another extension or a complete name.
	Specifying an extension is useful when extracting data from multiple
	files at once.

-writecue [[NAME].EXT]

	Writes a cue file compatible with chdman, the chd management tool from
	MAME/MESS. This kind of file describes the layout of a disc in textual
	format. Unless -writeraw is specified, the cue file will reference the
	input file. A warning will be printed if the cue file is not a complete
	description of the input file.

	The name of the file defaults to the input file name with the extension
	replaced with .cue; you can specify another extension or a complete name.
	Specifying an extension is useful when extracting data from multiple
	files at once.

-createcd [[NAME].EXT]

	Creates a chd file compatible with MAME/MESS by generating a temporary
	.cue$ file and, if necessary, a temporary .raw$ file, call chdman
	(which must be available in the current directory or in your PATH)
	to create a .chd file from this and then delete the temporaries.
	
	The creation of a temporary .raw$ file is necessary when the input
	file is has a pregap, is scrambled or is not in mode2_raw format with
	2352 bytes/sector; chdman does not properly handle such files.
	
	You can avoid deletion of the temporaries (and, incidentally, remove
	the trailing $ from their file extensions) by using the -writeraw and/or
	the -writecue options to force their creation.

	The name of the file defaults to the input file name with the extension
	replaced with .cue; you can specify another extension or a complete name.
	Specifying an extension is useful when extracting data from multiple
	files at once.

NOTE: Many cdifile options have optional parameters; it is best to specify
the options after the input file name(s) to ensure that these are not
interpreted as option parameters.


For more information about CD-i Emulator and other programs from CD-i Fan
you can visit his website at http://www.cdiemu.org.

