Further related to commands in Markdown

Author: mpilgrem

CONTRIBUTING.md

@@ -220,13 +220,17 @@ You can install HLint with Stack. You might want to install it in the global
 project in case you run into dependency conflicts. HLint can report hints in
 your favourite text editor. Refer to the HLint repository for more details.
 
-To install:
+To install, command:
 
-    stack install hlint
+~~~text
+stack install hlint
+~~~
 
-Once installed, you can check your changes with:
+Once installed, you can check your changes with command:
 
-    $ ./etc/scripts/hlint.sh
+~~~text
+stack exec -- sh ./etc/scripts/hlint.sh
+~~~
 
 ## Testing
 

doc/GUIDE.md

@@ -515,7 +515,8 @@ stack build
 We can also change resolvers on the command line, which can be useful in a
 Continuous Integration (CI) setting, like on Travis. For example, command:
 
-~~~textstack --resolver lts-18.28 build
+~~~text
+stack --resolver lts-18.28 build
 # Downloaded lts-18.28 build plan.
 # build output ...
 ~~~
@@ -822,23 +823,27 @@ much more composable command lines. For example, we can have a command that
 builds executables, generates Haddock documentation (Haskell API-level docs),
 and builds and runs your test suites, with:
 
-
-    $ stack build --haddock --test
+~~~text
+stack build --haddock --test
+~~~
 
 You can even get more inventive as you learn about other flags. For example,
-take the following:
+take the following command:
 
-    $ stack build --pedantic --haddock --test --exec "echo Yay, it succeeded" --file-watch
+~~~text
+stack build --pedantic --haddock --test --exec "echo Yay, it succeeded" --file-watch
+~~~
 
-This will:
+This command will:
 
-* turn on all warnings and errors
+* turn on all warnings and errors (the `--pendantic` flag)
 * build your library and executables
-* generate Haddocks
-* build and run your test suite
-* run the command `echo Yay, it succeeded` when that completes
+* generate Haddocks (the `--haddock` flag)
+* build and run your test suite (the `--test` flag)
+* run the command `echo Yay, it succeeded` when that completes (the `--exec`
+  option)
 * after building, watch for changes in the files used to build the project, and
-  kick off a new build when done
+  kick off a new build when done (the `--file-watch` flag)
 
 ### The `stack install` command and `copy-bins` option
 
@@ -849,15 +854,19 @@ precisely one thing in addition to the build command: it copies any generated
 executables to the local binary directory. You may recognize the default value
 for that path:
 
-On Unix-like operating systems:
+On Unix-like operating systems, command:
 
-    $ stack path --local-bin
-    /home/<user_name>/.local/bin
+~~~text
+stack path --local-bin
+/home/<user_name>/.local/bin
+~~~
 
-On Windows:
+On Windows, command:
 
-    $ stack path --local-bin
-    C:\Users\<user_name>\AppData\Roaming\local\bin
+~~~text
+stack path --local-bin
+C:\Users\<user_name>\AppData\Roaming\local\bin
+~~~
 
 That's why the download page recommends adding that directory to your PATH. This
 feature is convenient, because now you can simply run `executable-name` in your
@@ -877,10 +886,11 @@ Since it's such a point of confusion, let me list a number of things Stack does
 * Stack will not necessarily be creating a relocatable executable. If your
   executables hard-codes paths, copying the executable will not change those
   hard-coded paths.
