1 files changed, 102 insertions, 7 deletions
diff --git a/docs/UsersManual.html b/docs/UsersManual.html
index 65415eea48d5..20fdda72dced 100644
--- a/docs/UsersManual.html
+++ b/docs/UsersManual.html
@@ -33,6 +33,12 @@ td {
 <li><a href="#general_features">Language and Target-Independent Features</a>
  <ul>
   <li><a href="#diagnostics">Controlling Errors and Warnings</a></li>
+   <ul>
+   <li><a href="#diagnostics_display">Controlling How Clang Displays Diagnostics</a></li>
+   <li><a href="#diagnostics_mappings">Diagnostic Mappings</a></li>
+   <li><a href="#diagnostics_commandline">Controlling Diagnostics via Command Line Flags</a></li>
+   <li><a href="#diagnostics_pragmas">Controlling Diagnostics via Pragmas</a></li>
+   </ul>
   <li><a href="#precompiledheaders">Precompiled Headers</a></li>
   </ul>
 </li>
@@ -362,7 +368,7 @@ by commenting them out.</p>
 <p>Clang provides a number of ways to control which code constructs cause it to
 emit errors and warning messages, and how they are displayed to the console.</p>
 
-<h4>Controlling How Clang Displays Diagnostics</h4>
+<h4 id="diagnostics_display">Controlling How Clang Displays Diagnostics</h4>
 
 <p>When Clang emits a diagnostic, it includes rich information in the output,
 and gives you fine-grain control over which information is printed.  Clang has
@@ -394,18 +400,64 @@ it:</p>
 <p>For more information please see <a href="#cl_diag_formatting">Formatting of
 Diagnostics</a>.</p>
 
-<h4>Controlling Which Diagnostics Clang Generates</h4>
+<h4 id="diagnostics_mappings">Diagnostic Mappings</h4>
 
-<p>mappings: ignore, note, warning, error, fatal</p>
+<p>All diagnostics are mapped into one of these 5 classes:</p>
 
 <p>
-The two major classes are control from the command line and control via pragmas
-in your code.</p>
+<ul>
+<li>Ignored</li>
+<li>Note</li>
+<li>Warning</li>
+<li>Error</li>
+<li>Fatal</li>
+</ul></p>
 
+<h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line Flags</h4>
 
 <p>-W flags, -pedantic, etc</p>
 
-<p>pragma GCC diagnostic</p>
+<h4 id="diagnostics_pragmas">Controlling Diagnostics via Pragmas</h4>
+
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific warnings
+in a section of source code. Clang supports GCC's pragma for compatibility
+with existing source code, as well as several extensions. </p>
+
+<p>The pragma may control any warning that can be used from the command line.
+Warnings may be set to ignored, warning, error, or fatal. The following 
+example code will tell Clang or GCC to ignore the -Wall warnings:</p>
+
+<pre>
+#pragma GCC diagnostic ignored "-Wall"
+</pre>
+
+<p>In addition to all of the functionality of provided by GCC's pragma, Clang 
+also allows you to push and pop the current warning state.  This is particularly
+useful when writing a header file that will be compiled by other people, because 
+you don't know what warning flags they build with.</p>
+
+<p>In the below example
+-Wmultichar is ignored for only a single line of code, after which the
+diagnostics return to whatever state had previously existed.</p>
+
+<pre>
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmultichar"
+
+char b = 'df'; // no warning.
+
+#pragma clang diagnostic pop
+</pre>
+
+<p>The push and pop pragmas will save and restore the full diagnostic state of
+the compiler, regardless of how it was set. That means that it is possible to
+use push and pop around GCC compatible diagnostics and Clang will push and pop
+them appropriately, while GCC will ignore the pushes and pops as unknown 
+pragmas. It should be noted that while Clang supports the GCC pragma, Clang and
+GCC do not support the exact same set of warnings, so even when using GCC
+compatible #pragmas there is no guarantee that they will have identical behaviour
+on both compilers. </p>
 
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
 <h3 id="precompiledheaders">Precompiled Headers</h3>
@@ -465,6 +517,50 @@ for headers that are directly included within a source file. For example:</p>
 <tt>test.h</tt> since <tt>test.h</tt> was included directly in the source file
 and not specified on the command line using <tt>-include</tt>.</p>
 
+<h4>Relocatable PCH Files</h4>
+<p>It is sometimes necessary to build a precompiled header from headers that
+are not yet in their final, installed locations. For example, one might build a
+precompiled header within the build tree that is then meant to be installed
+alongside the headers. Clang permits the creation of "relocatable" precompiled
+headers, which are built with a given path (into the build directory) and can 
+later be used from an installed location.</p>
+
+<p>To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example, if you
+want to build a precompiled header for the header <code>mylib.h</code> that
+will be installed into <code>/usr/include</code>, create a subdirectory 
+<code>build/usr/include</code> and place the header <code>mylib.h</code> into
+that subdirectory. If <code>mylib.h</code> depends on other headers, then 
+they can be stored within <code>build/usr/include</code> in a way that mimics
+the installed location.</p>
+
+<p>Building a relocatable precompiled header requires two additional arguments.
+First, pass the <code>--relocatable-pch</code> flag to indicate that the
+resulting PCH file should be relocatable. Second, pass 
+<code>-isysroot /path/to/build</code>, which makes all includes for your
+library relative to the build directory. For example:</p>
+
+<pre>
+  # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+</pre>
+
+<p>When loading the relocatable PCH file, the various headers used in the PCH
+file are found from the system header root. For example, <code>mylib.h</code>
+can be found in <code>/usr/include/mylib.h</code>. If the headers are installed
+in some other system root, the <code>-isysroot</code> option can be used provide
+a different system root from which the headers will be based. For example,
+<code>-isysroot /Developer/SDKs/MacOSX10.4u.sdk</code> will look for 
+<code>mylib.h</code> in 
+<code>/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</code>.</p>
+
+<p>Relocatable precompiled headers are intended to be used in a limited number
+of cases where the compilation environment is tightly controlled and the
+precompiled header cannot be generated after headers have been installed. 
+Relocatable precompiled headers also have some performance impact, because
+the difference in location between the header locations at PCH build time vs. 
+at the time of PCH use requires one of the PCH optimizations,
+<code>stat()</code> caching, to be disabled. However, this change is only 
+likely to affect PCH files that reference a large number of headers.</p>
 
 <!-- ======================================================================= -->
 <h2 id="c">C Language Features</h2>
@@ -500,7 +596,6 @@ variants "__asm__" and "__typeof__" are recognized in all modes.</li>
 <li>The Apple "blocks" extension is recognized by default in gnu* modes
 on some platforms; it can be enabled in any mode with the "-fblocks"
 option.</li>
-<li>Some warnings are different.</li>
 </ul>
 
 <p>Differences between *89 and *99 modes:</p>