add note about spack help --spec (#440)

* add note about spack help --spec

* fix .. note::

* indent doesn't need to be so large

* fix the help text output

* break up sentences

Author: cmelone

outputs/basics/help-spec.out

@@ -0,0 +1,60 @@
+spec expression syntax:
+
+  package [constraints] [^dependency [constraints] ...]
+
+  package                           any package from 'spack list', or
+  /hash                             unique prefix or full hash of
+                                    installed package
+
+  constraints:
+    versions:
+      @version                      single version
+      @min:max                      version range (inclusive)
+      @min:                         version <min> or higher
+      @:max                         up to version <max> (inclusive)
+      @=version                     exact version
+
+    compilers:
+      %compiler                     build with <compiler>
+      %compiler@version             build with specific compiler version
+      %compiler@min:max             specific version range (see above)
+
+    compiler flags:
+      cflags="flags"                cppflags, cflags, cxxflags,
+                                    fflags, ldflags, ldlibs
+      ==                            propagate flags to package dependencies
+
+    variants:
+      +variant                      enable <variant>
+      -variant or ~variant          disable <variant>
+      variant=value                 set non-boolean <variant> to <value>
+      variant=value1,value2,value3  set multi-value <variant> values
+      ++, --, ~~, ==                propagate variants to package dependencies
+
+    architecture variants:
+      platform=platform             linux, darwin, freebsd, windows
+      os=operating_system           specific <operating_system>
+      target=target                 specific <target> processor
+      arch=platform-os-target       shortcut for all three above
+
+    dependencies:
+      ^dependency [constraints]     specify constraints on dependencies
+      ^/hash                        build with a specific installed
+                                    dependency
+
+  examples:
+      hdf5                          any hdf5 configuration
+      hdf5 @1.10.1                  hdf5 version 1.10.1
+      hdf5 @1.8:                    hdf5 1.8 or higher
+      hdf5 @1.8: %gcc               hdf5 1.8 or higher built with gcc
+      hdf5 +mpi                     hdf5 with mpi enabled
+      hdf5 ~mpi                     hdf5 with mpi disabled
+      hdf5 ++mpi                    hdf5 with mpi enabled and propagates
+      hdf5 ~~mpi                    hdf5 with mpi disabled and propagates
+      hdf5 +mpi ^mpich              hdf5 with mpi, using mpich
+      hdf5 +mpi ^openmpi@1.7        hdf5 with mpi, using openmpi 1.7
+      boxlib dim=2                  boxlib built for 2 dimensions
+      libdwarf %intel ^libelf%gcc
+          libdwarf, built with intel compiler, linked to libelf built with gcc
+      mvapich2 fabrics=psm,mrail,sock %gcc
+          mvapich2, built with gcc compiler, with support for multiple fabrics

tutorial_basics.rst

@@ -341,3 +341,12 @@ We can also remove compilers from our configuration using ``spack compiler remov
 
 .. literalinclude:: outputs/basics/compiler-remove.out
    :language: console
+
+.. note::
+
+   The spec syntax may be confusing for new users.
+   Spack can provide information about commands you run frequently.
+   For instance, see the output of ``spack help --spec``:
+
+   .. literalinclude:: outputs/basics/help-spec.out
+      :language: console

tutorial_binary_cache.rst

@@ -59,10 +59,10 @@ The build cache name, `buildcache-${USER}-${HOSTNAME}`, is a suggestion; you can
        oci://ghcr.io/<your-github-username-or-org>/buildcache-${USER}-${HOSTNAME}
 
 
-.. note ::
+.. note::
 
-We talk about mirrors and build caches almost interchangeably, because every build cache is a binary mirror.
-Source mirrors exist too, which we will not cover in this tutorial.
+   We talk about mirrors and build caches almost interchangeably, because every build cache is a binary mirror.
+   Source mirrors exist too, which we will not cover in this tutorial.
 
 
 Your ``spack.yaml`` file should now contain the following:
@@ -110,15 +110,15 @@ The location of the pushed package, when referred to as an OCI image, will be:
 
 look very similar to a container image --- we will get to that in a bit.
 
-.. note ::
+.. note::
 
-Binaries pushed to GitHub packages are ``private`` by default, which means you need a token to download them.
-You can change the visibility to ``public`` by going to GitHub Packages from your GitHub account, selecting the ``buildcache`` package, go to ``package settings``, and change the visibility to ``public`` in the ``Danger Zone`` section.
-This page can also be directly accessed by going to
+   Binaries pushed to GitHub packages are ``private`` by default, which means you need a token to download them.
+   You can change the visibility to ``public`` by going to GitHub Packages from your GitHub account, selecting the ``buildcache`` package, go to ``package settings``, and change the visibility to ``public`` in the ``Danger Zone`` section.
+   This page can also be directly accessed by going to
 
-   .. code-block:: text
+      .. code-block:: text
 
-      https://github.com/users/<user>/packages/container/buildcache/settings
+         https://github.com/users/<user>/packages/container/buildcache/settings
 
 
 -------------------------------