diff --git a/docs/benchmarks.rst b/docs/benchmarks.rst
index c998a787886912425dc90d982dd5fe8dd5fa28d3_ZG9jcy9iZW5jaG1hcmtzLnJzdA==..47fb6cf117c0a932e02d1020f29313448144e856_ZG9jcy9iZW5jaG1hcmtzLnJzdA== 100644
--- a/docs/benchmarks.rst
+++ b/docs/benchmarks.rst
@@ -2,8 +2,8 @@
 Details on benchmarks in Poulpe
 ===============================
 
-A benchmark describe "something" we want to get performance data on. It is
-defined in a "poulpe-benchmark-definition" file (`.pbd`). It will use code that
-exists in a poulpe's "binary-environment" to benchmark that "something" on the
-data present in a  poulpe's "binary-environment".
+A benchmark describes "something" we want to get performance information about.
+It is defined in a "poulpe-benchmark-definition" file (`.pbd`).
+It will use code that exists in a binary-environment to benchmark
+that "something" on the data present in a data-environment.
 
@@ -9,4 +9,4 @@
 
-The `.pbd` files includes multiple metadata and definition. Some are common to
-all type of benchmarks, some are specific to each type of benchmarks.
+The `.pbd` files include multiple kinds of metadata and definitions.
+Some are common to all types of benchmarks, some are specific.
 
@@ -12,6 +12,6 @@
 
-Generic metata data
-===================
+Generic metadata data
+=====================
 
 section: "meta"
 ---------------
@@ -19,10 +19,10 @@
 format
 ~~~~~~
 
-The version of this benchmark definition. Currently known version  are:
+The version of this benchmark definition. Currently known versions are:
 
 :0: The very first, quite volatile, version.
 
 name
 ~~~~
 
@@ -23,12 +23,12 @@
 
 :0: The very first, quite volatile, version.
 
 name
 ~~~~
 
-identifier of the benchmark. This will be stored in result.
+identifier of the benchmark. This will be stored in results.
 
 method
 ~~~~~~
 
 The way this benchmark is expected to be run. It will also define most of the
@@ -30,7 +30,7 @@
 
 method
 ~~~~~~
 
 The way this benchmark is expected to be run. It will also define most of the
-other value we expect to find to configure this benchmark.
+other values we expect to find to configure this benchmark.
 
@@ -36,5 +36,5 @@
 
-The current list of supported method is :
+The current list of supported methods is:
 
 :simple-command: benchmarking the run of a single shell command.
 :mercurial-perf-extension: using Mercurial perf extensions to run benchmarks
@@ -51,9 +51,9 @@
 section: environment
 --------------------
 
-A section that allow to set environment variable to be used when running the
-command. This is useful to replace some of the command argument with. Each
-sub-key is a an environment variable to replace.
+A section that allows to set environment variables to be used when running the
+command. This is useful to replace some of the command's arguments with. Each
+sub-key is an environment variable to replace.
 
 Value supports the `DATA-VARS:` notation if necessary
 
@@ -68,8 +68,8 @@
 
 The command to be run.
 
-It can we extended with variants (see next section)
+It can be extended with variants (see next section)
 
 cwd
 ~~~
 
@@ -72,6 +72,6 @@
 
 cwd
 ~~~
 
-The directory to run the command in.
+The directory in which to run the command.
 
@@ -77,5 +77,5 @@
 
-Value can be substituded for data-env variable using the
+Values can be substituted for data-env variables using the
 `"DATA-VARS:path.to.variable.in.the.data.env"` syntax.
 
 For example `"DATA-VARS:mercurial.status.large.all"`
@@ -87,8 +87,11 @@
 prepare-run
 ~~~~~~~~~~~
 
-A command (or series of command) to run before each command run.
+A command (or series of commands) to run before each command run.
+
+Note: this command will be run with bash and prefixed with `set -eEuo pipefail`.
+You can opt out of the prefix by specifying "simple-command.no-set-builtin=true"
 
 variants
 --------
 
@@ -91,7 +94,7 @@
 
 variants
 --------
 
-Variants allow for slight variation of a benchmark. For example, they allow to change the
-input data, of to turn some feature on and off.
+Variants allow for slight variations of a benchmark. For example,
+they allow for changing the input data, or for turning some feature on and off.
 
@@ -97,5 +100,5 @@
 
-Variants are organised within independant "dimensions".
+Variants are organized within independent "dimensions".
 
 Each dimension has a set of values, each value can modify the benchmark. Each
 dimension must have a default value.
@@ -107,7 +110,7 @@
 
   simple-command.variants.dimensions.<dimension-name>.<variant-key>
 
-The `dimension-name` and `variant-key` are used as identifier in the benchmark
+The `dimension-name` and `variant-key` are used as identifiers in the benchmark
 result and for selecting variant at run time.
 
 variants variables
