BuildSystem: docs (OSX)

- updated Xcode.app build instructions to make sure custom shell environment/PATH propagates to Xcode.
- various spelling corrections.


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

6 files changed, 92 insertions, 70 deletions

diff --git a/doc/BUILD-Cygwin b/doc/BUILD-Cygwin
index 5bda0ae13..48ac13568 100644
--- a/doc/BUILD-Cygwin
+++ b/doc/BUILD-Cygwin
@@ -1,4 +1,4 @@
-Guide to Building HandBrake svn2252 (2009031001) on Cygwin
+Guide to Building HandBrake svn2322 (2009041301) on Cygwin
 **********************************************************
 
 Table of Contents
@@ -146,10 +146,10 @@ Configure the build system.
 
 Configure will automatically create a scratch build directory `build'
 unless you use GNU-style build procedures and first `cd' to a directory
-other than top-level source. Additionally you may specify use `--build'
-to specify the directory. The name of the directory is arbitrary but it
-is recommended to use something which indicates transient files which
-are not checked into the repository.
+other than top-level source. Additionally you may use `--build' to
+specify the directory. The name of the directory is arbitrary but it is
+recommended to use something which indicates transient files which are
+not checked into the repository.
 
 The `configure' utility accepts many options. It is recommended that
 you specify `--help' for the complete list of options. The following
@@ -172,12 +172,13 @@ options are also documented here:
 
 `--launch'
      All-in-one option which launches the build and logs output
-     automatically.  Useful for novices and quickstart procedures.
+     automatically.  Useful for novices and quick-start procedures.
 
 `--disable-xcode'
-     Disable shunting the build through Xcode. If this option is
-     applied, `HandBrakeCLI' will be produced in a similare fashion as
-     it is on other platforms; sans Xcode. Mac OS X only.
+     Disable shunting the build through `xcodebuild'. If this option is
+     applied, `HandBrakeCLI' will be produced in a similar fashion as
+     it is on other platforms; sans Xcode and the Cocoa application
+     will not be produced. Mac OS X only.
 
 `--disable-gtk'
      Disable building the GTK GUI on applicable platforms such as
@@ -213,7 +214,7 @@ some of the reasons why someone may choose to scrap an existing build:
    * 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
+directory can be recursively 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
@@ -242,7 +243,7 @@ log. The following command allows for up to 4 concurrent jobs via make:
 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
+one-word targets. Scoped targets are usually two-words separated by a
 period.
 
 5.4.1 Global
@@ -306,7 +307,7 @@ Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 
 `make MODULE.fetch'
      Download source tarball from the Internet and save to
-     `TOP/downloads' directory. No checksumming is performed.
+     `TOP/downloads' directory. No check-summing is performed.
 
 `make MODULE.extract'
      Extract source tarball into `build' tree.
@@ -396,7 +397,7 @@ If the need arises to override settings in the build system
 (essentially gnu-make variables) the recommended method is to create
 optional include files which are automatically included if present and
 follow this naming convention; Do not check these files into the
-respository:
+repository:
 
 `_SRC_/custom.defs'
      Custom makevar definitions outside `build'. Suitable for settings
@@ -425,7 +426,7 @@ be lost. Here is a short example of what the contents of
      ## bump to gcc-4.2 in current path
      GCC.gcc = gcc-4.2
 
-     ## replace optimize for 'speed' with more agressive settings
+     ## replace optimize for 'speed' with more aggressive settings
      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 
 See also `make report.help' which displays a set of reports used to
@@ -438,7 +439,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2252
-     date:   2009-03-10 18:43:11 -0400
+     rev:    2322
+     date:   2009-04-13 13:28:21 -0400
      type:   developer
 
diff --git a/doc/BUILD-Linux b/doc/BUILD-Linux
index a6c3fb0cd..3c5182cf9 100644
--- a/doc/BUILD-Linux
+++ b/doc/BUILD-Linux
@@ -1,4 +1,4 @@
-Guide to Building HandBrake svn2252 (2009031001) on Linux
+Guide to Building HandBrake svn2322 (2009041301) on Linux
 *********************************************************
 
 Table of Contents
@@ -102,6 +102,8 @@ Ubuntu 8.10 packages:
 
    * libgtkhtml3.14-dev (gui)
 
+   * libnotify-dev (gui)
+
    * libgstreamer0.10-dev (gui)
 
    * libgstreamer-plugins-base0.10-dev (gui)
