rework description of source maps and move to section about bundle

diff --git a/README.adoc b/README.adoc
index 3d5c39e..ec64d04 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -17,7 +17,7 @@
 :url-nodejs: https://nodejs.org
 :url-nvm: https://github.com/creationix/nvm
 :url-nvm-install: {url-nvm}#installation
-:url-sourcemap-information: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
+:url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
 
 image:{img-ci-status}[CI Status (GitLab CI), link={url-ci-pipelines}]
 
@@ -167,17 +167,6 @@ This works by monitoring the project for changes, running the `preview:build` ta
 
 Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
-==== Source Maps
-
-In preview mode, {url-sourcemap-information}[source maps] are enabled. 
-This means that although Javascript and CSS files are combined into a single file (`site.js` or `site.css`) an additional `map` file is provided to allow a reference to the source.
-This is especially useful for debugging.
-
-This is mainly intended for preview and debugging not for production. 
-If you need this capability in production it can be achieved through an environment variable when bundling the UI:
-
- $ SOURCEMAPS=true gulp build
-
 === Package for Use with Antora
 
 If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
@@ -195,6 +184,22 @@ If you have the preview running, and you want to bundle without causing the prev
 
 The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
 
+==== Source Maps
+
+The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
+{url-source-maps}[Source maps] correlate these combined files with their original sources.
+
+This "`source mapping`" is accomplished by generating additional map files that make this association.
+These map files sit adjacent to the combined files in the build folder.
+The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging.
+
+In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them.
+If you need to include source maps in the bundle, you can do so by setting the `SOURCEMAPS` environment varible to `true` when you run the bundle command:
+
+ $ SOURCEMAPS=true gulp bundle
+
+In this case, the bundle will include the source maps, which can be used for debuggging your production site.
+
 == Copyright and License
 
 Copyright (C) 2017-2019 OpenDevise Inc. and the Antora Project.