Small manual improvements.

Copied from Perforce
 Change: 195243

mps/manual/source/guide/advanced.rst

@@ -877,7 +877,7 @@ Second, the leaf objects must be allocated on ``leaf_ap`` instead of
     res = mps_ap_create_k(&leaf_ap, leaf_pool, mps_args_none);
     if (res != MPS_RES_OK) error("Couldn't create leaf objects allocation point");
 
-Note that the new pool shared a :term:`generation chain` with the old
+Note that the new pool shares a :term:`generation chain` with the old
 pool. This is important, because the leaf objects live and die along
 with the non-leaf objects of similar ages.
 

mps/manual/source/release.rst

@@ -48,10 +48,10 @@ Interface changes
    :c:macro:`MPS_KEY_SPARE`, :c:func:`mps_arena_spare` and
    :c:func:`mps_arena_spare_set` instead.
 
-#. The format of :term:`telemetry` events has changed: Booleans are no
-   longer packed into bitfields, but are emitted as unsigned bytes.
-   This makes it possible to decode telemetry events using Python's
-   |struct|_.
+#. The format of the :term:`telemetry stream` has changed: Booleans
+   are no longer packed into bitfields, but are emitted as unsigned
+   bytes. This makes it possible to decode the telemetry stream using
+   the Python function |struct|_.
 
    .. |struct| replace:: ``struct.unpack``
    .. _struct: https://docs.python.org/3/library/struct.html#struct.unpack

mps/manual/source/topic/deprecated.rst

@@ -898,8 +898,12 @@ Deprecated in version 1.111
 
     .. deprecated::
 
-        If you need access to protected memory for debugging,
-        :ref:`contact us <contact>`.
+        If you need access to protected memory for debugging a fatal
+        error, use :c:func:`mps_arena_postmortem` instead.
+
+        If you need access to protected memory and also need to
+        continue running the MPS afterwards, :ref:`contact us
+        <contact>`.
 
     Ensure that the MPS is not protecting any :term:`page` in the
     :term:`arena` with a :term:`read barrier` or :term:`write

mps/manual/source/topic/error.rst

@@ -393,9 +393,9 @@ Varieties
 ---------
 
 The MPS has three *varieties* which have different levels of internal
-checking and :ref:`telemetry <topic-telemetry>`. The variety can be
-selected at compile time, by defining one of the following
-preprocessor constants. If none is specified then
+checking, :ref:`topic-error-assertion` and :ref:`topic-telemetry`. The
+variety can be selected at compile time, by defining one of the
+following preprocessor constants. If none is specified then
 :c:macro:`CONFIG_VAR_HOT` is the default.
 
 
@@ -430,8 +430,8 @@ preprocessor constants. If none is specified then
     in the default ANSI Library, the default assertion handler will not
     terminate the program.  See :c:func:`mps_lib_assert_fail_install`.
 
-    Some events are sent to the telemetry stream, namely those not on
-    the :term:`critical path`.
+    Some events are sent to the :term:`telemetry stream`, namely those
+    not on the :term:`critical path`.
 
 
 .. index::
@@ -446,4 +446,4 @@ preprocessor constants. If none is specified then
     No functions check the consistency of their data structures and
     consequently there are no assertions.
 
-    No events are sent to the telemetry stream.
+    No events are sent to the :term:`telemetry stream`.

mps/manual/source/topic/plinth.rst

@@ -30,8 +30,7 @@ support it needs from the execution environment. The MPS uses the plinth instead
 
 #. The plinth gives the :term:`client program` complete control of
    interaction between the MPS and the user, including
-   :ref:`assertions <topic-error-assertion>` and :ref:`telemetry
-   <topic-telemetry>`.
+   :ref:`topic-error-assertion` and :ref:`topic-telemetry`.
 
 The plinth may be provided by the :term:`client program`; however, a
 sample implementation of the plinth using ANSI Standard C Library

mps/manual/source/topic/security.rst

@@ -81,7 +81,7 @@ In its :term:`hot` and :term:`cool` varieties, the MPS contains a
 events for later analysis and debugging. When using the default
 :term:`plinth`, the behaviour of the telemetry system is under the
 control of the environment variable :envvar:`MPS_TELEMETRY_CONTROL`,
-and the telemetry stream is written to the file named by the
+and the :term:`telemetry stream` is written to the file named by the
 environment variable :envvar:`MPS_TELEMETRY_FILENAME`.
 
 This means that an attacker who can set arbitrary environment

mps/manual/source/topic/telemetry.rst

@@ -507,8 +507,8 @@ used in queries, for example:
         If the ``User`` event category is not turned on in the
         :term:`telemetry filter` (via :c:func:`mps_telemetry_set` or
         :envvar:`MPS_TELEMETRY_CONTROL`) then the string is not sent
-        to the telemetry stream. A label is still returned in this
-        case, but it is useless.
+        to the :term:`telemetry stream`. A label is still returned in
+        this case, but it is useless.
 
 
 .. c:function:: void mps_telemetry_label(mps_addr_t addr, mps_label_t label)
@@ -518,7 +518,7 @@ used in queries, for example:
 
     ``addr`` is an address.
 
-    ``label`` is a telemetry label returned from
+    ``label`` is a :term:`telemetry label` returned from
     :c:func:`mps_telemetry_intern`.
 
     The label will be associated with the address when it appears in
@@ -544,12 +544,12 @@ rather than writing it to a file on the local filesystem) then you may
 be able to do so by providing your own implementation of the
 :ref:`topic-plinth-io`.
 
-When it first needs to output telemetry, the MPS call the plinth
-function :c:func:`mps_io_create` to create an I/O stream. It then
-calls :c:func:`mps_io_write` to write binary data to the stream
-and :c:func:`mps_io_flush` to flush the stream in response to
-:c:func:`mps_telemetry_flush`. By providing your own implementations
-of these functions, you can direct the telemetry stream wherever you
-like.
+When it first needs to output the :term:`telemetry stream`, the MPS
+calls the plinth function :c:func:`mps_io_create` to create an I/O
+stream. It then calls :c:func:`mps_io_write` to write binary data to
+the stream and :c:func:`mps_io_flush` to flush the stream in response
+to :c:func:`mps_telemetry_flush`. By providing your own
+implementations of these functions, you can direct the telemetry
+stream wherever you like.
 
 See :ref:`topic-plinth` for details.