@@ -110,7 +112,8 @@ To install these packages:
      sudo apt-get install subversion yasm 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
+     libgtkhtml3.14-dev libnotify-dev libgstreamer0.10-dev \
+     libgstreamer-plugins-base0.10-dev
 
 Fedora 10 package groups:
    * Development Tools
@@ -136,13 +139,15 @@ Additional Fedora 10 packages:
 
    * gtkhtml3-devel (gui)
 
+   * libnotify-devel (gui)
+
    * gstreamer-devel (gui)
 
    * gstreamer-plugins-base-devel (gui)
 
 To install these packages:
      sudo yum install yasm zlib-devel bzip2-devel \
-     dbus-glib-devel hal-devel gtkhtml3-devel \
+     dbus-glib-devel hal-devel gtkhtml3-devel libnotify-devel\
      gstreamer-devel gstreamer-plugins-base-devel
 
 3 QuickStart
@@ -212,10 +217,10 @@ Configure the build system.
 
 Configure will automatically create a scratch build directory `build'
 unless you use GNU-style build procedures and first `cd' to a directory
-other than top-level source. Additionally you may specify use `--build'
-to specify the directory. The name of the directory is arbitrary but it
-is recommended to use something which indicates transient files which
-are not checked into the repository.
+other than top-level source. Additionally you may use `--build' to
+specify the directory. The name of the directory is arbitrary but it is
+recommended to use something which indicates transient files which are
+not checked into the repository.
 
 The `configure' utility accepts many options. It is recommended that
 you specify `--help' for the complete list of options. The following
@@ -238,12 +243,13 @@ options are also documented here:
 
 `--launch'
      All-in-one option which launches the build and logs output
-     automatically.  Useful for novices and quickstart procedures.
+     automatically.  Useful for novices and quick-start procedures.
 
 `--disable-xcode'
-     Disable shunting the build through Xcode. If this option is
-     applied, `HandBrakeCLI' will be produced in a similare fashion as
-     it is on other platforms; sans Xcode. Mac OS X only.
+     Disable shunting the build through `xcodebuild'. If this option is
+     applied, `HandBrakeCLI' will be produced in a similar fashion as
+     it is on other platforms; sans Xcode and the Cocoa application
+     will not be produced. Mac OS X only.
 
 `--disable-gtk'
      Disable building the GTK GUI on applicable platforms such as
@@ -279,7 +285,7 @@ some of the reasons why someone may choose to scrap an existing build:
    * 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
+directory can be recursively 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
@@ -308,7 +314,7 @@ log. The following command allows for up to 4 concurrent jobs via make:
 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
+one-word targets. Scoped targets are usually two-words separated by a
 period.
 
 5.4.1 Global
@@ -372,7 +378,7 @@ Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 
 `make MODULE.fetch'
      Download source tarball from the Internet and save to
-     `TOP/downloads' directory. No checksumming is performed.
+     `TOP/downloads' directory. No check-summing is performed.
 
 `make MODULE.extract'
      Extract source tarball into `build' tree.
@@ -462,7 +468,7 @@ If the need arises to override settings in the build system
 (essentially gnu-make variables) the recommended method is to create
 optional include files which are automatically included if present and
 follow this naming convention; Do not check these files into the
-respository:
+repository:
 
 `_SRC_/custom.defs'
      Custom makevar definitions outside `build'. Suitable for settings
@@ -491,7 +497,7 @@ be lost. Here is a short example of what the contents of
      ## bump to gcc-4.2 in current path
      GCC.gcc = gcc-4.2
 
-     ## replace optimize for 'speed' with more agressive settings
+     ## replace optimize for 'speed' with more aggressive settings
      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 
 See also `make report.help' which displays a set of reports used to
@@ -504,7 +510,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2252
-     date:   2009-03-10 18:43:11 -0400
+     rev:    2322
+     date:   2009-04-13 13:28:21 -0400
      type:   developer
 
diff --git a/doc/BUILD-Mac b/doc/BUILD-Mac
index 6dc74692d..dae650a92 100644
--- a/doc/BUILD-Mac
+++ b/doc/BUILD-Mac
@@ -1,4 +1,4 @@
-Build Guide for HandBrake svn2252 on Mac OS X
+Build Guide for HandBrake svn2322 on Mac OS X
 *********************************************
 
 Table of Contents
@@ -20,7 +20,7 @@ Table of Contents
     5.4.5 Contrib Aggregates
   5.5 Customizing Make
   5.6 Universal Binaries
