Improve the mac guide (#322)

* fix typo in setup_mac_build_environment.md

* improve setup_mac_build_environment.md

1 files changed, 74 insertions, 26 deletions

diff --git a/contrib/setup_mac_build_environment.md b/contrib/setup_mac_build_environment.md
index 0257176..d17ed2b 100644
--- a/contrib/setup_mac_build_environment.md
+++ b/contrib/setup_mac_build_environment.md
@@ -1,42 +1,90 @@
 # How to setup Browsh's build system for Mac
+If you just want to try Browsh, you can use [Homebrew](https://brew.sh/) (check out the [installation page](https://www.brow.sh/docs/installation/) at the [official site](https://www.brow.sh/)).
 
-## Install Go
-Follow the [install guide](https://golang.org/doc/install). Note that there is an installer for Mac.
+## Installations
+You need Go, Firefox and Node.js to run Browsh.
 
-### Ensure your GOPATH is set
-Open your terminal of choice. Run `echo $GOPATH`.
-You should see something like `/usr/local/go`. Inside this folder, there will be a src folder. If there isn't one created yet, run `mkdir $GOPATH/src`.
+### Install Go
+Follow the [installation guide](https://golang.org/doc/install) (you can use an installer).
 
-## Clone Browsh
-Fork Browsh to your Github account. Clone this fork of Browsh to your $GOPATH/src folder you just created.
+#### Ensure your GOPATH is set
 
-## Install Firefox
-Follow Firefox's [guide](https://support.mozilla.org/en-US/kb/how-download-and-install-firefox-mac) to installing Firefox on Mac.
+```sh
+$ echo $GOPATH
+/Users/uesr_name/go
+$ # anywhere is ok, but make sure it's not none
+```
 
-### Add the Firefox app to your PATH
-Browsh needs to be able to create new instances of Firefox. Add the Firefox app to your path. It's probably something like `/Applications/Firefox.app/Contents/MacOS`.
-To add this to your path, edit your path file by running `sudo nano /etc/paths`. Add the path to Firefox in here and save the file.
+#### Ensure you have `$GOPATH/src` and `$GOPATH/bin` folders
+If you're not sure if you have these folders, run:
 
-## Install Node
-[Install Node](https://nodejs.org/en/download/). The currently recommended version of Node for working with Browsh is v8.11.4.
+```sh
+$ mkdir "$GOPATH/src"
+$ mkdir "$GOPATH/bin"
+```
+
+### Install Firefox
+Follow the official [guide](https://support.mozilla.org/en-US/kb/how-download-and-install-firefox-mac) to install Firefox.
+
+#### Include Firefox to your PATH
+The `firefox` executable is probably at `/Applications/Firefox.app/Contents/MacOS`. You need to add it to your `PATH` so that Browsh can create new instances of Firefox.
+
+### Install Node.js
+Follow the [official downloading page](https://nodejs.org/en/download/).
+
+> v8.11.4. is currently recommended for working with Browsh (?)
+
+#### Install web-ext globally
+It's a Mozilla's handy tool for working with Firefox web extensions:
+
+```sh
+$ npm install -g web-ext
+```
+
+## Setting up your Browsh
+
+### Clone Browsh
+Fork Browsh to your Github account. Clone it to `$GOPATH/src`.
 
 ### Install NPM packages
-Navigate to browsh/webext. Run `npm install`.
 
-### Install web-ext globally
-Run `npm install -g web-ext`. This is Mozilla's handy tool for working with Firefox web extensions.
+```shell
+$ cd "$GOPATH/src/browsh/webext"
+$ npm install
+```
+
+### Run the build script
 
-## Run the build script
-Navigate to the root of your Browsh project. This should be `$GOROOT/src/browsh`. Run `./interfacer/contrib/build_browsh.sh`. This will install several required packages.
+```sh
+$ cd "$GOPATH/src/browsh"
+$ # install several required package"
+$ ./interfacer/contrib/build_browsh.sh
+```
 
 ## Running Browsh from source
-Now that you have all of the required dependencies installed, we can run Browsh. First, open 3 terminals.
+Now that you have all of the required dependencies installed, we can run Browsh. Open three terminals and do the follows:
+
+### Terminal 1 (builds JavaScript)
+
+```sh
+$ cd "$GOPATH/src/browsh/webext"
+$ # create a dist folder inside the webext folder.
+$ npx webpack --watch
+```
+
+### Terminal 2 (handles Firefox web extension)
+
+```sh
+$ # the dist folder is created in the first terminal
+$ cd "$GOPATH/browsh/webext/dist"
+$ # create a dist folder inside the webext folder.
+$ npx webpack --watch
+```
 
-### Terminal 1
-This terminal will build the Javascript. From the `browsh/webext` folder, run `npx webpack --watch`. This will create a dist folder inside the webext folder.
+### Terminal 3 (Displays Browsh)
 
-### Terminal 2
-This terminal will handle the Firefox web extension. From the `browsh/webext/dist` folder, run `web-ext run --verbose`.
+```sh
+$ cd "$GOPATH/browsh"
+$ go run ./interfacer/src/main.go --firefox.use-existing --debug
+```
 
-### Terminal 3
-This terminal will display Browsh. From the project root, run `go run ./interfacer/src/main.go --firefox.use-existing --debug`.