Restructure the Guide between introductory and GUIDE_advanced

Other than typographical corrections, this commit does not change any existing content. All it seeks to do is to separate the existing monolithic Guide web page into the introductory material (consistent with the existing introduction to the Guide) from the more advanced material (characterised in the Guide as 'fun features' or 'power user' commands).

The intent is that this will provide a better foundation for more comprehensive online guidance for the more advanced features.

Author: mpilgrem

doc/GUIDE.md

@@ -1,13 +1,16 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# User guide
+# User guide (introductory)
 
 Stack is a modern, cross-platform build tool for Haskell code.
 
-This guide takes a new Stack user through the typical workflows. This guide will
-not teach Haskell or involve much code, and it requires no prior experience with
-the Haskell packaging system or other build tools. Terms used in the guide are
-defined in the [glossary](glossary.md).
+This introductory guide takes a new Stack user through the typical workflows.
+This guide will not teach Haskell or involve much code, and it requires no prior
+experience with the Haskell packaging system or other build tools. Terms used in
+the guide are defined in the [glossary](glossary.md).
+
+Some of Stack's features will not be needed regularly or by all users. See the
+[advanced user's guide](GUIDE_advanced.md) for information about those features.
 
 ## Stack's functions
 
@@ -79,7 +82,9 @@ package name first:
 
 We'll call our project `helloworld`, and we'll use the `new-template` project
 template. This template is used by default, but in our example we will refer to
-it expressly. From the root directory for all our Haskell projects, we command:
+it expressly. Other templates are available, see the `stack templates` command.
+
+From the root directory for all our Haskell projects, we command:
 
     $ stack new helloworld new-template
 
@@ -1581,250 +1586,6 @@ __Other tools for comparison (including active and historical)__
   constraints and snapshots, it did not work as well as hoped. It is deprecated
   in favor of Stack.
 
-## Fun features
-
-This is just a quick collection of fun and useful feature Stack supports.
-
-### Templates
-
-We started off using the `new` command to create a project. Stack provides
-multiple templates to start a new project from. For more information, command:
-
-    $ stack templates
-
-You can specify one of these templates following your project name
-in the `stack new` command:
-
-    $ stack new my-rio-project rio
-    Downloading template "rio" to create project "my-rio-project" in my-rio-project/ ...
-    Looking for .cabal or package.yaml files to use to init the project.
-    Using cabal packages:
-    - my-rio-project/
-
-    Selecting the best among 18 snapshots...
-
-    * Matches ...
-
-    Selected resolver: ...
-    Initialising configuration using resolver: ...
-    Total number of user packages considered: 1
-    Writing configuration to file: my-rio-project/stack.yaml
-    All done.
-    <Stack root>\templates\rio.hsfiles:   10.10 KiB downloaded...
-
-The default templates repository is
-https://github.com/commercialhaskell/stack-templates. You can download templates
-from a different Github user by prefixing the username and a slash:
-
-    $ stack new my-yesod-project yesodweb/simple
-
-Then template file `simple.hsfiles` would be downloaded from GitHub repository
-`yesodweb/stack-templates`.
-
-You can even download templates from a service other that GitHub, such as
-[GitLab](https://gitlab.com) or [Bitbucket](https://bitbucket.com). For example:
-
-    $ stack new my-project gitlab:user29/foo
-
-Template file `foo.hsfiles` would be downloaded from GitLab, user account
-`user29`, repository `stack-templates`.
-
-If you need more flexibility, you can specify the full URL of the template:
-
-    $ stack new my-project https://my-site.com/content/template9.hsfiles
-
-(The `.hsfiles` extension is optional; it will be added if it's not specified.)
-
-Alternatively you can use a local template by specifying the path:
-
-    $ stack new project <path_to_template>/template.hsfiles
-
-As a starting point for creating your own templates, you can use the
-["simple" template](https://github.com/commercialhaskell/stack-templates/blob/master/simple.hsfiles).
-The
-[stack-templates repository](https://github.com/commercialhaskell/stack-templates#readme)
-provides an introduction into creating templates.
-
-### Editor integration
-
-For editor integration, Stack has a related project called
-[intero](https://github.com/commercialhaskell/intero). It is particularly well
-supported by Emacs, but some other editors have integration for it as well.
-
-### Visualizing dependencies
-
-If you'd like to get some insight into the dependency tree of your packages, you
-can use the `stack dot` command and Graphviz. More information is available in
-the [Dependency visualization documentation](dependency_visualization.md).
-
-### Travis with caching
-
-This content has been moved to a dedicated
-[Travis CI document](https://docs.haskellstack.org/en/stable/travis_ci/).
-
-### Shell auto-completion
-
-Love tab-completion of commands? You're not alone. If you're on bash, just run
-the following (or add it to `.bashrc`):
-
-    eval "$(stack --bash-completion-script stack)"
-
-For more information and other shells, see the
-[Shell auto-completion wiki page](https://docs.haskellstack.org/en/stable/shell_autocompletion)
-
-### Docker
-
-Stack is able to build your code inside a Docker image, which means even more
-reproducibility to your builds, since you and the rest of your team will always
-have the same system libraries.
-
-### Nix
-
-Stack provides an integration with [Nix](http://nixos.org/nix), providing you
-with the same two benefits as the first Docker integration discussed above:
-
-* more reproducible builds, since fixed versions of any system libraries and
-  commands required to build the project are automatically built using Nix and
-  managed locally per-project. These system packages never conflict with any
-  existing versions of these libraries on your system. That they are managed
-  locally to the project means that you don't need to alter your system in any
-  way to build any odd project pulled from the Internet.
-* implicit sharing of system packages between projects, so you don't have more
-  copies on-disk than you need to.
-
-When using the Nix integration, Stack downloads and builds Haskell dependencies
-as usual, but resorts on Nix to provide non-Haskell dependencies that exist in
-the Nixpkgs.
-
-Both Docker and Nix are methods to *isolate* builds and thereby make them more
-reproducible. They just differ in the means of achieving this isolation. Nix
-provides slightly weaker isolation guarantees than Docker, but is more
-lightweight and more portable (Linux and macOS mainly, but also Windows). For
-more on Nix, its command-line interface and its package description language,
-read the [Nix manual](http://nixos.org/nix/manual). But keep in mind that the
-point of Stack's support is to obviate the need to write any Nix code in the
-common case or even to learn how to use the Nix tools (they're called under the
-hood).
-
-For more information, see
-[the Nix-integration documentation](nix_integration.md).
-
-## Power user commands
-
-The following commands are a little more powerful, and won't be needed by all
-users. Here's a quick rundown:
-
-* `stack update` will download the most recent set of packages from your package
-  indices (e.g. Hackage). Generally, Stack runs this for you automatically
-  when necessary, but it can be useful to do this manually sometimes.
-* `stack unpack` is a command we've already used quite a bit for examples, but
-  most users won't use it regularly. It does what you'd expect: downloads a
-  tarball and unpacks it. It accept optional `--to` argument to specify
-  the destination directory.
-* `stack sdist` generates an uploading tarball containing your package code
-* `stack upload` uploads an sdist to Hackage. As of version
-  [1.1.0](https://docs.haskellstack.org/en/v1.1.0/ChangeLog/) Stack will also
-  attempt to GPG sign your packages as per
-  [our blog post](https://www.fpcomplete.com/blog/2016/05/stack-security-gnupg-keys).
-    * `--no-signature` disables signing of packages
-    * `--candidate` upload a
-      [package candidate](http://hackage.haskell.org/upload#candidates)
-    * Hackage API key can be used instead of username and password. Usage
-      example:
-
-    ```bash
-    HACKAGE_KEY=<api_key> stack upload .
-    ```
-
-    * `username` and `password` can be read by environment
-
-    ```bash
-    export $HACKAGE_USERNAME="<username>"
-    export $HACKAGE_PASSWORD="<password>"
-    ```
-
-* `stack upgrade` will build a new version of Stack from source.
-    * `--git` is a convenient way to get the most recent version from the
-      `master` branch, for those testing and living on the bleeding edge.
-* `stack ls snapshots` will list all the local snapshots by default. You can
-  also view the remote snapshots using `stack ls snapshots remote`. It also
-  supports option for viewing only lts (`-l`) and nightly (`-n`) snapshots.
-* `stack ls dependencies` lists all of the packages and versions used for a
-  project
-* `stack list [PACKAGE]...` list the version of the specified package(s) in a
-  snapshot, or without an argument list all the snapshot's package versions.
-  If no resolver is specified the latest package version from Hackage is given.
-* `stack sig` subcommand can help you with GPG signing & verification
-    * `sign` will sign an sdist tarball and submit the signature to
-      sig.commercialhaskell.org for storage in the sig-archive git repo.
-      (Signatures will be used later to verify package integrity.)
-
-## Debugging
-
-To profile a component of the current project, simply pass the `--profile`
-flag to `stack`. The `--profile` flag turns on the `--enable-library-profiling`
-and `--enable-executable-profiling` Cabal options _and_ passes the `+RTS -p`
-runtime options to any testsuites and benchmarks.
-
-For example the following command will build the `my-tests` testsuite with
-profiling options and create a `my-tests.prof` file in the current directory
-as a result of the test run.
-
-    $ stack test --profile my-tests
-
-The `my-tests.prof` file now contains time and allocation info for the test run.
-
-To create a profiling report for an executable, e.g. `my-exe`, you can run
-
-     $ stack exec --profile -- my-exe +RTS -p
-
-For more fine-grained control of compilation options there are the
-`--library-profiling` and `--executable-profiling` flags which will turn on the
-`--enable-library-profiling` and `--enable-executable-profiling` Cabal
-options respectively. Custom GHC options can be passed in with
-`--ghc-options "more options here"`.
-
-To enable compilation with profiling options by default you can add the
-following snippet to your `stack.yaml` or `~/.stack/config.yaml`:
-
-```yaml
-build:
-  library-profiling: true
-  executable-profiling: true
-```
-
-### Further reading
-
-For more commands and uses, see the
-[official GHC chapter on profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html),
-the [Haskell wiki](https://wiki.haskell.org/How_to_profile_a_Haskell_program),
-and the
-[chapter on profiling in Real World Haskell](http://book.realworldhaskell.org/read/profiling-and-optimization.html).
-
-### Tracing
-
-To generate a backtrace in case of exceptions during a test or benchmarks run,
-use the `--trace` flag. Like `--profile` this compiles with profiling options,
-but adds the `+RTS -xc` runtime option.
-
-### Debugging symbols
-
-Building with debugging symbols in the
-[DWARF information](https://ghc.haskell.org/trac/ghc/wiki/DWARF) is supported by
-Stack. This can be done by passing the flag `--ghc-options="-g"` and also to
-override the default behaviour of stripping executables of debugging symbols by
-passing either one of the following flags: `--no-strip`,
-`--no-library-stripping` or `--no-executable-stripping`.
-
-In Windows, GDB can be installed to debug an executable with
-`stack exec -- pacman -S gdb`. Windows' Visual Studio compiler's debugging
-format PDB is not supported at the moment. This might be possible by
-[separating](https://stackoverflow.com/questions/866721/how-to-generate-gcc-debug-symbol-outside-the-build-target)
-debugging symbols and
-[converting](https://github.com/rainers/cv2pdb) their format. Or as an option
-when
-[using the LLVM backend](http://blog.llvm.org/2017/08/llvm-on-windows-now-supports-pdb-debug.html).
-
 ## More resources
 
 There are lots of resources available for learning more about Stack: