doco: more updates for core/formula separation

Closes #71.

Signed-off-by: Andrew Janke <andrew@apjanke.net>

share/doc/homebrew/FAQ.md

@@ -176,7 +176,7 @@ If it’s not in `man brew`, it’s probably an external command. These are docu
 If it’s been a while, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. Maybe we were thinking on something. It will encourage consideration. In the meantime if you could rebase the pull request so that it can be cherry-picked more easily we will love you for a long time.
 
 ### Can I edit formulae myself?
-Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to*Homebrew/homebrew-core*, just edit the formula as you personally need it and `brew install`. As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications!
+Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to *Homebrew/homebrew-core*, just edit the formula as you personally need it and `brew install`. As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications!
 
 ### Can I make new formulae?
 Yes! It’s easy! Just `brew create URL` Homebrew will then open the

share/doc/homebrew/Formula-Cookbook.md

 # Formula Cookbook
-A formula is a package definition written in Ruby. It can be created with `brew create $URL` and installed with `brew install $FORMULA` and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers.
+A formula is a package definition written in Ruby. It can be created with `brew create $URL`, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers.
 
 ## Homebrew Terminology
 
@@ -29,7 +29,7 @@ Before submitting a new formula make sure your package:
 *   meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements
 *   isn't already in Homebrew (check `brew search $FORMULA`)
 *   isn't in another official [Homebrew tap](https://github.com/Homebrew)
-*   isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues))
+*   isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/pulls))
 *   is still supported by upstream (i.e. doesn't require extensive patching)
 *   has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Branches](Interesting-Taps-&-Branches.md) for where pre-release versions belong.
 *   passes all `brew audit --strict --online $FORMULA` tests.
@@ -109,7 +109,7 @@ Homebrew’s OpenSSL is
 to avoid conflicting with the system so sometimes formulae need to
 have environment variables set or special configuration flags passed
 to locate our OpenSSL. You can see this mechanism in the
