3 files changed, 40 insertions, 5 deletions
diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi
index 00501c4c6..a554f7a0e 100644
--- a/doc/texi/Building.osx.texi
+++ b/doc/texi/Building.osx.texi
@@ -10,10 +10,6 @@
 
 @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
 
diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi
index 5f2135a61..88cb3b483 100644
--- a/doc/texi/building/chapter.via.terminal.texi
+++ b/doc/texi/building/chapter.via.terminal.texi
@@ -92,6 +92,10 @@ Alias for @samp{make build}.
 @item make build
 Build main product. All necessary dependencies are also built if required.
 
+@item make install
+Perform final product(s) install.
+This will install build products to a standard directory or one specified via @command{configure --prefix} option.
+
 @item make clean
 Clean all build output excluding contrib modules. Configuration is retained.
 
@@ -170,3 +174,16 @@ For convenience, the following targets aggregate the all contrib modules' respec
 @item make contrib.clean
 @item make contrib.xclean
 @end itemize
+
+@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/edit the optional include file @file{build/GNUmakefile.custom} which sits adjacent to the top-level makefile. @b{Do not check this file into the respository}. The sole purpose is to allow a place to store local build settings for testing, tweaking, and experimenting with build configuration without losing your settings if @command{configure} is invoked; ie: @command{configure} would overwrite @file{GNUmakefile} and any customizations contained therein would be lost. Here is a short example of what the contents of @file{build/GNUmakefile.custom} might contain:
+
+@example
+## bump to gcc-4.2 in current path
+GCC.gcc = gcc-4.2
+
+## replace optimize for 'speed' with more agressive 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 f01874522..9983c94f8 100644
--- a/doc/texi/building/chapter.via.xcode.texi
+++ b/doc/texi/building/chapter.via.xcode.texi
@@ -18,7 +18,7 @@ In Xcode perform the following steps to build the default configuration:
 @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.
+The first build (on an empty @file{build} directory) will take a bit of time. You may use the Build Results window to observe progress. The most time-consuming part of the build is when the external build system (essentially the @b{terminal} method) is triggered by Xcode and a substantial amount of log transcript ensues. Much of that transcript 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.
 
@@ -47,3 +47,25 @@ This configuration is used to build for the ppc architecture. Build directory is
 @item standard.ppc64
 This configuration is used to build for the ppc64 architecture. Build directory is @file{build.standard.ppc64} .
 @end table
+
+@c %**-------------------------------------------------------------------------
+@anchor{xcode.userdefined}
+@section User-Defined Settings
+The following user defined settings are used in Xcode project for the external build system:
+
+@table @samp
+@item EXTERNAL_BUILD
+Specifies the build location for each configuration.
+It is highly recommended the locations always evaluate to a unique pathname when factoring the configuration name.
+
+@item EXTERNAL_JOBS
+Specifies the concurrency factor for the external build system when builds are launched from within Xcode.
+This variable is meant to be customized by the developer for faster builds if the host supports it.
+
+@item EXTERNAL_METHOD
+This variable is used for internal/external build coordination and must always be @samp{xcode}.
+
+@item EXTERNAL_PROJECT
+Specifies the directory which is top of @value{HB.name} source tree.
+
+@end table