@@ -118,9 +121,9 @@
 
 Exactly one variant must have it set to `true` per dimension.
 
-When set and no variant have been explicitly selected for this dimension, this
-variant will be used.
+When set and no variant has been explicitly selected for this dimension during
+a benchmark run, this variant will be used.
 
 extend-command
 ~~~~~~~~~~~~~~
 
@@ -123,9 +126,9 @@
 
 extend-command
 ~~~~~~~~~~~~~~
 
-A string to append to the commend when this variable is selected.
+A string to append to the command when this variable is selected.
 
 cwd
 ~~~
 
@@ -128,6 +131,6 @@
 
 cwd
 ~~~
 
-overwrite the global `simple-command.cwd` variable. Behave the same.
+overwrites the global `simple-command.cwd` variable. Behaves the same.
 
@@ -133,6 +136,6 @@
 
-Mercurial perf extensions configuration
-=======================================
+Mercurial perf extension configuration
+======================================
 
 section: "hg-perf-ext"
 ----------------------
@@ -151,8 +154,8 @@
 args
 ~~~~
 
-Arguments to pass to the command (a list of string).
+Arguments to pass to the command (a list of strings).
 
 setup-script
 ~~~~~~~~~~~~
 
@@ -155,9 +158,12 @@
 
 setup-script
 ~~~~~~~~~~~~
 
-a shell script to run before running the perf-command.
+A shell script to run before running the perf-command.
+
+Note: this command will be run with bash and prefixed with `set -eEuo pipefail`.
+You can opt out of the prefix by specifying "hg-perf-ext.no-set-builtin=true"
 
 constraints
 ~~~~~~~~~~~
 
@@ -160,10 +166,10 @@
 
 constraints
 ~~~~~~~~~~~
 
-Theses variables control when this benchmark can be run.
+These variables control when this benchmark can be run.
 
 Here is the list of currently supported constraints:
 
 - `graph.visible-revision-count.min=<integer>`:
 
@@ -165,10 +171,10 @@
 
 Here is the list of currently supported constraints:
 
 - `graph.visible-revision-count.min=<integer>`:
 
-  Target repository must have at least that many visible revision for this
+  Target repository must have at least that many visible revisions for this
   benchmark to run.
 
 - `compatible-revision-range=<revset>`:
 
@@ -171,10 +177,10 @@
   benchmark to run.
 
 - `compatible-revision-range=<revset>`:
 
-  The range of revision compatible with this changes. 
+  The range of revisions compatible with the command being run.
 
 
 variants
 --------
 
@@ -176,8 +182,8 @@
 
 
 variants
 --------
 
-Variants allow for slight variation of a benchmark. For example, they allow to change the
-input data, of to turn some feature on and off.
+Variants allow for slight variations of a benchmark. For example,
+they allow for changing the input data, of for turning some feature on and off.
 
@@ -183,5 +189,5 @@
 
-Variants are organised within independant "dimensions".
+Variants are organized within independent "dimensions".
 
 Each dimension has a set of values, each value can modify the benchmark. Each
 dimension must have a default value.
@@ -189,7 +195,7 @@
 defining a variant
 ~~~~~~~~~~~~~~~~~~
 
-Variants are defined under keys following this patterns :
+Variants are defined under keys following this pattern:
 
   hg-perf-ext.variants.dimensions.<dimension-name>.<variant-key>
 
@@ -193,8 +199,8 @@
 
   hg-perf-ext.variants.dimensions.<dimension-name>.<variant-key>
 
-The `dimension-name` and `variant-key` are used as identifier in the benchmark
-result and for selecting variant at run time.
+The `dimension-name` and `variant-key` are used as identifiers in the benchmark
+result and for selecting variants at run time.
 
 variants variables
 ~~~~~~~~~~~~~~~~~~
@@ -204,7 +210,7 @@
 
 Exactly one variant must have it set to `true` per dimension.
 
-When set and no variant have been explicitly selected for this dimension, this
+When set and no variant has been explicitly selected for this dimension, this
 variant will be used.
 
 args
@@ -208,10 +214,10 @@
 variant will be used.
 
 args
-~~~~~~~~~~~~~~
+~~~~
 
 A list of args to add to the command
 
 cwd
 ~~~
 
@@ -212,11 +218,11 @@
 
 A list of args to add to the command
 
 cwd
 ~~~
 
-overwrite the global `hg-perf-ext.cwd` variable. Behave the same.
+Overwrites the global `hg-perf-ext.cwd` variable. Behaves the same.
 
 setup-script
 ~~~~~~~~~~~~
 
@@ -219,5 +225,5 @@
 
 setup-script
 ~~~~~~~~~~~~
 
-overwrite the global `hg-perf-ext.setup-script` variable. Behave the same.
+Overwrites the global `hg-perf-ext.setup-script` variable. Behaves the same.