From 3ce9de767214d0ff8998d576bfc7f0301e284e3a Mon Sep 17 00:00:00 2001
From: "Mark D. Blackwell" <markdblackwell01@gmail.com>
Date: Tue, 9 Aug 2016 19:14:40 -0400
Subject: [PATCH] docs: Follow through on watch default

---
 docs/content/extras/livereload.md             | 38 ++++++++++++-------
 docs/content/overview/usage.md                |  6 +--
 .../content/tutorials/creating-a-new-theme.md | 22 +++++++++--
 3 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/docs/content/extras/livereload.md b/docs/content/extras/livereload.md
index 602b9124c..a69e7af92 100644
--- a/docs/content/extras/livereload.md
+++ b/docs/content/extras/livereload.md
@@ -1,5 +1,5 @@
 ---
-lastmod: 2015-04-01
+lastmod: 2016-08-09
 date: 2014-05-26
 menu:
   main:
@@ -23,7 +23,8 @@ Hugo comes with LiveReload built in. There are no additional packages to
 install. A common way to use Hugo while developing a site is to have
 Hugo run a server and watch for changes:
 
-    $ hugo server --watch
+{{< nohighlight >}}$ hugo server
+{{< /nohighlight >}}
 
 This will run a full functioning web server while simultaneously
 watching your file system for additions, deletions or changes within
@@ -34,32 +35,41 @@ your:
  * data files
  * layouts
  * current theme
+ * configuration files
 
-Whenever anything changes Hugo will rebuild the site, continue to serve
-the content and as soon as the build is finished it will tell the
-browser and silently reload the page. Because most hugo builds are so
+Whenever anything changes, Hugo will rebuild the site while continuing to serve
+the content. As soon as the build is finished, it will tell the
+browser and silently reload the page. Because most Hugo builds are so
 fast they are barely noticeable, you merely need to glance at your open
-browser and you will see the change already there.
+browser and you will see the change, already there.
 
 This means that keeping the site open on a second monitor (or another
 half of your current monitor) allows you to see exactly what your
-content looks like without even leaving your text editor.
+content looks like, without even leaving your text editor.
+
+## Disabling Watch
+
+If for some reason you don't want the Hugo server's watch functionality,
+just do:
+
+{{< nohighlight >}}$ hugo server --watch=false
+{{< /nohighlight >}}
 
 ## Disabling LiveReload
 
-LiveReload works by injecting JavaScript into the pages it
-creates that creates a web socket client to the hugo web socket server.
+LiveReload works by injecting JavaScript into the pages Hugo generates,
+which creates a connection from the browser web socket client to the
+Hugo web socket server.
 
 Awesome for development, but not something you would want to do in
-production. Since many people use `hugo server --watch` in production to
+production. Since many people use `hugo server` in production to
 instantly display any updated content, we’ve made it easy to disable the
-LiveReload functionality.
+LiveReload functionality:
 
-    $ hugo server --watch --disableLiveReload
+{{< nohighlight >}}$ hugo server --disableLiveReload
+{{< /nohighlight >}}
 
 ## Notes
 
-The `--watch` flag is enabled by default when `hugo server` is run.
-
 You must have a closing `</body>` tag for LiveReload to work.
 Hugo injects the LiveReload `<script>` before this tag.
diff --git a/docs/content/overview/usage.md b/docs/content/overview/usage.md
index 3fd74db55..feb1b0f76 100644
--- a/docs/content/overview/usage.md
+++ b/docs/content/overview/usage.md
@@ -1,7 +1,7 @@
 ---
 aliases:
 - /doc/usage/
-lastmod: 2015-12-23
+lastmod: 2016-08-09
 date: 2013-07-01
 menu:
   main:
@@ -13,7 +13,7 @@ title: Using Hugo
 weight: 30
 ---
 
-Make sure either `hugo` is in your `PATH` or provide a path to it.
+Make sure Hugo is in your `PATH` (or provide a path to it). Test it with:
 
 {{< nohighlight >}}$ hugo help
 
@@ -88,7 +88,7 @@ ready to be deployed to your web server.
 
 ## Instant feedback as you develop your web site
 
-If you are working on things and want to see the changes immediately, tell Hugo to watch for changes.
+If you are working on things and want to see the changes immediately, by default
 Hugo will watch the filesystem for changes, and rebuild your site as soon as a file is saved:
 
 {{< nohighlight >}}$ hugo -s ~/Code/hugo/docs
diff --git a/docs/content/tutorials/creating-a-new-theme.md b/docs/content/tutorials/creating-a-new-theme.md
index cf38dffc3..af74b8186 100644
--- a/docs/content/tutorials/creating-a-new-theme.md
+++ b/docs/content/tutorials/creating-a-new-theme.md
@@ -1,6 +1,6 @@
 ---
 author: "Michael Henderson"
-lastmod: 2015-12-01
+lastmod: 2016-08-10
 date: 2015-11-26
 linktitle: Creating a New Theme
 toc: true
@@ -416,9 +416,25 @@ When rendering the site, Hugo will create new files and update existing ones in
 
 As of version 0.15, Hugo doesn't write files when running in server mode. Instead, it keeps all the rendered files in memory. You can "clean" up files by stopping and restarting the server.
 
-### Hugo's Watch Option
+### Watching with Hugo
 
-Hugo's "`--watch`" option will monitor the content/ and your theme directories for changes and rebuild the site automatically. Since version 0.15, this has been the default option for `hugo server`.
+Hugo's watch functionality monitors the relevant site and theme directories
+for file changes,
+and rebuilds the site automatically when changes are detected.
+
+By default, watching is
+enabled when in web server mode (`hugo server`),
+but disabled for the web site generator (`hugo`).
+
+In some use cases,
+Hugo's web site generator should watch&mdash;simply
+type `hugo --watch` on the command line.
+
+Sometimes with Docker containers (and Heroku slugs),
+the site sources may live on a read-only filesystem.
+In that scenario, it makes no sense
+for Hugo's web server to watch for file changes&mdash;so
+use `hugo server --watch=false`.
 
 ### Live Reload