BuildSystem:

- split build guide into 3 articles, one for each platform
- populated root of tree with 3 platform Building guides: osx, cygwin, linux for convenience
- added python script (needs python3.0) to optionally generate wiki from .texi articles


git-svn-id: svn://svn.handbrake.fr/HandBrake/trunk@2195 b64f7644-9d1e-0410-96f1-a4d463321fa5

19 files changed, 1615 insertions, 339 deletions

diff --git a/00-BuildUserGuide.txt b/00.Building.cygwin.txt
index 3dd304128..b11b43c4c 100644
--- a/00-BuildUserGuide.txt
+++ b/00.Building.cygwin.txt
@@ -1,49 +1,94 @@
-HandBrake 0.9.3 Build User Guide
-********************************
+Guide to Building HandBrake svn2194 (2009030201) on Cygwin
+**********************************************************
 
 Table of Contents
 *****************
 
 1 Introduction
-2 Quickstart
-3 Build Process
-  3.1 Checkout Sources
-  3.2 Configure
-  3.3 Build
-  3.4 Clean
-  3.5 Extra Clean
-4 Make Targets
-  4.1 Global
-  4.2 General Modules
-  4.3 Contrib Modules
-  4.4 Contrib Aggregate
-5 Platform Requirements and Notes
-  5.1 Mac OS X
-  5.2 Cygwin
-  5.3 Linux
+2 Prerequisites
+3 QuickStart
+4 Overview
+5 Building via Terminal
+  5.1 Checkout Sources
+  5.2 Configure
+  5.3 Build
+  5.4 Make Targets
+    5.4.1 Global
+    5.4.2 General Modules
+    5.4.3 Contrib Modules
+    5.4.4 Contrib Aggregates
 
 
 1 Introduction
 **************
 
-This guide documents the recommended process to build HandBrake from
-the official source-code repository. Building from any other source is
-not unsupported.
+This guide documents the recommended process to build HandBrake on
+Cygwin hosts from the official source-code repository. Building from
+any other source is not supported.
 
-2 Quickstart
+2 Prerequisites
+***************
+
+The following are the recommended specifications for building on
+Cygwin; but is not necessarily the only configuration that is possible:
+
+   * Intel 32-bit or 64-bit hardware (only 32-bit product binaries are
+     supported)
+
+   * Cygwin, gcc 4.2.4
+
+   * yasm 0.7.2.2153 (for i386 or x86_64 architectures)
+
+     Note: It is recommended to use the platform distribution's bundled
+     compiler for maximum C++ compatibility. If you build with a custom
+     compiler it will likely introduce non-standard runtime
+     requirements. There are of course many valid reasons to build with
+     unbundled compilers, but be aware it is generally unsupported and
+     left as an exercise to the reader.
+
+     Note: As of this writing, Cygwin has available to it several
+     versions of gcc; only one of which may be found and used in the
+     path as `gcc' and `g++'. Configure will thus find what is probably
+     the older version of gcc in a typical Cygwin environment. If you
+     desire to build with the newer gcc, it is found in the path as
+     `gcc-4' and `g++-4' respectively and you must indicate to
+     configure the desired versions. The following syntax should do the
+     trick:
+
+     ../configure --gcc=gcc-4
+
+The following general tools are used on various platforms and it is
+recommended you use these versions or similar:
+
+   * subversion - 1.5.5
+
+   * python - Python 2.4.6
+
+   * curl - curl 7.19.3 (or wget)
+
+   * m4 - GNU M4 1.4.6
+
+   * make - GNU Make 3.81
+
+   * patch - Patch 2.5.8
+
+   * tar - GNU tar 1.15.1
+
+   * wget - GNU Wget 1.11.4 (or curl)
+
+3 QuickStart
 ************
 
-This chapter is for the impatient or those just looking for a quick
-summary of the commands used to launch a typical build with the fewest
-commands possible. For more control over the build process please skip
-this section and jump to *Note Build Process:: for full details.
+This chapter is for building from a terminal/shell environment in as
+few commands as possible. If more flexibility is required you should
+skip this chapter and jump to *Note overview::.
 
      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
      cd hb-trunk
      ./configure --launch
 
-The above is an special streamlined invocation of `configure' which
-performs the following steps automatically:
+The special option `--launch' selected launch mode and performs the
+following steps:
 
    * assert scratch directory `build/' does not exist
 
@@ -57,10 +102,16 @@ performs the following steps automatically:
 
    * echo build output
 
-3 Build Process
-***************
+4 Overview
+**********
 
-3.1 Checkout Sources
+Cygwin builds are performed from a terminal. There is no support for
+building from any IDEs.
+
+5 Building via Terminal
+***********************
+
+5.1 Checkout Sources
 ====================
 
 Checkout HandBrake from the official source-code repository.
@@ -76,7 +127,7 @@ If you have write-access to the repository, then you may add the
 appropriate login/password information as needed. It is recommended to
 use Subversion 1.5.0 or higher. Lower versions should also work.
 
-3.2 Configure
+5.2 Configure
 =============
 
 Configure the build system.
@@ -94,11 +145,24 @@ purposes.
 
 The `configure' utility accepts many options. It is recommended that
 you specify `--help' for the complete list of options. The following
-options are detailed:
+options are also documented here:
 
 `--help'
      List available options.
 
+`--prefix=PREFIX'
+     Specify destination directory for final product install.  This
+     defaults to a reasonable platform-specific value.
+
+`--disable-xcode'
+     Disable driving the build through Xcode. If this option is
+     disabled only `HandBrakeCLI' will be produced and Xcode will not
+     be invoked. Mac OS X only.
+
+`--disable-gtk'
+     Disable building the GTK GUI on applicable platforms such as
+     Linux.
+
 `--debug=MODE'
      Select debug mode. Must be one of `none', `min', `std', `max'.
      This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
@@ -135,12 +199,11 @@ some of the reasons why someone may choose to scrap an existing build:
 There are generally two methods for scrapping a build. The `build'
 directory can be recusrively removed which has the effect of loosing
 your existing configuration but does guarantee no residuals are left
-behind. The other method is to use ask the build system to perform an
-`xclean'. This is known to work well but will leave empty directories
-behind. However, the configuration is left intact. See *Note Extra
-Clean:: for further details.
+behind. The other method is to ask the build system to perform an `make
+xclean'. This is known to work well but will leave empty directories
+behind. However, the configuration is left intact.
 
-3.3 Build
+5.3 Build
 =========
 
 Build main product. All necessary dependencies are also built if
@@ -157,24 +220,8 @@ log. The following command allows for up to 4 concurrent jobs via make:
 
      make -j4
 
-3.4 Clean
-=========
-
-Clean all build output excluding contrib modules. Configuration is
-retained.
-
-     make clean
-
-3.5 Extra Clean
-===============
-
-Clean all build output including contrib modules. Configuration is
-retained.
-
-     make xclean
-
-4 Make Targets
-**************
+5.4 Make Targets
+================
 
 The build system supports passing many kinds of targets some of which
 become very useful in normal development cycles. The targets by
@@ -182,8 +229,8 @@ convention are lower-case words passed to `make'. Global targets are
 one-word targets. Scoped targets are usually two-words seperated by a
 period.
 
-4.1 Global
-==========
+5.4.1 Global
+------------
 
 `make'
      Alias for `make build'.
@@ -200,11 +247,15 @@ period.
      Clean all build output including contrib modules. Configuration is
      retained.
 
-4.2 General Modules
-===================
+`make doc'
+     Build auto-generated project documentation. Various articles are
+     produced and may be found in `build/doc/articles'.
 
-General modules such as `libhb' and `test' have the following scoped
-targets:
+5.4.2 General Modules
+---------------------
+
+General modules such as `libhb', `test' and `gtk' have the following
+scoped targets:
 
 `make MODULE.build'
      Build MODULE.
@@ -212,8 +263,8 @@ targets:
 `make MODULE.clean'
      Clean build output for MODULE.
 
-4.3 Contrib Modules
-===================
+5.4.3 Contrib Modules
+---------------------
 
 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
@@ -252,8 +303,8 @@ Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
      Extra clean module; first invokes uninstall then recursively
      removes the module build directory.
 
-4.4 Contrib Aggregate
-=====================
+5.4.4 Contrib Aggregates
+------------------------
 
 For convenience, the following targets aggregate the all contrib
 modules' respective targets together:
@@ -276,100 +327,3 @@ modules' respective targets together:
 
    * make contrib.xclean
 