-6 Building via Xcode
+6 Building via Xcode.app
   6.1 Checkout Sources
   6.2 Build
   6.3 External Targets
@@ -115,11 +115,13 @@ following steps:
 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
+The two general methods to build on Mac OS X are from terminal or
+Xcode.app. 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.
+individual. To be extra clear, building from the terminal by default
+actually invokes `xcodebuild' to build the very same targets contained
+in the Xcode project. Think of it as building with Xcode but without
+the GUI.
 
 5 Building via Terminal
 ***********************
@@ -149,10 +151,10 @@ Configure the build system.
 
 Configure will automatically create a scratch build directory `build'
 unless you use GNU-style build procedures and first `cd' to a directory
-other than top-level source. Additionally you may specify use `--build'
-to specify the directory. The name of the directory is arbitrary but it
-is recommended to use something which indicates transient files which
-are not checked into the repository.
+other than top-level source. Additionally you may use `--build' to
+specify the directory. The name of the directory is arbitrary but it is
+recommended to use something which indicates transient files which are
+not checked into the repository.
 
 The `configure' utility accepts many options. It is recommended that
 you specify `--help' for the complete list of options. The following
@@ -175,12 +177,13 @@ options are also documented here:
 
 `--launch'
      All-in-one option which launches the build and logs output
-     automatically.  Useful for novices and quickstart procedures.
+     automatically.  Useful for novices and quick-start procedures.
 
 `--disable-xcode'
-     Disable shunting the build through Xcode. If this option is
-     applied, `HandBrakeCLI' will be produced in a similare fashion as
-     it is on other platforms; sans Xcode. Mac OS X only.
+     Disable shunting the build through `xcodebuild'. If this option is
+     applied, `HandBrakeCLI' will be produced in a similar fashion as
+     it is on other platforms; sans Xcode and the Cocoa application
+     will not be produced. Mac OS X only.
 
 `--disable-gtk'
      Disable building the GTK GUI on applicable platforms such as
@@ -216,7 +219,7 @@ some of the reasons why someone may choose to scrap an existing build:
    * 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
+directory can be recursively 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
@@ -245,7 +248,7 @@ log. The following command allows for up to 4 concurrent jobs via make:
 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
+one-word targets. Scoped targets are usually two-words separated by a
 period.
 
 5.4.1 Global
@@ -309,7 +312,7 @@ Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 
 `make MODULE.fetch'
      Download source tarball from the Internet and save to
-     `TOP/downloads' directory. No checksumming is performed.
+     `TOP/downloads' directory. No check-summing is performed.
 
 `make MODULE.extract'
      Extract source tarball into `build' tree.
@@ -399,7 +402,7 @@ If the need arises to override settings in the build system
 (essentially gnu-make variables) the recommended method is to create
 optional include files which are automatically included if present and
 follow this naming convention; Do not check these files into the
-respository:
+repository:
 
 `_SRC_/custom.defs'
      Custom makevar definitions outside `build'. Suitable for settings
@@ -428,7 +431,7 @@ be lost. Here is a short example of what the contents of
      ## bump to gcc-4.2 in current path
      GCC.gcc = gcc-4.2
 
-     ## replace optimize for 'speed' with more agressive settings
+     ## replace optimize for 'speed' with more aggressive settings
      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 
 See also `make report.help' which displays a set of reports used to
@@ -461,8 +464,8 @@ and `x86_64' before invoking `make':
      ## prefer i386 (order is important)
      UB.archs = i386 x86_64
 
-6 Building via Xcode
-********************
+6 Building via Xcode.app
+************************
 
 6.1 Checkout Sources
 ====================
