From d0ebfd2325f3debfe93f2396dfd129ce0826c045 Mon Sep 17 00:00:00 2001
From: Gareth Rees <gdr@ravenbrook.com>
Date: Thu, 9 Jan 2014 16:58:32 +0000
Subject: [PATCH] Add glossary entry for client pointer (merged from
 custom/cet/main)

Copied from Perforce
 Change: 183909
 ServerID: perforce.ravenbrook.com
---
 mps/manual/source/glossary/b.rst   |  8 ++++++++
 mps/manual/source/glossary/c.rst   | 10 ++++++++++
 mps/manual/source/glossary/i.rst   |  3 +++
 mps/manual/source/topic/format.rst | 10 ++++++----
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/mps/manual/source/glossary/b.rst b/mps/manual/source/glossary/b.rst
index e312008cf2f..8356404267c 100644
--- a/mps/manual/source/glossary/b.rst
+++ b/mps/manual/source/glossary/b.rst
@@ -92,6 +92,14 @@ Memory Management Glossary: B
 
         .. opposite:: :term:`derived pointer`.
 
+        .. mps:specific::
+
+            For objects with :term:`in-band headers`, the MPS
+            distinguishes between the base pointer, which points to
+            the start of the header, and the :term:`client pointer`,
+            which points to the first word after the end of the
+            header.
+
     best fit
 
         The :term:`allocation policy` that always allocates from the
diff --git a/mps/manual/source/glossary/c.rst b/mps/manual/source/glossary/c.rst
index 15fb1ff9a4a..b2d8f2b1400 100644
--- a/mps/manual/source/glossary/c.rst
+++ b/mps/manual/source/glossary/c.rst
@@ -219,6 +219,16 @@ Memory Management Glossary: C
             objects, the other two being :term:`forwarding objects`
             and :term:`padding objects`.
 
+    client pointer
+
+        .. mps:specific::
+
+            A pointer to the first word in an object that's not part
+            of the :term:`in-band header`. See
+            :ref:`topic-format-headers`.
+
+        .. seealso:: :term:`base pointer`.
+
     client program
 
         .. see:: :term:`mutator`
diff --git a/mps/manual/source/glossary/i.rst b/mps/manual/source/glossary/i.rst
index f0e6ad70eff..9ce2a3f9cea 100644
--- a/mps/manual/source/glossary/i.rst
+++ b/mps/manual/source/glossary/i.rst
@@ -87,6 +87,9 @@ Memory Management Glossary: I
             :c:macro:`MPS_KEY_FMT_HEADER_SIZE` :term:`keyword
             argument` to :c:func:`mps_fmt_create_k`.
 
+            A pointer to the first word after the in-band header is
+            called a :term:`client pointer`.
+
     in parameter
 
         A function parameter that supplies data from the caller to the
diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst
index 46cc6dfd9ee..fb785cd00a9 100644
--- a/mps/manual/source/topic/format.rst
+++ b/mps/manual/source/topic/format.rst
@@ -155,14 +155,16 @@ relation to the memory block.
 If you have one of these use cases, you should pass the
 :c:macro:`MPS_KEY_FMT_HEADER_SIZE` :term:`keyword argument` to
 :c:func:`mps_fmt_create_k`, specifying the size of the header: that
-is, the offset of a client pointer from the base of the memory block.
+is, the offset of a :term:`client pointer` from the base of the memory
+block.
 
 There are some cautions to be observed when using in-band headers:
 
 1. The format methods (other than the :term:`padding method`) receive
-   *client pointers* (that is, pointers past the header) but all other
-   MPS functions expect to receive and return *base pointers* (that
-   is, pointers to the base of the block where the header is stored).
+   :term:`client pointers` (that is, pointers past the header) but all
+   other MPS functions expect to receive and return :term:`base
+   pointers` (that is, pointers to the base of the block where the
+   header is stored).
 
    In particular, :c:func:`mps_reserve` and :c:func:`mps_alloc` always
    hand out base pointers, and :c:func:`mps_free` expects to receive