-    * At the time of writing, there's no way to change those kinds of paths with
-      Stack, but see
-      [issue #848 about --prefix](https://github.com/commercialhaskell/stack/issues/848)
-      for future plans.
+
+  * At the time of writing, there's no way to change those kinds of paths with
+    Stack, but see
+    [issue #848 about --prefix](https://github.com/commercialhaskell/stack/issues/848)
+    for future plans.
 
 That's really all there is to the `install` command: for the simplicity of what
 it does, it occupies a much larger mental space than is warranted.

doc/GUIDE_advanced.md

@@ -269,49 +269,61 @@ resulting package archive, to test it.
 Stack provides multiple templates to start a new project from. 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...
+~~~text
+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:
+from a different Github user by prefixing the username and a slash. Command:
 
-    $ stack new my-yesod-project yesodweb/simple
+~~~text
+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:
+[GitLab](https://gitlab.com) or [Bitbucket](https://bitbucket.com). For example,
+command:
 
-    $ stack new my-project gitlab:user29/foo
+~~~text
+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:
+If you need more flexibility, you can specify the full URL of the template.
+Command:
 
-    $ stack new my-project https://my-site.com/content/template9.hsfiles
+~~~text
+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:
+Alternatively you can use a local template by specifying the path. Command:
 
-    $ stack new project <path_to_template>/template.hsfiles
+~~~text
+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).

doc/install_and_upgrade.md

@@ -319,44 +319,44 @@ wget -qO- https://get.haskellstack.org/ | sh
     <!-- * [Linux AArch64](https://get.haskellstack.org/stable/linux-aarch64.tar.gz) -->
 
 * Extract the archive and place `stack` somewhere on your PATH (see the
-  [Path](#path) section below)
+  [Path](#path) section below).
 
 * Ensure you have required system dependencies installed. These include GCC, GNU
   Make, xz, perl, libgmp, libffi, and zlib. We also recommend Git and GPG. To
   install these using your package manager:
 
-    * Debian / Ubuntu, command:
+  * Debian / Ubuntu, command:
 
-      ~~~text
-      sudo apt-get install g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg netbase
-      ~~~
+        ~~~text
+        sudo apt-get install g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg netbase
+        ~~~
 
-    * Fedora / CentOS, command:
+  * Fedora / CentOS, command:
 
-      ~~~text
-      sudo dnf install perl make automake gcc gmp-devel libffi zlib zlib-devel xz tar git gnupg
-      ~~~
+        ~~~text
+        sudo dnf install perl make automake gcc gmp-devel libffi zlib zlib-devel xz tar git gnupg
+        ~~~
 
-      (use `yum` instead of `dnf` on CentOS and Fedora <= 21)
+    (use `yum` instead of `dnf` on CentOS and Fedora <= 21)
 
-        * Fedora 24: In order to use `stack setup` on a 32-bit system, you may
-          need to run `sudo dnf install ncurses-compat-libs`. If this package is
-          not installed, Stack may not be able to install 32-bit GHC versions.
+    * Fedora 24: In order to use `stack setup` on a 32-bit system, you may
+      need to run `sudo dnf install ncurses-compat-libs`. If this package is
+      not installed, Stack may not be able to install 32-bit GHC versions.
 
-    * Arch Linux, command:
+  * Arch Linux, command:
 
-      ~~~text
-      sudo pacman -S make gcc ncurses git gnupg xz zlib gmp libffi zlib
-      ~~~
+        ~~~text
+        sudo pacman -S make gcc ncurses git gnupg xz zlib gmp libffi zlib
+        ~~~
 
-        * In order to use `stack setup` with older versions of GHC or on a
-          32-bit system, you may need the
-          [ncurses5-compat-libs](https://aur.archlinux.org/packages/ncurses5-compat-libs/)
-          AUR package installed. If this package is not installed, Stack may not
-          be able to install older (< 7.10.3) or 32-bit GHC versions.
+    * In order to use `stack setup` with older versions of GHC or on a
+      32-bit system, you may need the
+      [ncurses5-compat-libs](https://aur.archlinux.org/packages/ncurses5-compat-libs/)
+      AUR package installed. If this package is not installed, Stack may
+      not be able to install older (< 7.10.3) or 32-bit GHC versions.
 
-    * Gentoo users, make sure to have the `ncurses` package with `USE=tinfo`
-      (without it, Stack will not be able to install GHC).
+    * Gentoo users, make sure to have the `ncurses` package with
+      `USE=tinfo` (without it, Stack will not be able to install GHC).
 
 * Now you can run Stack from the command line in a terminal.
 
@@ -390,26 +390,32 @@ Run:
 
 You can install Stack by copying the executable file anywhere on your PATH. A
 good place to install is the same directory where Stack itself will install
-executables. On Windows, that directory is `%APPDATA%\local\bin`, e.g. `c:\Users\<user-name>\AppData\Roaming\local\bin`. For other systems, it's
-`$HOME/.local/bin`.
+executables. On Unix-like operating systems, that directory is:
+
+~~~text
+$HOME/.local/bin
+~~~
 
-If you don't have that directory in your PATH, you may need to update your PATH
-(such as, on Unix-like operating systems, by editing `~/.bashrc`).
+On Windows, that directory is:
+
+~~~text
+%APPDATA%\local\bin
+~~~
+
+For example: `C:\Users\<user-name>\AppData\Roaming\local\bin`.
+
+If you don't have that directory in your PATH, you may need to update your PATH.
+On Unix-like operating systems, that can be done by editing the `~/.bashrc`
+file.
 
 If you're curious about the choice of these directories, see
 [issue #153](https://github.com/commercialhaskell/stack/issues/153)
 
 ## Shell auto-completion
 
-To get tab-completion of commands on bash, just run the following (or add it to
-`.bashrc`):
-
-~~~text
-eval "$(stack --bash-completion-script stack)"
-~~~
-
-For more information and other shells, see the
-[shell auto-completion](shell_autocompletion.md) page.
+On Unix-like operating systems, it is possible to set up auto-completion of
+Stack commands. For further information, see the
+[shell auto-completion](shell_autocompletion.md) documentation.
 
 ## China-based users