-[clamav](https://github.com/Homebrew/homebrew-core/blob/master/Formula/clamav.rb#L28)
+[clamav](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/clamav.rb#L38)
 formula. Usually this is unnecessary because when OpenSSL is specified
 as a dependency Homebrew temporarily prepends the `$PATH` with that
 prefix.
@@ -170,7 +170,7 @@ Sometimes there’s hard conflict between formulae, and it can’t be avoided or
 
 `mbedtls` is a good [example](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mbedtls.rb) formula for minor conflict.
 
-`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just remove it.
+`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just [remove it](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/mbedtls.rb#L27-L28) during the installation process.
 
 [pdftohtml](https://github.com/Homebrew/homebrew-core/blob/master/Formula/pdftohtml.rb) provides an example of a serious
 conflict, where both formula ship an identically-named binary that is essential to functionality, so a [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#conflicts_with-class_method) is preferable.
@@ -332,12 +332,12 @@ Ensure you reference any relevant GitHub issue e.g. `Closes #12345` in the commi
 
 Now you just need to push your commit to GitHub.
 
-If you haven’t forked Homebrew yet, [go to the repo and hit the fork button](https://github.com/Homebrew/homebrew).
+If you haven’t forked Homebrew yet, [go to the `homebrew-core` repository and hit the fork button](https://github.com/Homebrew/homebrew-core).
 
-If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the Homebrew/homebrew master):
+If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the `Homebrew/homebrew-core` master):
 
 ```shell
-git push https://github.com/myname/homebrew/ <what-you-called-your-branch>
+git push https://github.com/myname/homebrew-core/ <what-you-called-your-branch>
 ```
 
 Now, please [open a pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes.
@@ -481,7 +481,7 @@ Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formu
 
 # Advanced Formula Tricks
 
-If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repo homebrew/core` directory. Please submit a pull request to amend this document if you think it will help!
+If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repo homebrew/core)` directory. Please submit a pull request to amend this document if you think it will help!
 
 ## Unstable versions (`devel`, `head`)
 

share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md

 # How To Open a Homebrew Pull Request (and get it merged)
+
 The following commands are used by Homebrew's contributors to setup a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request of the changes in that branch.
 
 Depending on the change you want to make, you need to send the pull request to the corresponding repository. If you want to submit a change in Homebrew core code, you should open the pull request at [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you could open the pull request at [Homebrew core tap](https://github.com/Homebrew/homebrew-core) or any other [official taps](https://github.com/Homebrew) based the formula type.
@@ -17,6 +18,8 @@ Depending on the change you want to make, you need to send the pull request to t
 2. [Fork the Homebrew/homebrew-core repository](https://github.com/Homebrew/homebrew-core/fork) on GitHub. This creates a pushable, personal remote repository. This is needed as only Homebrew maintainers have push access to the main repository.
 3. Add the pushable forked repository with `git remote add YOUR_USERNAME https://github.com/YOUR_USERNAME/homebrew-core.git`
 
+## Create your Pull Request from a new branch
+
 To make a new branch and submit it for review:
 
 1. Checkout the `master` branch with `git checkout master`
@@ -27,6 +30,8 @@ To make a new branch and submit it for review:
 6. Upload your new commits to the branch to your fork with `git push --set-upstream YOUR_USERNAME YOUR_BRANCH_NAME`
 7. Go to https://github.com/Homebrew/homebrew-core and create a pull request to request review and merge of commits in your pushed branch. Make sure you explain why the change is needed and, if fixing a bug, how to reproduce the bug. Please note that the preferred commit message format for simple version updates is "FORMULA_NAME NEW_VERSION", e.g. "`source-highlight 3.1.8`". `devel` version bumps should have the commit message marked with addtional `(devel)` suffix like "`nginx 1.9.1 (devel)`". Await feedback or a merge from Homebrew's maintainers.
 
+## Following up
+
 To respond well to feedback:
 
 1. Ask for clarification of anything you don't understand and help with anything you don't know how to do.

share/doc/homebrew/Interesting-Taps-&-Branches.md

 # Interesting Taps & Branches
 A Tap is homebrew-speak for a git repository containing extra formulae.
-Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` command. Type `man brew` in your Terminal. The main repository https://github.com/Homebrew/homebrew-core often called "Homebrew/core" is always built-in.
+Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` command. Type `man brew` in your Terminal. The main repository https://github.com/Homebrew/homebrew-core, often called `homebrew/core`, is always built-in.
 
 ## Main Taps
 
@@ -36,7 +36,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
 
 *   [homebrew/x11](https://github.com/Homebrew/homebrew-x11): Formulae with hard X11 dependencies.
 
-`brew search` looks in these main taps and as well in [Homebrew/homebrew](https://github.com/Homebrew/homebrew). So don't worry about missing stuff. We will add other taps to the search as they become well maintained and popular.
+`brew search` looks in these main taps as well as in [homebrew/core](https://github.com/Homebrew/homebrew-core). So don't worry about missing stuff. We will add other taps to the search as they become well maintained and popular.
 
 You can be added as a maintainer for one of the Homebrew organization taps and aid the project! If you are interested write to our list: homebrew-discuss@googlegroups.com. We want your help!
 

share/doc/homebrew/Rename-A-Formula.md

@@ -5,7 +5,7 @@ you need to:
 
 1. Rename the formula file and its class to a new formula. The new name must meet all the usual rules of formula naming. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formulae (i.e. `brew audit --strict` must pass for that formula).
 
-2. Create a pull request to the corresponding tap deleting the old formula file, adding the new formula file and add it to `formula_renames.json` with a commit message like `newack: renamed from ack`. Use canonical name (e.g. `ack` instead of `user/repo/ack`).
+2. Create a pull request to the corresponding tap deleting the old formula file, adding the new formula file, and adding it to `formula_renames.json` with a commit message like `newack: renamed from ack`. Use the canonical name (e.g. `ack` instead of `user/repo/ack`).
 
 
 A `formula_renames.json` example for a formula rename:

share/doc/homebrew/brew-tap.md

@@ -54,10 +54,10 @@ edavis/emacs
 
 ## Formula duplicate names
 
-If your tap contains a formula that is also present in master, that's fine,
+If your tap contains a formula that is also present in [`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine,
 but it means that you must install it explicitly by default.
 
-If you would like to prioritize a tap over master, you can use
+If you would like to prioritize a tap over `homebrew/core`, you can use
 `brew tap-pin username/repo` to pin the tap,
 and use `brew tap-unpin username/repo` to revert the pin.