Update manpages using man brew

Properly update man pages using the local brew executable (from the repo),
and copy the man pages to the repo.

Library/Homebrew/cmd/install.rb

@@ -22,7 +22,10 @@
 #:    If `--cc=`<compiler> is passed, attempt to compile using <compiler>.
 #:    <compiler> should be the name of the compiler's executable, for instance
 #:    `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
-#:    4.9.
+#:    4.9. In order to use LLVM's clang, use `llvm_clang`. To specify the
+#:    Apple-provided clang, use `clang`. This parameter will only accept
+#:    compilers that are provided by Homebrew. Note that this will override
+#:    the value set by the `$HOMEBREW_CC` environment variable.
 #:
 #:    If `--build-from-source` (or `-s`) is passed, compile the specified <formula> from
 #:    source even if a bottle is provided. Dependencies will still be installed

Library/Homebrew/manpages/brew.1.md.erb

@@ -138,6 +138,15 @@ Note that environment variables must have a value set to be detected. For exampl
 
     *Default:* `~/Library/Caches/Homebrew`.
 
+  * `HOMEBREW_CC`:
+    If set, instructs Homebrew to used the specified compiler to build a
+    package from source. In order to specify the Apple-provided clang,
+    set `clang`. For the clang provided from the LLVM package, use 
+    `llvm_clang`. For versions of gcc, use the names of the executables from
+    the packages that Homebrew provides, e.g. for gcc 4.9, `gcc-4.9`, or for
+    gcc 8, `gcc-8`. Note that this variable can only be set to compilers that
+    are provided by Homebrew.
+
   * `HOMEBREW_CURLRC`:
     If set, Homebrew will not pass `-q` when invoking `curl`(1) (which disables
     the use of `curlrc`).

docs/Custom-GCC-and-cross-compilers.md

@@ -17,5 +17,6 @@ GCC or cross-compiler suite, please link it in here.
 * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
   C++11 support on earlier versions.
 * Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`.
+* Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
 * [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
   toolchain including binutils and GCC.

docs/Manpage.md

@@ -240,9 +240,10 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     If `--cc=``compiler` is passed, attempt to compile using `compiler`.
     `compiler` should be the name of the compiler's executable, for instance
     `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
-    4.9. In order to use the Homebrew-provided clang from the LLVM package,
+    4.9. In order to use LLVM's clang, use `llvm_clang`. To specify the
-    use `llvm_clang`. Note that this will override the `HOMEBREW_CC`
+    Apple-provided clang, use `clang`. This parameter will only accept
-    environment variable.
+    compilers that are provided by Homebrew. Note that this will override
+    the value set by the `$HOMEBREW_CC` environment variable.
 
     If `--build-from-source` (or `-s`) is passed, compile the specified `formula` from
     source even if a bottle is provided. Dependencies will still be installed
@@ -1125,13 +1126,13 @@ Note that environment variables must have a value set to be detected. For exampl
     *Default:* `~/Library/Caches/Homebrew`.
 
   * `HOMEBREW_CC`:
-    If set, directs which compiler Homebrew will use to compile packages if it
+    If set, instructs Homebrew to used the specified compiler to build a
-    builds them from source. If an installation command passes in a `--cc`
+    package from source. In order to specify the Apple-provided clang,
-    flag, it will override the value set by `HOMEBREW_CC`. The only valid
+    set `clang`. For the clang provided from the LLVM package, use 
-    compilers are ones provided by Homebrew, or Apple's bundled clang. To use
+    `llvm_clang`. For versions of gcc, use the names of the executables from
-    gcc for compilation, pass in the executable name, i.e. `gcc-4.9`, `gcc-8`.
+    the packages that Homebrew provides, e.g. for gcc 4.9, `gcc-4.9`, or for
-    If you want to use Apple's provided clang, simply use `clang`. For
+    gcc 8, `gcc-8`. Note that this variable can only be set to compilers that
-    Homebrew's clang from the LLVM package, use `llvm_clang`.
+    are provided by Homebrew.
 
   * `HOMEBREW_CURLRC`:
     If set, Homebrew will not pass `-q` when invoking `curl`(1) (which disables

manpages/brew.1

@@ -227,7 +227,7 @@ If \fB\-\-ignore\-dependencies\fR is passed, skip installing any dependencies of
 If \fB\-\-only\-dependencies\fR is passed, install the dependencies with specified options but do not install the specified formula\.
 .
 .IP
-If \fB\-\-cc=\fR\fIcompiler\fR is passed, attempt to compile using \fIcompiler\fR\. \fIcompiler\fR should be the name of the compiler\'s executable, for instance \fBgcc\-4\.2\fR for Apple\'s GCC 4\.2, or \fBgcc\-4\.9\fR for a Homebrew\-provided GCC 4\.9\.
+If \fB\-\-cc=\fR\fIcompiler\fR is passed, attempt to compile using \fIcompiler\fR\. \fIcompiler\fR should be the name of the compiler\'s executable, for instance \fBgcc\-4\.2\fR for Apple\'s GCC 4\.2, or \fBgcc\-4\.9\fR for a Homebrew\-provided GCC 4\.9\. In order to use LLVM\'s clang, use \fBllvm_clang\fR\. To specify the Apple\-provided clang, use \fBclang\fR\. This parameter will only accept compilers that are provided by Homebrew\. Note that this will override the value set by the \fB$HOMEBREW_CC\fR environment variable\.
 .
 .IP
 If \fB\-\-build\-from\-source\fR (or \fB\-s\fR) is passed, compile the specified \fIformula\fR from source even if a bottle is provided\. Dependencies will still be installed from bottles if they are available\.
@@ -1069,6 +1069,10 @@ If set, instructs Homebrew to use the given directory as the download cache\.
 \fIDefault:\fR \fB~/Library/Caches/Homebrew\fR\.
 .
 .TP
+\fBHOMEBREW_CC\fR
+If set, instructs Homebrew to used the specified compiler to build a package from source\. In order to specify the Apple\-provided clang, set \fBclang\fR\. For the clang provided from the LLVM package, use \fBllvm_clang\fR\. For versions of gcc, use the names of the executables from the packages that Homebrew provides, e\.g\. for gcc 4\.9, \fBgcc\-4\.9\fR, or for gcc 8, \fBgcc\-8\fR\. Note that this variable can only be set to compilers that are provided by Homebrew\.
+.
+.TP
 \fBHOMEBREW_CURLRC\fR
 If set, Homebrew will not pass \fB\-q\fR when invoking \fBcurl\fR(1) (which disables the use of \fBcurlrc\fR)\.
 .