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

16 files changed, 725 insertions, 176 deletions

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 )