Refactor how to use section

Makefile

@@ -7,7 +7,7 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
-# SOURCE_DATE_EPOCH = $(shell git log -1 --format=%ct)
+SOURCE_DATE_EPOCH = $(shell git log -1 --format=%ct)
 
 # Put it first so that "make" without argument is like "make help".
 help:

hoh.nix

@@ -31,6 +31,10 @@ pkgs.stdenv.mkDerivation {
    src     = ./.;
    propagatedBuildInputs = pythonInputs ++ nonPythonInputs;
 
+   preBuild = ''
+  SOURCE_DATE_EPOCH="$(${pkgs.coreutils}/bin/date '+%s')"
+  '';
+
    buildPhase = ''
    runHook preBuild
    make ${target} SPHINXOPTS="-W"

src/Measurement_Observation/Heap_Third/cachegrind.rst

@@ -1,4 +1,6 @@
-.. _Cachegrind:
+.. _Cachegrind Chapter:
 
 :lightgrey:`Using Cachegrind`
 =============================
+
+`TODO <https://github.com/haskellfoundation/hs-opt-handbook.github.io/issues/10>`_

src/Measurement_Observation/Measurement_Libs/weigh.rst

@@ -10,7 +10,7 @@ useful to confirm that a data structure or function has the memory performance
 you anticipate it to have at *runtime*. ``Weigh`` is easy to setup and
 non-invasive; requiring no changes to source code. Thus, it is a good *initial*
 tool to use before trying more advanced methods with higher setup costs, such as
-:ref:`Cachegrind <Cachegrind>`.
+:ref:`Cachegrind <Cachegrind Chapter>`.
 
 
 Requirements

src/Measurement_Observation/Measurement_Third/linux_perf.rst

@@ -1,4 +1,4 @@
-.. Perf
+.. _Perf Chapter:
 
 :lightgrey:`The perf utility`
 =============================

src/Preliminaries/how_to_use.rst

@@ -7,7 +7,7 @@ Purpose
 -------
 
 This book is written as a handbook for the intrepid Haskell developer. It
-attempts to make clear aspects of the GHC-based Haskell so that performance
+attempts to make clear aspects of GHC-based Haskell so that performance
 optimizations and recommendations are actionable, rather than mysterious
 invocations whispered around the internet.
 
@@ -17,7 +17,7 @@ Intended Audience
 The Haskell Optimization Handbook is intended for developers using Haskell in
 their day to day life for money or pleasure. It assumes the audience is
 proficient with pure functional programming concepts, such as recursion, purity,
-higher-ordered functions functors, applicative functors, monads et cetera., and
+higher-ordered functions, functors, applicative functors, monads et cetera., and
 the basics of the Haskell ecosystem, such as using cabal or stack to compile and
 run a project.
 
@@ -65,18 +65,20 @@ handbook. Thus, the book is not meant to be read in a linear order. Instead, one
 should pick and choose which chapter to read next based on their needs because
 *the book assumes you have a problem that needs solving*.
 
-There are two general sections; both are ordered from the least time consuming
-to most time consuming topics. The first section, Part 1, aids the developer in
-identifying performance issues in their own code. Part 1 is primarily concerned
-with measurement, observation, repeatability and testing, but also includes
-methods of *direct observation* such as inspecting and understanding the
-``Core`` and ``Stg`` languages.
+There are two parts: Part 1, focuses on measurement, profiling and observation
+of Haskell programs. This part is ordered from the bottom-up; it begins with
+tools and probes that are language agnostic and close to the machine, such as
+:ref:`Perf <Perf Chapter>` and :ref:`Cachegrind <Cachegrind Chapter>`, then
+proceeds through each `intermediate representation
+<https://en.wikipedia.org/wiki/Intermediate_representation#:~:text=An%20intermediate%20representation%20(IR)%20is,such%20as%20optimization%20and%20translation.>`_
+(IR) describing the tools, probes, and information available at each IR.
 
-The second section, Part 2, aids the developer in optimizing their code. It is
+Part 2, provides an ordered sequence of techniques to optimize code. It is
 ordered from the easiest methods, such as choosing the right libraries; to the
-hardest methods, such as exploiting ``backpack`` for fine-grained
-:term:`Unboxed` data types or exploiting :term:`Levity Polymorphism` to control
-the runtime representation of a data type.
+hardest and more invasive methods, such as exploiting :ref:`Backpack <Backpack
+Chapter>` for fine-grained :term:`Unboxed` data types or exploiting
+:term:`Levity Polymorphism` to control the runtime representation of a data
+type.
 
 
 Goals
@@ -111,6 +113,10 @@ HOH does not have:
    a given platform.
 #. Descriptions, analyses and explanations of functional algorithms or data
    structures. Content will instead be "Try unordered-containers if you have
-   foo, bar, baz", rather than "This is what a bankers queue or HAMT is ...".
+   this or that set of constraints", rather than "This is what a banker's queue
+   [#]_ or `HAMT <https://en.wikipedia.org/wiki/Hash_array_mapped_trie>`_ is
+   ...".
 #. A monad or monad transformer tutorial. This is assumed knowledge in the
    audience.
+
+.. [#] See :cite:t:`okasaki`, page 23.