doc: clean up discussion of scratch space

diff --git a/doc/dev-reference/runtime.rst b/doc/dev-reference/runtime.rst
index 0f3fc5fa78c4ef75d4a1491ff3e37c537a505d78..665395a83ac82c853eb53bb2f6ccbdd94b4712d4 100644 (file)
--- a/doc/dev-reference/runtime.rst
+++ b/doc/dev-reference/runtime.rst
@@ -124,13 +124,19 @@ databases, only a single scratch region is necessary: in this case, calling
 will ensure that the scratch space is large enough to support scanning against
 any of the given databases.
 
-Importantly, only one such space is required per thread and can (and indeed
-should) be allocated before data scanning is to commence. In a scenario where a
-set of expressions are compiled by a single "master" thread and data will be
-scanned by multiple "worker" threads, the convenience function
-:c:func:`hs_clone_scratch` allows multiple copies of an existing scratch space
-to be made for each thread (rather than forcing the caller to pass all the
-compiled databases through :c:func:`hs_alloc_scratch` multiple times).
+While the Hyperscan library is re-entrant, the use of scratch spaces is not.
+For example, if by design it is deemed necessary to run recursive or nested
+scanning (say, from the match callback function), then an additional scratch
+space is required for that context.
+
+In the absence of recursive scanning, only one such space is required per thread
+and can (and indeed should) be allocated before data scanning is to commence.
+
+In a scenario where a set of expressions are compiled by a single "master"
+thread and data will be scanned by multiple "worker" threads, the convenience
+function :c:func:`hs_clone_scratch` allows multiple copies of an existing
+scratch space to be made for each thread (rather than forcing the caller to pass
+all the compiled databases through :c:func:`hs_alloc_scratch` multiple times).
 
 For example:
 
@@ -163,14 +169,6 @@ For example:
     /* Now two threads can both scan against database db,
        each with its own scratch space. */
 
-While the Hyperscan library is re-entrant, the use of scratch spaces is not.
-For example, if by design it is deemed necessary to run recursive or nested
-scanning (say, from the match callback function), then an additional scratch
-space is required for that context.
-
-The easiest way to achieve this is to build up a single scratch space as a
-prototype, then clone it for each context:
-
 *****************
 Custom Allocators
 *****************