[WIP][RFC] sframe: doc: Spec terminology change from offset to data item

This patch applies on top of the upstream branch
users/ibhagat/sframe-v3-jan14-v4.

I attempted to see what the terminology change would look like.  This
patch is my first shabby attempt.

Whats not attempted, but needs to be covered:
  - (#1) The spec defines "fre_offset_count" and "fre_offset_size"
  - (#2) There are other constants:
    SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B, SFRAME_FRE_OFFSET_4B.
    Changing these constants is a search-replace patch touching gas/ and
    ld/ and libsframe/, not attempted either.
  - (#3) Control/Register Word, Displacement Word does not seem to fit
    very well: The "Control/Register Word" contains the register data,
    so I kept the name as such, and not "Control Word"

What do you think ?  I do not prefer to do this last minute change
anymore; there could be more renames needed in code once we start from
(#2) above. (#1) could be addressed by renaming those to
"fre_dataitem_count", and "fre_dataitem_size", but I find the latter
even more awkward.  More misfit like feeling arises with (#3).

That said, I will reconsider if your judgement is different.  Please let
me know what you think.

libsframe/doc/sframe-spec.texi

@@ -780,8 +780,9 @@ signed offset.  Return Address (RA) and Frame Pointer (FP) are recovered using
 the CFA plus a signed offset (or a fixed register for specific
 architectures like s390x).
 
-The variable-length stack offsets are interpreted according to the ABI/arch-specific
+The variable-length bytes trailing each SFrame FRE are interpreted according
-rules for the target architecture.  More details in @ref{Default FDE Type Interpretation}.
+to the ABI/arch-specific rules for the target architecture.  More details in
+@ref{Default FDE Type Interpretation}.
 
 @tindex SFRAME_FDE_TYPE_FLEX
 @item @code{SFRAME_FDE_TYPE_FLEX}
@@ -791,16 +792,18 @@ Used for complex cases such as stack realignment (DRAP), non-standard CFA base
 registers, or when RA/FP recovery requires dereferencing or non-CFA base
 registers.
 
-The variable-length stack offsets are interpreted as pairs of Control Data
+The variable-length bytes trailing each SFrame FRE are interpreted as pairs
-and Displacements, allowing for complex recovery rules (e.g., DRAP on AMD64,
+of Control Word and Data Word, allowing for complex recovery rules (e.g.,
-Stack Realignment).  More details in @ref{Flexible FDE Type Interpretation}.
+DRAP on AMD64, Stack Realignment).  More details in @ref{Flexible FDE Type
+Interpretation}.
 @end multitable
 
 @cindex Provisions for future ABIs
-Currently, five bits are reserved in the @code{sfda_func_info2} for indicating
+Currently, five bits are reserved in the @code{sfda_func_info2} for
-SFrame FDE types.  In future, other ABIs/architectures may add even
+indicating SFrame FDE types.  In future, other ABIs/architectures may add
-arch-specific FDE types.  Each distinct FDE type may define a different layout,
+even arch-specific FDE types.  Each distinct FDE type may define a different
-encoding, and interpretation of the SFrame FRE offsets.
+layout, encoding, and interpretation of the variable-length bytes trailing
+each SFrame FRE.
 
 
 @node The SFrame FRE Types
@@ -852,15 +855,16 @@ containing SFrame stack trace information for a range of contiguous
 (instruction) addresses, starting at the specified offset from the start of the
 function.
 
-Each SFrame FRE encodes the stack offsets to recover the CFA, FP and RA (as
+Each SFrame FRE encodes the information to recover the CFA, FP and RA (as
 specified by the ABI or the FDE type) for the respective instruction addresses.
 To encode this information, each SFrame FRE is followed by S*N bytes, where:
 
 @itemize @minus
 @item
-@code{S} is the size of a stack offset for the FRE, and
+@code{S} is the size of each data item in the variable-length bytes trailing
+the SFrame FRE, and
 @item
-@code{N} is the number of stack offsets in the FRE
+@code{N} is the number of data items in the respective FRE.
 @end itemize
 
 The entities @code{S}, @code{N} are encoded in the SFrame FRE info byte, via
@@ -869,10 +873,10 @@ information about the precise encoding and range of values for @code{S} and
 @code{N} is provided later in the @ref{The SFrame FRE Info Word}.
 
 @cindex Provisions for future ABIs
-It is important to underline here that although the canonical interpretation
+It is important to underline here that although the canonical interpretation of
-of these bytes is as stack offsets (to recover CFA, FP and RA), these bytes
+these bytes is as stack offsets (to recover CFA, FP and RA) for default FDE
-@emph{may} be used by future ABIs/architectures to convey other information on
+type, these bytes @emph{may} be used by future ABIs/architectures to convey
-a per SFrame FRE basis.
+other information on a per SFrame FRE basis.
 
 In summary, SFrame file format, by design, supports a variable number of stack
 offsets at the tail end of each SFrame FRE.  To keep the SFrame file
@@ -1155,23 +1159,23 @@ rule.
 @end itemize
 
 In a flexible FDE type, for each tracked entity (CFA, RA, FP), the SFrame FRE
-carries a pair of offsets to specify the respective recovery rule.
+carries a pair of data items to specify the respective recovery rule.
 
 @enumerate
 @item
-Offset 1 (Control/Register Data): Encodes the base register number, a
+Data item 1 (Control/Register Data): Encodes the base register number, a
 dereference flag, and a register-mode flag.
 @item
-Offset 2 (Displacement Data): Encodes the signed offset to be added to the base.
+Data item 2 (Displacement Data): Encodes the signed offset to be added to the base.
 @end enumerate
 
-The offsets appear in the order: CFA, RA, FP.  These offsets obey the
+Each pair of data items appears in the order: CFA, RA, FP.  These data items
-@code{fre_offset_size} defined in the FRE info byte (i.e., they are 1, 2, or 4
+obey the @code{fre_offset_size} defined in the FRE info byte (i.e., they are 1,
-bytes wide).
+2, or 4 bytes wide).
 
-@subsubheading Encoding of Offset 1 (Control/Register Data)
+@subsubheading Encoding of Data 1 (Control/Register Data)
 
-The first offset of the pair is an unsigned integer of width
+The first data item of the pair is an unsigned integer of width
 @code{fre_offset_size}.  It is used as a bitfield that describes
 register/control data for the tracked entity.  From LSB to MSB:
 
@@ -1198,15 +1202,15 @@ If 0, the value is @code{Base + Offset}.
 @end multitable
 
 A value of 0 in the Control/Register Data is used to indicate that no further
-offset data follows for the tracked entity.  Using the value of 0 in
+data item follows for the tracked entity.  Using the value of 0 in
 Control/Register Data (i.e., regnum = 0, deref_p = 0, reg_p = 0) to designate
 invalid tracking info does mean that currently, e.g., for RA, the rule RA = CFA
 + 0 cannot be encoded.  NB: RA = CFA + 0 is distinct from RA = *(CFA + 0).  The
 former should not be needed for any ABI, and the latter is representable.
 
-@subsubheading Encoding of Offset 2 (Displacement Data)
+@subsubheading Encoding of Data 2 (Displacement Data)
 
-The second offset of the pair is a signed integer of width
+The second data item of the pair is a signed integer of width
 @code{fre_offset_size}.  It is used as a stack offset for the respective
 tracked entity (CFA, FP or RA).
 
@@ -1384,9 +1388,9 @@ interpreting the Control Data and Displacement Data pair for flexible FDEs:
 
 @example
     // Apply SFrame V3 Flex FDE recovery rule.
-    // reg_data: The Control Data (Offset 1)
+    // reg_data: The Control Data (Data item 1)
                  containing reg_p, deref_p, regnum.
-    // offset:   The Displacement (Offset 2).
+    // offset:   The Displacement (Data item 2).
     // cfa:      The current CFA value (used as base if reg_p is 0).
     // cfa_p:    Bool indicating if we are currently recovering the
                  CFA itself.