@@ -483,9 +486,16 @@ 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 Xcode.app from a terminal by using the `open' command which passes
+your shell environment and its `PATH' setting to Xcode. Do not attempt
+to launch Xcode.app from Finder or by using Finder to open
+`HandBrake.xcodeproj' - doing so will defeat any custom path settings
+which contain required tools.
 
-   * open `macosx/HandBrake.xcodeproj'
+     open `macosx/HandBrake.xcodeproj'
+
+Once the HandBrake Xcode project is open, perform the following steps
+to build the default configuration:
 
    * select active configuration standard
 
@@ -617,7 +627,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2252
-     date:   2009-03-10 18:43:11 -0400
+     rev:    2322
+     date:   2009-04-13 13:28:21 -0400
      type:   developer
 
diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi
index 768488152..5ab1ff1ce 100644
--- a/doc/texi/Building.osx.texi
+++ b/doc/texi/Building.osx.texi
@@ -35,7 +35,7 @@ Building on @value{OS.osx} is well supported. It is the reference platform for @
 @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.
+The two general methods to build on @value{OS.osx} are from @b{terminal} or @b{Xcode.app}. The preferred method for automated and repeatable builds is to use the terminal. Otherwise the choice is generally up to the individual. To be extra clear, building from the terminal by default actually invokes @command{xcodebuild} to build the very same targets contained in the Xcode project. Think of it as building with Xcode but without the GUI.
 
 @c %**-------------------------------------------------------------------------
 @include building/chapter.via.terminal.texi
diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi
index 5b6e2cd65..ba437a7ac 100644
--- a/doc/texi/building/chapter.via.terminal.texi
+++ b/doc/texi/building/chapter.via.terminal.texi
@@ -35,10 +35,10 @@ This defaults to a reasonable platform-specific value.
 
 @item --launch
 All-in-one option which launches the build and logs output automatically.
-Useful for novices and quickstart procedures.
+Useful for novices and quick-start procedures.
 
 @item --disable-xcode
-Disable shunting the build through Xcode. If this option is applied, @command{HandBrakeCLI} will be produced in a similare fashion as it is on other platforms; sans Xcode. @value{OS.osx} only.
+Disable shunting the build through @command{xcodebuild}. If this option is applied, @command{HandBrakeCLI} will be produced in a similar fashion as it is on other platforms; sans Xcode and the Cocoa application will not be produced. @value{OS.osx} only.
 
 @item --disable-gtk
 Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
@@ -64,7 +64,7 @@ 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 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.
+There are generally two methods for scrapping a build. The @file{build} directory can be recursively 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.
 
 @c %**-------------------------------------------------------------------------
 @anchor{terminal.build}
@@ -85,7 +85,7 @@ make -j4
 @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.
+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 separated by a period.
 
 @anchor{terminal.targets.global}
 @subsection Global
@@ -144,7 +144,7 @@ Contrib modules such as @samp{a52dec}, @samp{bzip2}, @samp{faac}, @samp{faad2},
 
 @table @samp
 @item make @i{MODULE}.fetch
-Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
+Download source tarball from the Internet and save to @file{TOP/downloads} directory. No check-summing is performed.
 
 @item make @i{MODULE}.extract
 Extract source tarball into @file{build} tree.
@@ -212,7 +212,7 @@ For convenience, the following targets aggregate the all contrib modules' respec
 @c %**-------------------------------------------------------------------------
 @anchor{terminal.customizing}
 @section Customizing Make
-If the need arises to override settings in the build system (essentially gnu-make variables) the recommended method is to create optional include files which are automatically included if present and follow this naming convention; @b{Do not check these files into the respository}:
+If the need arises to override settings in the build system (essentially gnu-make variables) the recommended method is to create optional include files which are automatically included if present and follow this naming convention; @b{Do not check these files into the repository}:
 
 @table @file
 @item _SRC_/custom.defs
@@ -235,7 +235,7 @@ The purpose is to allow a place to store local build settings for testing, tweak
 ## bump to gcc-4.2 in current path
 GCC.gcc = gcc-4.2
 
-## replace optimize for 'speed' with more agressive settings
+## replace optimize for 'speed' with more aggressive settings
 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 @end example
 
diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi
index 7a2aab9ed..2b79a7bfc 100644
--- a/doc/texi/building/chapter.via.xcode.texi
+++ b/doc/texi/building/chapter.via.xcode.texi
@@ -1,5 +1,5 @@
 @anchor{xcode}
-@chapter Building via Xcode
+@chapter Building via Xcode.app
 
 @c %**-------------------------------------------------------------------------
 @anchor{xcode.checkout}
@@ -9,10 +9,15 @@
 @c %**-------------------------------------------------------------------------
 @anchor{xcode.build}
 @section Build
-In Xcode perform the following steps to build the default configuration:
+Open Xcode.app from a terminal by using the @command{open} command which passes your shell environment and its @samp{PATH} setting to Xcode. Do not attempt to launch Xcode.app from Finder or by using Finder to open @file{HandBrake.xcodeproj} -- doing so will defeat any custom path settings which contain required tools.
+
+@example
+open @file{macosx/HandBrake.xcodeproj}
+@end example
+
+Once the HandBrake Xcode project is open, 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}