-5 Platform Requirements and Notes
-*********************************
-
-The build system supports various platforms of interest to the project.
-However this does not mean it supports all plaforms. If the platform is
-not listed in this chapter, then it is not supported.
-
-The following tools are used on various platforms and it is recommended
-you use these versions or newer:
-
-   * python - Python 2.4.6
-
-   * curl - curl 7.19.3 (or wget)
-
-   * m4 - GNU M4 1.4.6
-
-   * make - GNU Make 3.81
-
-   * patch - Patch 2.5.8
-
-   * tar - GNU tar 1.15.1
-
-   * wget - GNU Wget 1.11.4 (or curl)
-
-5.1 Mac OS X
-============
-
-Building on Mac OS X is well supported. It is the reference platform
-for HandBrake. The following are the recommended specifications for
-this platform; but is not necessarily the only configuration that is
-possible:
-
-   * Mac Intel hardware
-
-   * Mac OS X 10.5.6
-
-   * Xcode-3.1.2
-
-   * gcc 4.0.1 (Apple Inc. build 5490)
-
-   * yasm 0.7.2.2153 (for i386 or x86_64 architectures)
-
-     Note: It is recommended to use the platform distribution's bundled
-     compiler for maximum C++ compatibility. If you build with a custom
-     compiler it will likely introduce non-standard runtime
-     requirements. There are of course many valid reasons to build with
-     unbundled compilers, but be aware it is generally unsupported and
-     left as an exercise to the reader.
-
-5.2 Cygwin
-==========
-
-Building on Cygwin is supported. The following are the recommended
-specifications for this platform; but is not necessarily the only
-configuration that is possible:
-
-   * Intel 32-bit or 64-bit hardware
-
-   * Cygwin, gcc 4.3.2
-
-   * yasm 0.7.1.2093 (for i386 or x86_64 architectures)
-
-     Note: As of this writing, Cygwin has available to it several
-     versions of gcc; only one of which may be found and used in the
-     path as `gcc' and `g++'. Configure will thus find what is probably
-     the older version of gcc in a typical Cygwin environment. If you
-     desire to build with the newer gcc, it is found in the path as
-     `gcc-4' and `g++-4' respectively and you must indicate to
-     configure the desired versions. The following syntax should do the
-     trick:
-
-     ../configure --gcc=gcc-4
-
-5.3 Linux
-=========
-
-Building on Linux is supported. The following are the recommended
-specifications for this platform; but is not necessarily the only
-configuration that is possible:
-
-   * Intel 32-bit or 64-bit hardware
-
-   * Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
-
-   * Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
-
-   * Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
-
-   * gcc 4.0.0 or higher is reported to work
-
-     Note: It is recommended to use the platform distribution's bundled
-     compiler for maximum C++ compatibility. If you build with a custom
-     compiler it will likely introduce non-standard runtime
-     requirements. There are of course many valid reasons to build with
-     unbundled compilers, but be aware it is generally unsupported and
-     left as an exercise to the reader.
-
diff --git a/00.Building.linux.txt b/00.Building.linux.txt
new file mode 100644
index 000000000..255acd491
--- /dev/null
+++ b/00.Building.linux.txt
@@ -0,0 +1,353 @@
+Guide to Building HandBrake svn2194 (2009030201) on Linux
+*********************************************************
+
+Table of Contents
+*****************
+
+1 Introduction
+2 Prerequisites
+3 QuickStart
+4 Overview
+5 Building via Terminal
+  5.1 Checkout Sources
+  5.2 Configure
+  5.3 Build
+  5.4 Make Targets
+    5.4.1 Global
+    5.4.2 General Modules
+    5.4.3 Contrib Modules
+    5.4.4 Contrib Aggregates
+
+
+1 Introduction
+**************
+
+This guide documents the recommended process to build HandBrake on
+Linux hosts from the official source-code repository. Building from any
+other source is not supported.
+
+2 Prerequisites
+***************
+
+The following are the recommended specifications for building on
+Linux; but is not necessarily the only configuration that is possible:
+
+   * Intel 32-bit or 64-bit kernel
+
+   * Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
+
+   * Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
+
+   * Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
+
+   * gcc 4.0.0 or higher is reported to work
+
+     Note: It is recommended to use the platform distribution's bundled
+     compiler for maximum C++ compatibility. If you build with a custom
+     compiler it will likely introduce non-standard runtime
+     requirements. There are of course many valid reasons to build with
+     unbundled compilers, but be aware it is generally unsupported and
+     left as an exercise to the reader.
+
+The GTK UI introduces some significant extra build requirements. If you
+intend to disable building the GUI with `configure --disable-gtk' you
+may not need any of these packages installed:
+
+   * build-essential
+
+   * autoconf
+
+   * intltool
+
+   * libtool
+
+   * zlib1g-dev
+
+   * libbz2-dev
+
+   * libglib2.0-dev
+
+   * libdbus-glib-1-dev
+
+   * libgtk2.0-dev
+
+   * libhal-dev
+
+   * libhal-storage-dev
+
+   * libgtkhtml3.14-dev
+
+   * libgstreamer0.10-dev
+
+   * libgstreamer-plugins-base0.10-dev
+
+The following general tools are used on various platforms and it is
+recommended you use these versions or similar:
+
+   * subversion - 1.5.5
+
+   * python - Python 2.4.6
+
+   * curl - curl 7.19.3 (or wget)
+
+   * m4 - GNU M4 1.4.6
+
+   * make - GNU Make 3.81
+
+   * patch - Patch 2.5.8
+
+   * tar - GNU tar 1.15.1
+
+   * wget - GNU Wget 1.11.4 (or curl)
+
+3 QuickStart
+************
+
+This chapter is for building from a terminal/shell environment in as
+few commands as possible. If more flexibility is required you should
+skip this chapter and jump to *Note overview::.
+
+     svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
+     cd hb-trunk
+     ./configure --launch
+
+The special option `--launch' selected launch mode and performs the
+following steps:
+
+   * assert scratch directory `build/' does not exist
+
+   * create scratch directory `build/'
+
+   * change to directory `build/'
+
+   * launch `make'
+
+   * capture build output to `build/log.txt'
+
+   * echo build output
+
+4 Overview
+**********
+
+Linux builds are performed from a terminal. There is no support for
+building from any IDEs.
+
+5 Building via Terminal
+***********************
+
+5.1 Checkout Sources
+====================
+
+Checkout HandBrake from the official source-code repository.
+
+     svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
+     cd hb-trunk
+
+Sources are checked out from the `trunk' branch. This document was
+generated from that very branch, and for example purposes, we will use
+exactly the same branch.
+
+If you have write-access to the repository, then you may add the
+appropriate login/password information as needed. It is recommended to
+use Subversion 1.5.0 or higher. Lower versions should also work.
+
+5.2 Configure
+=============
+
+Configure the build system.
+
+     rm -fr build/
+     mkdir build/
+     cd build/
+     ../configure
+
+Create a scratch directory which will contain all files created during
+the build process. The directory name is arbitrary but we recommend
+something simple and descriptive. One directory is required for each
+distinctly configured build. We name our directory `build' for example
+purposes.
+
+The `configure' utility accepts many options. It is recommended that
+you specify `--help' for the complete list of options. The following
+options are also documented here:
+
+`--help'
+     List available options.
+
+`--prefix=PREFIX'
+     Specify destination directory for final product install.  This
+     defaults to a reasonable platform-specific value.
+
+`--disable-xcode'
+     Disable driving the build through Xcode. If this option is
+     disabled only `HandBrakeCLI' will be produced and Xcode will not
+     be invoked. Mac OS X only.
+
+`--disable-gtk'
+     Disable building the GTK GUI on applicable platforms such as
+     Linux.
+
+`--debug=MODE'
+     Select debug mode. Must be one of `none', `min', `std', `max'.
+     This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
+
+`--optimize=MODE'
+     Select optimize mode. Must be one of `none', `speed', `size'.
+     This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
+
+`--arch=MODE'
+     Select build architecture. The available architectures vary by
+     platform. Most platforms support exactly one architecture except
+     Mac OS X which has support for various universal binary
+     architectures. The available choices are hard-coded per platform
+     and no sanity checks for the required tools are performed.
+
+`--gcc=EXE'
+     Specify the `gcc' executable to use where EXE is the executable
+     name which is either absolute or environment `PATH' is searched
+     accordingly.
+
+Clean-room procedures dictate that when certain factors change, old
+builds should be scrapped and new builds configured. This is the main
+reason for requiring a scratch directory; to promote consistent,
+reliable and clean software builds. The following is a short list of
+some of the reasons why someone may choose to scrap an existing build:
+
+   * configure with different options
+
+   * subversion working dir is updated and you want configure to
+     re-evaluate working dir metadata.
+
+   * build corruption is suspected
+
+There are generally two methods for scrapping a build. The `build'
+directory can be recusrively removed which has the effect of loosing
+your existing configuration but does guarantee no residuals are left
+behind. The other method is to ask the build system to perform an `make
+xclean'. This is known to work well but will leave empty directories
+behind. However, the configuration is left intact.
+
+5.3 Build
+=========
+
+Build main product. All necessary dependencies are also built if
+required.
+
+     make
+
+Parallel builds may optionally be enabled. Be aware that while a
+parallel build may save time on systems with additional cores, the
+output is often mixed, overlapped and sometimes even corrupted with
+binary characters. Thus if you experience a build issue, you should
+clean and redo the build in default serial mode to produce a readable
+log. The following command allows for up to 4 concurrent jobs via make:
+
+     make -j4
+
+5.4 Make Targets
+================
+
+The build system supports passing many kinds of targets some of which
+become very useful in normal development cycles. The targets by
+convention are lower-case words passed to `make'. Global targets are
+one-word targets. Scoped targets are usually two-words seperated by a
+period.
+
+5.4.1 Global
+------------
+
+`make'
+     Alias for `make build'.
+
+`make build'
+     Build main product. All necessary dependencies are also built if
+     required.
+
+`make clean'
+     Clean all build output excluding contrib modules. Configuration is
+     retained.
+
+`make xclean'
+     Clean all build output including contrib modules. Configuration is
+     retained.
+
+`make doc'
+     Build auto-generated project documentation. Various articles are
+     produced and may be found in `build/doc/articles'.
+
+5.4.2 General Modules
+---------------------
+
+General modules such as `libhb', `test' and `gtk' have the following
+scoped targets:
+
+`make MODULE.build'
+     Build MODULE.
+
+`make MODULE.clean'
+     Clean build output for MODULE.
+
+5.4.3 Contrib Modules
+---------------------
+
+Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
+`lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
+`libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
+`xvidcore' and `zlib' have the following scoped targets:
+
+`make MODULE.fetch'
+     Download source tarball from the Internet and save to
+     `TOP/downloads' directory. No checksumming is performed.
+
+`make MODULE.extract'
+     Extract source tarball into `build' tree.
+
+`make MODULE.patch'
+     Apply appropriate patches (if any) to module sources.
+
+`make MODULE.configure'
+     Configure module sources.  This usually invokes autotool configure.
+
+`make MODULE.build'
+     Build module.  This usually invokes autotool build.
+
+`make MODULE.install'
+     Install module products such as headers and libraries into `build'
+     tree.  This usually invokes autotool install.
+
+`make MODULE.uninstall'
+     Uninstall module products; generally the reverse of install.  This
+     usually invokes autotool uninstall.
+
+`make MODULE.clean'
+     Clean module; generally the reverse of build.  This usually
+     invokes autotool clean.
+
+`make MODULE.xclean'
+     Extra clean module; first invokes uninstall then recursively
+     removes the module build directory.
+
+5.4.4 Contrib Aggregates
+------------------------
+
+For convenience, the following targets aggregate the all contrib
+modules' respective targets together:
+
+   * make contrib.fetch
+
+   * make contrib.extract
+
+   * make contrib.patch
+
+   * make contrib.configure
+
+   * make contrib.build
+
+   * make contrib.install
+
+   * make contrib.uninstall
+
+   * make contrib.clean
+
+   * make contrib.xclean
+
diff --git a/00.Building.osx.txt b/00.Building.osx.txt
new file mode 100644
index 000000000..5f6ef108e
--- /dev/null
+++ b/00.Building.osx.txt
@@ -0,0 +1,420 @@
+Guide to Building HandBrake svn2194 (2009030201) on Mac OS X
+************************************************************
+
+     Warning: Parallel builds on Mac OS X are currently broken when
+     building in a terminal with Xcode. You must not use the `make -jN'
+     jobs option. A workaround is available if you do not need to build
+     HandBrake.app (MacGUI): use `configure --disable-xcode' to disable
+     Xcode.
+
+Table of Contents
+*****************
+
+1 Introduction
+2 Prerequisites
+3 QuickStart
+4 Overview
+5 Building via Terminal
+  5.1 Checkout Sources
+  5.2 Configure
+  5.3 Build
+  5.4 Make Targets
+    5.4.1 Global
+    5.4.2 General Modules
+    5.4.3 Contrib Modules
+    5.4.4 Contrib Aggregates
+6 Building via Xcode
+  6.1 Checkout Sources
+  6.2 Build
+
+
+1 Introduction
+**************
+
+This guide documents the recommended process to build HandBrake on
+Mac OS X hosts from the official source-code repository. Building from
+any other source is not supported.
+
+2 Prerequisites
+***************
+
+Building on Mac OS X is well supported. It is the reference platform
+for HandBrake. The following are the recommended specifications for
+this platform; but is not necessarily the only configuration that is
+possible:
+
+   * Mac Intel hardware
+
+   * Mac OS X 10.5.6
+
+   * Xcode-3.1.2
+
+   * gcc 4.0.1 (Apple Inc. build 5490)
+
+   * yasm 0.7.2.2153 (for i386 and x86_64 architectures)
+
+     Note: It is recommended to use the platform distribution's bundled
+     compiler for maximum C++ compatibility. If you build with a custom
+     compiler it will likely introduce non-standard runtime
+     requirements. There are of course many valid reasons to build with
+     unbundled compilers, but be aware it is generally unsupported and
+     left as an exercise to the reader.
+
+The following general tools are used on various platforms and it is
+recommended you use these versions or similar:
+
+   * subversion - 1.5.5
+
+   * python - Python 2.4.6
+
+   * curl - curl 7.19.3 (or wget)
+
+   * m4 - GNU M4 1.4.6
+
+   * make - GNU Make 3.81
+
+   * patch - Patch 2.5.8
+
+   * tar - GNU tar 1.15.1
+
+   * wget - GNU Wget 1.11.4 (or curl)
+
+3 QuickStart
+************
+
+This chapter is for building from a terminal/shell environment in as
+few commands as possible. If more flexibility is required you should
+skip this chapter and jump to *Note overview::.
+
+     svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
+     cd hb-trunk
+     ./configure --launch
+
+The special option `--launch' selected launch mode and performs the
+following steps:
+
+   * assert scratch directory `build/' does not exist
+
+   * create scratch directory `build/'
+
+   * change to directory `build/'
+
+   * launch `make'
+
+   * capture build output to `build/log.txt'
+
+   * echo build output
+
+4 Overview
+**********
+
+The two general methods to build on Mac OS X are building from terminal
+or Xcode. The preferred method for automated and repeatable builds is
+to use the terminal. Otherwise the choice is generally up to the
+individual. In essence, the terminal actually invokes `xcodebuild' to
+build the very same targets contained in the Xcode project.
+
+5 Building via Terminal
+***********************
+
+5.1 Checkout Sources
+====================
+
+Checkout HandBrake from the official source-code repository.
+
+     svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
+     cd hb-trunk
+
+Sources are checked out from the `trunk' branch. This document was
+generated from that very branch, and for example purposes, we will use
+exactly the same branch.
+
+If you have write-access to the repository, then you may add the
+appropriate login/password information as needed. It is recommended to
+use Subversion 1.5.0 or higher. Lower versions should also work.
+
+5.2 Configure
+=============
+
+Configure the build system.
+
+     rm -fr build/
+     mkdir build/
+     cd build/
+     ../configure
+
+Create a scratch directory which will contain all files created during
+the build process. The directory name is arbitrary but we recommend
+something simple and descriptive. One directory is required for each
+distinctly configured build. We name our directory `build' for example
+purposes.
+
+The `configure' utility accepts many options. It is recommended that
+you specify `--help' for the complete list of options. The following
+options are also documented here:
+
+`--help'
+     List available options.
+
+`--prefix=PREFIX'
+     Specify destination directory for final product install.  This
+     defaults to a reasonable platform-specific value.
+
+`--disable-xcode'
+     Disable driving the build through Xcode. If this option is
+     disabled only `HandBrakeCLI' will be produced and Xcode will not
+     be invoked. Mac OS X only.
+
+`--disable-gtk'
+     Disable building the GTK GUI on applicable platforms such as
+     Linux.
+
+`--debug=MODE'
+     Select debug mode. Must be one of `none', `min', `std', `max'.
+     This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
+
+`--optimize=MODE'
+     Select optimize mode. Must be one of `none', `speed', `size'.
+     This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
+
+`--arch=MODE'
+     Select build architecture. The available architectures vary by
+     platform. Most platforms support exactly one architecture except
+     Mac OS X which has support for various universal binary
+     architectures. The available choices are hard-coded per platform
+     and no sanity checks for the required tools are performed.
+
+`--gcc=EXE'
+     Specify the `gcc' executable to use where EXE is the executable
+     name which is either absolute or environment `PATH' is searched
+     accordingly.
+
+Clean-room procedures dictate that when certain factors change, old
+builds should be scrapped and new builds configured. This is the main
+reason for requiring a scratch directory; to promote consistent,
+reliable and clean software builds. The following is a short list of
+some of the reasons why someone may choose to scrap an existing build:
+
+   * configure with different options
+
+   * subversion working dir is updated and you want configure to
+     re-evaluate working dir metadata.
+
+   * build corruption is suspected
+
+There are generally two methods for scrapping a build. The `build'
+directory can be recusrively removed which has the effect of loosing
+your existing configuration but does guarantee no residuals are left
+behind. The other method is to ask the build system to perform an `make
+xclean'. This is known to work well but will leave empty directories
+behind. However, the configuration is left intact.
+
+5.3 Build
+=========
+
+Build main product. All necessary dependencies are also built if
+required.
+
+     make
+
+Parallel builds may optionally be enabled. Be aware that while a
+parallel build may save time on systems with additional cores, the
+output is often mixed, overlapped and sometimes even corrupted with
+binary characters. Thus if you experience a build issue, you should
+clean and redo the build in default serial mode to produce a readable
+log. The following command allows for up to 4 concurrent jobs via make:
+
+     make -j4
+
+5.4 Make Targets
+================
+
+The build system supports passing many kinds of targets some of which
+become very useful in normal development cycles. The targets by
+convention are lower-case words passed to `make'. Global targets are
+one-word targets. Scoped targets are usually two-words seperated by a
+period.
+
+5.4.1 Global
+------------
+
+`make'
+     Alias for `make build'.
+
+`make build'
+     Build main product. All necessary dependencies are also built if
+     required.
+
+`make clean'
+     Clean all build output excluding contrib modules. Configuration is
+     retained.
+
+`make xclean'
+     Clean all build output including contrib modules. Configuration is
+     retained.
+
+`make doc'
+     Build auto-generated project documentation. Various articles are
+     produced and may be found in `build/doc/articles'.
+
+5.4.2 General Modules
+---------------------
+
+General modules such as `libhb', `test' and `gtk' have the following
+scoped targets:
+
+`make MODULE.build'
+     Build MODULE.
+
+`make MODULE.clean'
+     Clean build output for MODULE.
+
+5.4.3 Contrib Modules
+---------------------
+
+Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
+`lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
+`libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
+`xvidcore' and `zlib' have the following scoped targets:
+
+`make MODULE.fetch'
+     Download source tarball from the Internet and save to
+     `TOP/downloads' directory. No checksumming is performed.
+
+`make MODULE.extract'
+     Extract source tarball into `build' tree.
+
+`make MODULE.patch'
+     Apply appropriate patches (if any) to module sources.
+
+`make MODULE.configure'
+     Configure module sources.  This usually invokes autotool configure.
+
+`make MODULE.build'
+     Build module.  This usually invokes autotool build.
+
+`make MODULE.install'
+     Install module products such as headers and libraries into `build'
+     tree.  This usually invokes autotool install.
+
+`make MODULE.uninstall'
+     Uninstall module products; generally the reverse of install.  This
+     usually invokes autotool uninstall.
+
+`make MODULE.clean'
+     Clean module; generally the reverse of build.  This usually
+     invokes autotool clean.
+
+`make MODULE.xclean'
+     Extra clean module; first invokes uninstall then recursively
+     removes the module build directory.
+
+5.4.4 Contrib Aggregates
+------------------------
+
+For convenience, the following targets aggregate the all contrib
+modules' respective targets together:
+
+   * make contrib.fetch
+
+   * make contrib.extract
+
+   * make contrib.patch
+
+   * make contrib.configure
+
+   * make contrib.build
+
+   * make contrib.install
+
+   * make contrib.uninstall
+
+   * make contrib.clean
+
+   * make contrib.xclean
+
+6 Building via Xcode
+********************
+
+6.1 Checkout Sources
+====================
+
+Checkout HandBrake from the official source-code repository.
+
+     svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
+     cd hb-trunk
+
+Sources are checked out from the `trunk' branch. This document was
+generated from that very branch, and for example purposes, we will use
+exactly the same branch.
+
+If you have write-access to the repository, then you may add the
+appropriate login/password information as needed. It is recommended to
+use Subversion 1.5.0 or higher. Lower versions should also work.
+
+6.2 Build
+=========
+
+In Xcode perform the following steps to build the default configuration:
+
+   * open `macosx/HandBrake.xcodeproj'
+
+   * select active configuration standard
+
+   * select active target HandBrake
+
+   * click Build or Build and Go
+
+The first time it builds will take a bit of time. You may use the Build
+Results window to watch it progress. A large partof the build is
+invoking the external build system which poduces quite a lot of log
+output. Much of that output are warnings and errors that are part of
+the normal build process for 3rd-party contributed modules so in
+general you need not do anything. However, if Xcode itself reports the
+build failed, then you must take corrective action.
+
+Unfortunately, due to limitations of Xcode we do not have hooks in
+place to offer finer-grained control over per-module make actions for
+the (external) build system. Thus, you will have to use terminal to
+accomplish those tasks. Just `cd' into the build directory which is
+associated with your active configuration and perform any necessary
+`make' commands. Be careful not to issue commands from the terminal
+simultaneously with Xcode tasks as that will confuse both Xcode and
+make and likely corrupt your build directory.
+
+When you click clean in Xcode it will not perform an external build
+clean. Basically HandBrakeCLI and HandBrake.app are the only products
+which have full Xcode iterative development flexibility.
+
+Each configuration uses a different `build' directory. This makes it
+possible to build each configuration and switch between them without
+losing their respective build state. The description of each
+configuration and the name convention for build directories are as
+follows:
+
+`standard'
+     This configuration will build to the host native architecture.
+     Build directory is `build.standard' .  The standard variant
+     produces optimized code without debug information.
+
+`debug'
+     This configuration will build to the host native architecture.
+     Build directory is `build.standard' .  The debug variant produces
+     unoptimized code with debug information.
+
+`standard.i386'
+     This configuration is used to build for the i386 architecture.
+     Build directory is `build.standard.i386' .
+
+`standard.x86_64'
+     This configuration is used to build for the x86_64 architecture.
+     Build directory is `build.standard.x86_64' .
+
+`standard.ppc'
+     This configuration is used to build for the ppc architecture.
+     Build directory is `build.standard.ppc' .
+
+`standard.ppc64'
+     This configuration is used to build for the ppc64 architecture.
+     Build directory is `build.standard.ppc64' .
+
diff --git a/doc/module.defs b/doc/module.defs
index 16929f03d..468196c96 100644
--- a/doc/module.defs
+++ b/doc/module.defs
@@ -21,10 +21,13 @@ DOC.texi2html.out = $(patsubst $(DOC.in/)texi/%.texi,$(DOC.out.articles/)html/%.
 DOC.texi2txt.out  = $(patsubst $(DOC.in/)texi/%.texi,$(DOC.out.articles/)txt/%.txt,$(DOC.texi.articles))
 DOC.texi2xml.out  = $(patsubst $(DOC.in/)texi/%.texi,$(DOC.out.articles/)xml/%.xml,$(DOC.texi.articles))
 
+DOC.xml2wiki.out  = $(DOC.texi2xml.out:$(DOC.out.articles/)xml/%.xml=$(DOC.out.articles/)wiki/%.wiki)
+
 BUILD.out += $(DOC.m4.out)
 BUILD.out += $(DOC.texi2html.out)
 BUILD.out += $(DOC.texi2txt.out)
 BUILD.out += $(DOC.texi2xml.out)
+BUILD.out += $(DOC.xml2wiki.out)
 
 ###############################################################################
 
@@ -39,3 +42,7 @@ MAKEINFO.flags.html = --html --no-headers --no-split
 MAKEINFO.flags.txt  = --plaintext --no-headers
 MAKEINFO.flags.xml  = --xml --output-indent=4
 MAKEINFO            = $(MAKEINFO.exe) $(MAKEINFO.flags) $(MAKEINFO.flags.$(1)) $(2) -o $(3)
+
+XML2WIKI.exe   = python3.0 $(DOC.in/)xml2wiki.py
+XML2WIKI.flags = --date --toc
+XML2WIKI       = $(XML2WIKI.exe) $(XML2WIKI.flags) $(1) > $(2)
diff --git a/doc/module.rules b/doc/module.rules
index f318cf2a4..22d97e672 100644
--- a/doc/module.rules
+++ b/doc/module.rules
@@ -1,8 +1,9 @@
 $(eval $(call import.MODULE.rules,DOC))
 
-doc: doc.articles
+doc: doc.txt
 
-doc.articles: $(DOC.texi2txt.out)
+doc.txt: $(DOC.texi2txt.out)
+doc.wiki: $(DOC.xml2wiki.out)
 
 doc.clean:
 	$(RM.exe) -fr $(DOC.out/)
@@ -14,7 +15,23 @@ $(DOC.texi2txt.out): $(DOC.out.articles/)txt/%.txt: $(DOC.in/)texi/%.texi
 	$(call MAKEINFO,txt,$<,$@)
 	@echo $^
 
+$(DOC.texi2xml.out): | $(DOC.m4.out)
+$(DOC.texi2xml.out): | $(dir $(DOC.texi2xml.out))
+$(DOC.texi2xml.out): $(DOC.texi.includes)
+$(DOC.texi2xml.out): $(DOC.out.articles/)xml/%.xml: $(DOC.in/)texi/%.texi
+	$(call MAKEINFO,xml,$<,$@)
+	@echo $^
+
+$(DOC.xml2wiki.out): | $(dir $(DOC.xml2wiki.out))
+$(DOC.xml2wiki.out): $(DOC.out.articles/)wiki/%.wiki: $(DOC.out.articles/)xml/%.xml
+	$(call XML2WIKI,$<,$@)
+
 $(DOC.m4.out): | $(dir $(DOC.m4.out))
 $(DOC.m4.out): $(DOC.M4.deps)
 $(DOC.m4.out): $(DOC.out/)%: $(DOC.in/)%.m4
 	$(call DOC.M4,$@,$<)
+
+mike:
+	@echo $(DOC.texi2xml.out)
+	@echo $(DOC.xml2wiki.out)
+	@echo ok
diff --git a/doc/texi/Building.cygwin.texi b/doc/texi/Building.cygwin.texi
new file mode 100644
index 000000000..a2fda9ab3
--- /dev/null
+++ b/doc/texi/Building.cygwin.texi
@@ -0,0 +1,45 @@
+@input texinfo @c -*- Texinfo -*-
+@c %**start of header
+@setfilename Building.cygwin.info
+@include base/article.texi
+@include building/command.texi
+@paragraphindent none
+
+@set BG.platform cygwin
+@c %**end of header
+
+@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}}
+@contents
+@include building/chapter.introduction.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{prerequisites}
+@chapter Prerequisites
+The following are the recommended specifications for building on @value{OS.cygwin}; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Intel 32-bit or 64-bit hardware (only 32-bit product binaries are supported)
+@item @value{OS.cygwin}, gcc 4.2.4
+@item yasm 0.7.2.2153 (for i386 or x86_64 architectures)
+@end itemize
+
+@include building/prerequisites.bundled.texi
+
+@quotation Note
+As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and used in the path as @code{gcc} and @code{g++}. Configure will thus find what is probably the older version of gcc in a typical @value{OS.cygwin} environment. If you desire to build with the newer gcc, it is found in the path as @command{gcc-4} and @command{g++-4} respectively and you must indicate to configure the desired versions. The following syntax should do the trick:
+@end quotation
+
+@example
+../configure --gcc=gcc-4
+@end example
+
+@include building/prerequisites.common.texi
+
+@c %**-------------------------------------------------------------------------
+@include building/chapter.quickstart.texi
+
+@anchor{overview}
+@chapter Overview
+@value{OS.cygwin} builds are performed from a @b{terminal}. There is no support for building from any IDEs.
+
+@include building/chapter.via.terminal.texi
diff --git a/doc/texi/Building.linux.texi b/doc/texi/Building.linux.texi
new file mode 100644
index 000000000..b7aa14505
--- /dev/null
+++ b/doc/texi/Building.linux.texi
@@ -0,0 +1,58 @@
+@input texinfo @c -*- Texinfo -*-
+@c %**start of header
+@setfilename Building.linux.info
+@include base/article.texi
+@include building/command.texi
+@paragraphindent none
+
+@set BG.platform linux
+@c %**end of header
+
+@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}}
+@contents
+@include building/chapter.introduction.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{prerequisites}
+@chapter Prerequisites
+The following are the recommended specifications for building on @value{OS.linux}; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Intel 32-bit or 64-bit kernel
+@item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
+@item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
+@item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
+@item gcc 4.0.0 or higher is reported to work
+@end itemize
+
+@include building/prerequisites.bundled.texi
+
+The @b{GTK UI} introduces some significant extra build requirements. If you intend to disable building the GUI with @command{configure --disable-gtk} you may not need any of these packages installed:
+
+@itemize @bullet
+@item build-essential
+@item autoconf
+@item intltool
+@item libtool
+@item zlib1g-dev
+@item libbz2-dev
+@item libglib2.0-dev
+@item libdbus-glib-1-dev
+@item libgtk2.0-dev
+@item libhal-dev
+@item libhal-storage-dev
+@item libgtkhtml3.14-dev
+@item libgstreamer0.10-dev
+@item libgstreamer-plugins-base0.10-dev
+@end itemize
+
+@include building/prerequisites.common.texi
+
+@c %**-------------------------------------------------------------------------
+@include building/chapter.quickstart.texi
+
+@anchor{overview}
+@chapter Overview
+@value{OS.linux} builds are performed from a @b{terminal}. There is no support for building from any IDEs.
+
+@include building/chapter.via.terminal.texi
diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi
new file mode 100644
index 000000000..00501c4c6
--- /dev/null
+++ b/doc/texi/Building.osx.texi
@@ -0,0 +1,45 @@
+@input texinfo @c -*- Texinfo -*-
+@c %**start of header
+@setfilename Building.osx.info
+@include base/article.texi
+@include building/command.texi
+@paragraphindent none
+
+@set BG.platform osx
+@c %**end of header
+
+@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}}
+
+@quotation Warning
+Parallel builds on @value{OS.osx} are currently broken when building in a @b{terminal} with Xcode. You @b{must not use} the @command{make -jN} jobs option. A workaround is available if you do not need to build HandBrake.app (MacGUI): use @command{configure --disable-xcode} to disable Xcode.
+@end quotation
+
+@contents
+@include building/chapter.introduction.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{prerequisites}
+@chapter Prerequisites
+Building on @value{OS.osx} is well supported. It is the reference platform for @value{HB.name}. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Mac Intel hardware
+@item @value{OS.osx} 10.5.6
+@item Xcode-3.1.2
+@item gcc 4.0.1 (Apple Inc. build 5490)
+@item yasm 0.7.2.2153 (for i386 and x86_64 architectures)
+@end itemize
+
+@include building/prerequisites.bundled.texi
+@include building/prerequisites.common.texi
+
+@c %**-------------------------------------------------------------------------
+@include building/chapter.quickstart.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{overview}
+@chapter Overview
+The two general methods to build on @value{OS.osx} are building from @b{terminal} or @b{Xcode}. The preferred method for automated and repeatable builds is to use the terminal. Otherwise the choice is generally up to the individual. In essence, the terminal actually invokes @command{xcodebuild} to build the very same targets contained in the Xcode project.
+
+@include building/chapter.via.terminal.texi
+@include building/chapter.via.xcode.texi
diff --git a/doc/texi/build/command.texi b/doc/texi/build/command.texi
deleted file mode 100644
index db6b0b493..000000000
--- a/doc/texi/build/command.texi
+++ /dev/null
@@ -1,27 +0,0 @@
-@macro COMMAND.checkout{}
-svn checkout @value{HB.repo.url} @value{HB.acro.lower}-@value{HB.repo.branch}
-cd @value{HB.acro.lower}-@value{HB.repo.branch}
-@end macro
-
-@macro COMMAND.configure.launch{}
-./configure --launch
-@end macro
-
-@macro COMMAND.configure{}
-rm -fr build/
-mkdir build/
-cd build/
-../configure
-@end macro
-
-@macro COMMAND.build{}
-make
-@end macro
-
-@macro COMMAND.clean{}
-make clean
-@end macro
-
-@macro COMMAND.xclean{}
-make xclean
-@end macro
diff --git a/doc/texi/building/chapter.introduction.texi b/doc/texi/building/chapter.introduction.texi
new file mode 100644
index 000000000..9c6053349
--- /dev/null
+++ b/doc/texi/building/chapter.introduction.texi
@@ -0,0 +1,3 @@
+@anchor{introduction}
+@chapter Introduction
+This guide documents the recommended process to build @value{HB.name} on @value{OS.@value{BG.platform}} hosts from the official source-code repository. @b{Building from any other source is not supported}.
diff --git a/doc/texi/building/chapter.overview.texi b/doc/texi/building/chapter.overview.texi
new file mode 100644
index 000000000..29dec0394
--- /dev/null
+++ b/doc/texi/building/chapter.overview.texi
@@ -0,0 +1,21 @@
+@anchor{overview}
+@chapter Build Overview
+The build system has several
+
+This chapter is for building from a terminal/shell environment in as few commands as possible. If more flexibility is required you should skip this chapter and jump to @ref{process}.
+
+@example
[email protected]{}
+./configure --launch
+@end example
+
+The special option @command{--launch} selected launch mode and performs the following steps:
+
+@itemize
+@item assert scratch directory @file{build/} does not exist
+@item create scratch directory @file{build/}
+@item change to directory @file{build/}
+@item launch @command{make}
+@item capture build output to @file{build/log.txt}
+@item echo build output
+@end itemize
diff --git a/doc/texi/building/chapter.quickstart.texi b/doc/texi/building/chapter.quickstart.texi
new file mode 100644
index 000000000..7829087e4
--- /dev/null
+++ b/doc/texi/building/chapter.quickstart.texi
@@ -0,0 +1,19 @@
+@anchor{quickstart}
+@chapter QuickStart
+This chapter is for building from a terminal/shell environment in as few commands as possible. If more flexibility is required you should skip this chapter and jump to @ref{overview}.
+
+@example
[email protected]{}
+./configure --launch
+@end example
+
+The special option @command{--launch} selected launch mode and performs the following steps:
+
+@itemize
+@item assert scratch directory @file{build/} does not exist
+@item create scratch directory @file{build/}
+@item change to directory @file{build/}
+@item launch @command{make}
+@item capture build output to @file{build/log.txt}
+@item echo build output
+@end itemize
diff --git a/doc/texi/BuildUserGuide.texi b/doc/texi/building/chapter.via.terminal.texi
index 7fb3a4d66..5f2135a61 100644
--- a/doc/texi/BuildUserGuide.texi
+++ b/doc/texi/building/chapter.via.terminal.texi
@@ -1,69 +1,41 @@
-@input texinfo @c -*- Texinfo -*-
-@c %**start of header
-@setfilename BuildUserGuide.info
-@include base/article.texi
-@include build/command.texi
-@paragraphindent none
-@c %**end of header
-
-@majorheading @value{HB.title} Build User Guide
-@contents
+@anchor{terminal}
+@chapter Building via Terminal
 
 @c %**-------------------------------------------------------------------------
-@chapter Introduction
-This guide documents the recommended process to build @value{HB.name} from the official source-code repository. @b{Building from any other source is not unsupported}.
-
-@chapter Quickstart
-This chapter is for the impatient or those just looking for a quick summary of the commands used to launch a typical build with the fewest commands possible. For more control over the build process please skip this section and jump to @ref{Build Process} for full details.
-
-@example
[email protected]{}
[email protected]{}
-@end example
-
-The above is an special streamlined invocation of @command{configure} which performs the following steps automatically:
-
-@itemize
-@item assert scratch directory @file{build/} does not exist
-@item create scratch directory @file{build/}
-@item change to directory @file{build/}
-@item launch @command{make}
-@item capture build output to @file{build/log.txt}
-@item echo build output
-@end itemize
-
-@c %**-------------------------------------------------------------------------
-@anchor{Build Process}
-@chapter Build Process
-
-@anchor{Checkout}
+@anchor{terminal.checkout}
 @section Checkout Sources
-Checkout @value{HB.name} from the official source-code repository.
-
-@example
[email protected]{}
-@end example
+@include building/method.checkout.texi
 
-Sources are checked out from the @samp{@value{HB.repo.branch}} branch. This document was generated from that very branch, and for example purposes, we will use exactly the same branch.
-
-If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.5.0 or higher. Lower versions should also work.
-
-@anchor{Configure}
+@c %**-------------------------------------------------------------------------
+@anchor{terminal.configure}
 @section Configure
 Configure the build system.
 
 @example
[email protected]{}
+rm -fr build/
+mkdir build/
+cd build/
+../configure
 @end example
 
 Create a scratch directory which will contain all files created during the build process. The directory name is arbitrary but we recommend something simple and descriptive. One directory is required for each distinctly configured build. We name our directory @file{build} for example purposes.
 
-The @command{configure} utility accepts many options. It is recommended that you specify @command{--help} for the complete list of options. The following options are detailed:
+The @command{configure} utility accepts many options. It is recommended that you specify @command{--help} for the complete list of options. The following options are also documented here:
 
 @table @samp
 @item --help
 List available options.
 
+@item --prefix=PREFIX
+Specify destination directory for final product install.
+This defaults to a reasonable platform-specific value.
+
+@item --disable-xcode
+Disable driving the build through Xcode. If this option is disabled only @command{HandBrakeCLI} will be produced and Xcode will not be invoked. @value{OS.osx} only.
+
+@item --disable-gtk
+Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
+
 @item --debug=MODE
 Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}.
 This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}.
@@ -87,14 +59,15 @@ Clean-room procedures dictate that when certain factors change, old builds shoul
 @item build corruption is suspected
 @end itemize
 
-There are generally two methods for scrapping a build. The @file{build} directory can be recusrively removed which has the effect of loosing your existing configuration but does guarantee no residuals are left behind. The other method is to use ask the build system to perform an @command{xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact. See @ref{Extra Clean} for further details.
+There are generally two methods for scrapping a build. The @file{build} directory can be recusrively removed which has the effect of loosing your existing configuration but does guarantee no residuals are left behind. The other method is to ask the build system to perform an @command{make xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact.
 
-@anchor{Build}
+@c %**-------------------------------------------------------------------------
+@anchor{terminal.build}
 @section Build
 Build main product. All necessary dependencies are also built if required.
 
 @example
[email protected]{}
+make
 @end example
 
 Parallel builds may optionally be enabled. Be aware that while a parallel build may save time on systems with additional cores, the output is often mixed, overlapped and sometimes even corrupted with binary characters. Thus if you experience a build issue, you should clean and redo the build in default serial mode to produce a readable log. The following command allows for up to 4 concurrent jobs via make:
@@ -103,30 +76,14 @@ Parallel builds may optionally be enabled. Be aware that while a parallel build
 make -j4
 @end example
 
-@anchor{Clean}
-@section Clean
-Clean all build output excluding contrib modules. Configuration is retained.
-
-@example
[email protected]{}
-@end example
-
-@anchor{Extra Clean}
-@section Extra Clean
-Clean all build output including contrib modules. Configuration is retained.
-
-@example
[email protected]{}
-@end example
-
 @c %**-------------------------------------------------------------------------
-@anchor{Make Targets}
-@chapter Make Targets
+@anchor{terminal.targets}
+@section Make Targets
 
 The build system supports passing many kinds of targets some of which become very useful in normal development cycles. The targets by convention are lower-case words passed to @command{make}. Global targets are one-word targets. Scoped targets are usually two-words seperated by a period.
 
-@anchor{Global Targets}
-@section Global
+@anchor{terminal.targets.global}
+@subsection Global
 
 @table @samp
 @item make
@@ -140,12 +97,15 @@ Clean all build output excluding contrib modules. Configuration is retained.
 
 @item make xclean
 Clean all build output including contrib modules. Configuration is retained.
+
+@item make doc
+Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}.
 @end table
 
-@anchor{General Module Targets}
-@section General Modules
+@anchor{terminal.targets.general}
+@subsection General Modules
 
-General modules such as @samp{libhb} and @samp{test} have the following scoped targets:
+General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets:
 
 @table @samp
 @item make @i{MODULE}.build
@@ -155,8 +115,8 @@ Build @i{MODULE}.
 Clean build output for @i{MODULE}.
 @end table
 
-@anchor{Contrib Module Targets}
-@section Contrib Modules
+@anchor{terminal.targets.contrib}
+@subsection Contrib Modules
 
 Contrib modules such as @samp{a52dec}, @samp{bzip2}, @samp{faac}, @samp{faad2}, @samp{ffmpeg}, @samp{lame}, @samp{libdca}, @samp{libdvdread}, @samp{libmkv}, @samp{libmp4v2}, @samp{libogg}, @samp{libsamplerate}, @samp{libtheora}, @samp{libvorbis}, @samp{mpeg2dec}, @samp{x264}, @samp{xvidcore} and @samp{zlib} have the following scoped targets:
 
@@ -194,8 +154,8 @@ This usually invokes autotool clean.
 Extra clean module; first invokes uninstall then recursively removes the module build directory.
 @end table
 
-@anchor{Contrib Aggregate Targets}
-@section Contrib Aggregate
+@anchor{terminal.targets.contrib.aggregate}
+@subsection Contrib Aggregates
 
 For convenience, the following targets aggregate the all contrib modules' respective targets together:
 
@@ -210,71 +170,3 @@ For convenience, the following targets aggregate the all contrib modules' respec
 @item make contrib.clean
 @item make contrib.xclean
 @end itemize
-
-@c %**-------------------------------------------------------------------------
-@anchor{Platform}
-@chapter Platform Requirements and Notes
-
-The build system supports various platforms of interest to the project. However this does not mean it supports all plaforms. If the platform is not listed in this chapter, then it is not supported.
-
-The following tools are used on various platforms and it is recommended you use these versions or newer:
-
-@itemize @bullet
-@item python - Python 2.4.6
-@item curl - curl 7.19.3 (or wget)
-@item m4 - GNU M4 1.4.6
-@item make - GNU Make 3.81
-@item patch - Patch 2.5.8
-@item tar - GNU tar 1.15.1
-@item wget - GNU Wget 1.11.4 (or curl)
-@end itemize
-
-@anchor{@value{OS.osx}}
-@section @value{OS.osx}
-
-Building on @value{OS.osx} is well supported. It is the reference platform for @value{HB.name}. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
-
-@itemize @bullet
-@item Mac Intel hardware
-@item @value{OS.osx} 10.5.6
-@item Xcode-3.1.2
-@item gcc 4.0.1 (Apple Inc. build 5490)
-@item yasm 0.7.2.2153 (for i386 or x86_64 architectures)
-@end itemize
-
-@include build/platform.common.bundled.texi
-
-@anchor{@value{OS.cygwin}}
-@section @value{OS.cygwin}
-
-Building on @value{OS.cygwin} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
-
-@itemize @bullet
-@item Intel 32-bit or 64-bit hardware
-@item @value{OS.cygwin}, gcc 4.3.2
-@item yasm 0.7.1.2093 (for i386 or x86_64 architectures)
-@end itemize
-
-@quotation Note
-As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and
-used in the path as @code{gcc} and @code{g++}. Configure will thus find what is probably the older version of gcc in a typical @value{OS.cygwin} environment. If you desire to build with the newer gcc, it is found in the path as @command{gcc-4} and @command{g++-4} respectively and you must indicate to configure the desired versions. The following syntax should do the trick:
-@end quotation
-
-@example
-../configure --gcc=gcc-4
-@end example
-
-@anchor{@value{OS.linux}}
-@section @value{OS.linux}
-
-Building on @value{OS.linux} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
-
-@itemize @bullet
-@item Intel 32-bit or 64-bit hardware
-@item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
-@item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
-@item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
-@item gcc 4.0.0 or higher is reported to work
-@end itemize
-
-@include build/platform.common.bundled.texi
diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi
new file mode 100644
index 000000000..f01874522
--- /dev/null
+++ b/doc/texi/building/chapter.via.xcode.texi
@@ -0,0 +1,49 @@
+@anchor{xcode}
+@chapter Building via Xcode
+
+@c %**-------------------------------------------------------------------------
+@anchor{xcode.checkout}
+@section Checkout Sources
+@include building/method.checkout.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{xcode.build}
+@section Build
+In Xcode perform the following steps to build the default configuration:
+
+@itemize
+@item open @file{macosx/HandBrake.xcodeproj}
+@item select active configuration @b{standard}
+@item select active target @b{HandBrake}
+@item click @b{Build} or @b{Build and Go}
+@end itemize
+
+The first time it builds will take a bit of time. You may use the Build Results window to watch it progress. A large partof the build is invoking the external build system which poduces quite a lot of log output. Much of that output are warnings and errors that are part of the normal build process for 3rd-party contributed modules so in general you need not do anything. However, if Xcode itself reports the build failed, then you must take corrective action.
+
+Unfortunately, due to limitations of Xcode we do not have hooks in place to offer finer-grained control over per-module make actions for the (external) build system. Thus, you will have to use @b{terminal} to accomplish those tasks. Just @command{cd} into the build directory which is associated with your active configuration and perform any necessary @command{make} commands. @b{Be careful not to issue commands from the terminal simultaneously with Xcode tasks} as that will confuse both Xcode and make and likely corrupt your build directory.
+
+When you click @b{clean} in Xcode it will not perform an external build clean. Basically @b{HandBrakeCLI} and @b{HandBrake.app} are the only products which have full Xcode iterative development flexibility.
+
+Each configuration uses a different @file{build} directory. This makes it possible to build each configuration and switch between them without losing their respective build state. The description of each configuration and the name convention for build directories are as follows:
+
+@table @samp
+@item standard
+This configuration will build to the host native architecture. Build directory is @file{build.standard} .
+The standard variant produces optimized code without debug information.
+
+@item debug
+This configuration will build to the host native architecture. Build directory is @file{build.standard} .
+The debug variant produces unoptimized code with debug information.
+
+@item standard.i386
+This configuration is used to build for the i386 architecture. Build directory is @file{build.standard.i386} .
+
+@item standard.x86_64
+This configuration is used to build for the x86_64 architecture. Build directory is @file{build.standard.x86_64} .
+
+@item standard.ppc
+This configuration is used to build for the ppc architecture. Build directory is @file{build.standard.ppc} .
+
+@item standard.ppc64
+This configuration is used to build for the ppc64 architecture. Build directory is @file{build.standard.ppc64} .
+@end table
diff --git a/doc/texi/building/command.texi b/doc/texi/building/command.texi
new file mode 100644
index 000000000..3acddc3a0
--- /dev/null
+++ b/doc/texi/building/command.texi
@@ -0,0 +1,4 @@
+@macro COMMAND.checkout{}
+svn checkout @value{HB.repo.url} @value{HB.acro.lower}-@value{HB.repo.branch}
+cd @value{HB.acro.lower}-@value{HB.repo.branch}
+@end macro
diff --git a/doc/texi/building/method.checkout.texi b/doc/texi/building/method.checkout.texi
new file mode 100644
index 000000000..ca2352cec
--- /dev/null
+++ b/doc/texi/building/method.checkout.texi
@@ -0,0 +1,9 @@
+Checkout @value{HB.name} from the official source-code repository.
+
+@example
[email protected]{}
+@end example
+
+Sources are checked out from the @samp{@value{HB.repo.branch}} branch. This document was generated from that very branch, and for example purposes, we will use exactly the same branch.
+
+If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.5.0 or higher. Lower versions should also work.
diff --git a/doc/texi/build/platform.common.bundled.texi b/doc/texi/building/prerequisites.bundled.texi
index f5af0fcce..f5af0fcce 100644
--- a/doc/texi/build/platform.common.bundled.texi
+++ b/doc/texi/building/prerequisites.bundled.texi
diff --git a/doc/texi/building/prerequisites.common.texi b/doc/texi/building/prerequisites.common.texi
new file mode 100644
index 000000000..a3e368073
--- /dev/null
+++ b/doc/texi/building/prerequisites.common.texi
@@ -0,0 +1,12 @@
+The following general tools are used on various platforms and it is recommended you use these versions or similar:
+
+@itemize @bullet
+@item subversion - 1.5.5
+@item python - Python 2.4.6
+@item curl - curl 7.19.3 (or wget)
+@item m4 - GNU M4 1.4.6
+@item make - GNU Make 3.81
+@item patch - Patch 2.5.8
+@item tar - GNU tar 1.15.1
+@item wget - GNU Wget 1.11.4 (or curl)
+@end itemize
diff --git a/doc/xml2wiki.py b/doc/xml2wiki.py
new file mode 100755
index 000000000..96651c20f
--- /dev/null
+++ b/doc/xml2wiki.py
@@ -0,0 +1,395 @@
+import io
+import re
+import sys
+import time
+import xml.parsers.expat
+
+from optparse import OptionParser
+
+###############################################################################
+
+writer = None
+
+###############################################################################
+
+class StreamEntry:
+    def __init__( self, object, isElement ):
+        self.object    = object
+        self.isElement = isElement
+    
+###############################################################################
+
+class Element:
+    def __init__( self, parent, text=True, strip=True, delimBegin=None, delimEnd=None, newline=0 ):
+        self._parent     = parent
+        self._text       = text
+        self._strip      = strip
+        self._delimBegin = delimBegin
+        self._delimEnd   = delimEnd
+        self._newline    = newline
+        self._stream     = []
+
+    def _addElement( self, child ):
+        self._stream.append( StreamEntry( child, True ))
+
+    def _addText( self, text ):
+        if self._text:
+            self._stream.append( StreamEntry( text, False ))
+
+    def _write( self, file ):
+        if self._delimBegin:
+            file.write( self._delimBegin )
+        for entry in self._stream:
+            if entry.isElement:
+                entry.object.write( file )
+            else:
+                file.write( str(entry.object) )
+        if self._delimEnd:
+            file.write( self._delimEnd )
+
+    def write( self, file ):
+        if self._newline > writer.newlineCount:
+            file.write( '\n' * (self._newline - writer.newlineCount))
+        self._write( file )
+
+###############################################################################
+
+class Document( Element ):
+    def __init__( self ):
+        Element.__init__( self, None )
+        self._stack        = [ self ]
+        self._pending      = self
+        self._summary      = None
+        self._debugIndent  = ''
+        self._chapterLevel = 0
+        self._sectionLevel = 0
+        self._dividerCount = 0
+
+        #self._pragmaSummary = PragmaElement( self, 'summary' )
+        #self._pragmaLabels = PragmaElement( self, 'labels' )
+        #self._pragmaLabels._addText( 'xml2wiki,Distribution,Featured' )
+
+    def _pop( self ):
+        self._stack.pop()
+        self._pending = self._stack[-1]
+        return self._pending
+
+    def _pushChild( self, child, add=True ):
+        if add:
+            self._pending._addElement( child );
+        self._stack.append( child )
+        self._pending = child
+        return self._pending
+
+    def _chapterBegin( self ):
+        self._chapterLevel = self._chapterLevel + 1
+
+    def _chapterEnd( self ):
+        self._chapterLevel = self._chapterLevel - 1
+
+    def _sectionBegin( self ):
+        self._sectionLevel = self._sectionLevel + 1
+
+    def _sectionEnd( self ):
+        self._sectionLevel = self._sectionLevel - 1
+
+    def _write( self, file ):
+        #self._pragmaSummary.write( file )
+        #file.write( '\n' )
+        #self._pragmaLabels.write( file )
+        if options.date:
+            file.write( "\n\n  ===== `[`generated by xml2wiki on %s`]` =====" % (time.strftime( '%c' ) ))
+        #if options.toc:
+        #    file.write( '\n\n<wiki:toc max_depth="3" />' )
+        Element._write( self, file )
+        file.write( '\n' )
+
+    def handleElementBegin( self, name, attrs ):
+        self._debugIndent = '    ' * (len(self._stack) - 1)
+        if options.verbose:
+            print( '%sBEGIN %s %s' % (self._debugIndent, name, attrs))
+
+        e = None
+        shouldAdd = True
+
+        if name == 'anchor':
+            global anchor
+            anchor = attrs['name']
+        elif name == 'b':
+            e = Element( self._pending, delimBegin="'''", delimEnd="'''" )
+        elif name == 'chapter':
+            self._chapterBegin()
+        elif name == 'code':
+            e = Element( self._pending, delimBegin='{{{{', delimEnd='}}}' )
+        elif name == 'command':
+            e = Element( self._pending, delimBegin='{{{', delimEnd='}}}' )
+        elif name == 'enumerate':
+            e = EnumerateElement( self._pending )
+        elif name == 'example':
+            e = CodeElement( self._pending )
+        elif name == 'file':
+            e = Element( self._pending, delimBegin='{{{', delimEnd='}}}' )
+        elif name == 'i':
+            e = Element( self._pending, delimBegin="''", delimEnd="''" )
+        elif name == 'itemize':
+            e = ItemizeElement( self._pending )
+        elif name == 'item':
+            e = ItemElement( self._pending )
+        #elif name == 'majorheading':
+        #    e = self._pragmaSummary
+        #    shouldAdd = False
+        elif name == 'para':
+            e = ParagraphElement( self._pending )
+        elif name == 'quotation':
+            e = IndentedElement( self._pending )
+        elif name == 'samp':
+            e = Element( self._pending, delimBegin='{{{', delimEnd='}}}' )
+        elif name == 'section' or name == 'subsection':
+            self._sectionBegin()
+        #elif name == 'table':
+        #    e = Element( self._pending, newline=1, delimBegin='<table border="1" cellpadding="4">', delimEnd='</table>', strip=True )
+        elif name == 'tableitem':
+            e = TableItemElement( self._pending )
+        elif name == 'tableterm':
+            e = Element( self._pending, delimBegin=' ', delimEnd='::\n' )
+        elif name == 'title':
+            e = HeadingElement( self._pending, self._chapterLevel + self._sectionLevel )
+        elif name == 'unnumbered' or name == 'unnumberedsec':
+            self._chapterBegin()
+        elif name == 'uref':
+            e = UrefInline( self._pending )
+        elif name == 'urefdesc':
+            e = UrefDescInline( self._pending )
+        elif name == 'urefurl':
+            e = UrefUrlInline( self._pending )
+        elif name == 'xref':
+            e = XrefInline( self._pending )
+        elif name == 'xrefnodename':
+            e = XrefNodenameInline( self._pending )
+
+        if not e:
+            self._pushChild( UnknownElement( self._pending ) )
+            if options.verbose > 2:
+                print( 'UNKNOWN:', name )
+        else:
+            self._pushChild( e, add=shouldAdd )
+
+    def handleElementEnd( self, name ):
+        if name == 'chapter':
+            self._chapterEnd()
+        elif name == 'section' or name == 'subsection':
+            self._sectionEnd()
+        elif name == 'unnumbered' or name == 'unnumberedsec':
+            self._sectionEnd()
+
+        self._pop()
+        self._debugIndent = '    ' * (len(self._stack) - 1)
+        if options.verbose:
+            print( '%sEND %s' % (self._debugIndent, name))
+
+    def handleCharacterData( self, data ):
+        if options.verbose > 1:
+            print( '%s[%s]' % (self._debugIndent, data.strip()))
+        self._pending._addText( data )
+
+###############################################################################
+
+class UnknownElement( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, text=False )
+
+###############################################################################
+
+class PragmaElement( Element ):
+    def __init__( self, parent, keyword ):
+        Element.__init__( self, parent, delimBegin=('#' + keyword + ' ') )
+
+###############################################################################
+
+class BlockElement( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, newline=2, text=False )
+
+###############################################################################
+
+class CodeElement( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, newline=2, delimBegin='{{{\n', delimEnd='\n}}}\n' )
+
+###############################################################################
+
+class HeadingElement( Element ):
+    def __init__( self, parent, level ):
+        Element.__init__( self, parent, newline=2 )
+        global anchor
+        self._anchor = anchor
+
+        self._level = level
+        self._delimBegin = ('=' * level) + ' '
+        self._delimEnd   =  ' %s #%s\n' % (('=' * level), self._anchor)
+        #self._delimEnd   =  ' ' + ('=' * level) + ' #%s\n' % (self._anchor)
+
+        # insert divider for level 1 headers
+        if level == 1:
+            if options.toc or doc._dividerCount:
+                self._delimBegin = '----\n%s' % (self._delimBegin)
+            doc._dividerCount = doc._dividerCount + 1
+
+        toc.append( self )
+
+###############################################################################
+
+class IndentedElement( BlockElement ):
+    def _write( self, file ):
+        writer.increase()
+        Element._write( self, file )
+        writer.decrease()
+
+###############################################################################
+
+class EnumerateElement( IndentedElement ):
+    pass
+
+###############################################################################
+
+class ItemizeElement( IndentedElement ):
+    pass
+
+###############################################################################
+
+class ItemElement( BlockElement ):
+    def __init__( self, parent ):
+        BlockElement.__init__( self, parent )
+        self._newline = 1
+        if isinstance( parent, TableItemElement ):
+            self._newline    = 0
+            #self._delimBegin = '<td>'
+            #self._delimEnd   = '</td>'
+            self._delimBegin = '    '
+            self._delimEnd   = '\n'
+
+###############################################################################
+
+class ParagraphElement( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, newline=2 )
+        if isinstance( parent, ItemElement ):
+            if isinstance( parent._parent, TableItemElement ):
+                self._newline = 0
+            elif isinstance( parent._parent, EnumerateElement ):
+                self._newline    = 1
+                self._delimBegin = '# '
+            else:
+                self._newline    = 1
+                self._delimBegin = '* '
+
+###############################################################################
+
+class TableItemElement( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, newline=1, text=False )
+        #self._delimBegin = '<tr>'
+        #self._delimEnd   = '</tr>'
+
+###############################################################################
+
+class UrefInline( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, text=False, delimBegin='[', delimEnd=']' )
+
+###############################################################################
+
+class UrefDescInline( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, delimBegin=' ' )
+
+###############################################################################
+
+class UrefUrlInline( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent )
+
+###############################################################################
+
+class XrefInline( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent, text=False )
+
+###############################################################################
+
+class XrefNodenameInline( Element ):
+    def __init__( self, parent ):
+        Element.__init__( self, parent )
+
+    def _write( self, file ):
+        buffer = io.StringIO()
+        Element._write( self, buffer )
+        name = str( buffer.getvalue() )
+        anchor = re.sub( ' ', '_', name )
+        file.write( '[#%s %s]' % (anchor, name) )
+
+###############################################################################
+
+class IndentedWriter:
+    def __init__( self, size, file ):
+        self._chunk   = ' ' * size
+        self._file    = file
+        self._level   = 0
+        self._indent  = ''
+        self._pending = False
+
+        self.newlineCount = 0
+
+    def decrease( self ):
+        self._level  = self._level - 1
+        self._indent = self._chunk * self._level
+
+    def increase( self ):
+        self._level  = self._level + 1
+        self._indent = self._chunk * self._level
+
+    def write( self, data ):
+        for b in data:
+            if self._pending:
+                self._pending = False
+                self._file.write( self._indent )
+            if b == '\n':
+                self.newlineCount = self.newlineCount + 1
+                self._pending = True
+            else:
+                self.newlineCount = 0
+            self._file.write( b )
+
+###############################################################################
+
+parser = OptionParser( 'Usage: %prog [OPTIONS] xml' )
+parser.add_option( '-d', '--date', action='store_true', default=False, help='generate date-stamp under title' )
+parser.add_option( '-t', '--toc', action='store_true', default=False, help='generate table of contents' )
+parser.add_option( '-v', '--verbose', action='count', default=False, help='increase verbosity' )
+
+(options, args) = parser.parse_args()
+
+if( len(args) != 1 ):
+    parser.error( 'incorrect number of arguments' )
+
+###############################################################################
+
+doc = Document()
+xml = xml.parsers.expat.ParserCreate()
+
+xml.StartElementHandler  = doc.handleElementBegin
+xml.EndElementHandler    = doc.handleElementEnd
+xml.CharacterDataHandler = doc.handleCharacterData
+
+anchor = None
+toc = []
+with open( args[0], 'rb' ) as fin:
+    xml.ParseFile( fin )
+
+writer = IndentedWriter( 4, sys.stdout )
+
+if options.toc:
+    for e in toc:
+        writer.write( '%s* [#%s %s]\n' % ('  ' * e._level,e._anchor,e._stream[0].object) )
+
+doc.write( writer )