erl_interface: Editorial changes

1 files changed, 378 insertions, 308 deletions

diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml
index 7928e4f5d1..6d416028a5 100644
--- a/lib/erl_interface/doc/src/ei.xml
+++ b/lib/erl_interface/doc/src/ei.xml
@@ -33,328 +33,368 @@
     <file>ei.xml</file>
   </header>
   <lib>ei</lib>
-  <libsummary>routines for handling the erlang binary term format</libsummary>
+  <libsummary>Routines for handling the Erlang binary term format.</libsummary>
   <description>
     <p>The library <c><![CDATA[ei]]></c> contains macros and functions to encode
-      and decode the erlang binary term format.</p>
-    <p>With <c><![CDATA[ei]]></c>, you can convert atoms, lists, numbers and
+      and decode the Erlang binary term format.</p>
+
+    <p><c><![CDATA[ei]]></c> allows you to convert atoms, lists, numbers, and
       binaries to and from the binary format. This is useful when
       writing port programs and drivers. <c><![CDATA[ei]]></c> uses a given
-      buffer, and no dynamic memory (with the exception of
-      <c><![CDATA[ei_decode_fun()]]></c>), and is often quite fast.</p>
-    <p>It also handles C-nodes, C-programs that talks erlang
-      distribution with erlang nodes (or other C-nodes) using the
-      erlang distribution format. The difference between <c><![CDATA[ei]]></c> and
-      <c><![CDATA[erl_interface]]></c> is that <c><![CDATA[ei]]></c> uses the binary format
-      directly when sending and receiving terms. It is also thread
-      safe, and using threads, one process can handle multiple
+      buffer, no dynamic memory (except
+      <c><![CDATA[ei_decode_fun()]]></c>) and is often quite fast.</p>
+
+    <p><c><![CDATA[ei]]></c> also handles C-nodes, C-programs that talks Erlang
+      distribution with Erlang nodes (or other C-nodes) using the
+      Erlang distribution format. The difference between <c><![CDATA[ei]]></c>
+      and <c><![CDATA[erl_interface]]></c> is that <c><![CDATA[ei]]></c> uses
+      the binary format directly when sending and receiving terms. It is also
+      thread safe, and using threads, one process can handle multiple
       C-nodes. The <c><![CDATA[erl_interface]]></c> library is built on top of
-      <c><![CDATA[ei]]></c>, but of legacy reasons, it doesn't allow for multiple
-      C-nodes. In general, <c><![CDATA[ei]]></c> is the preferred way of doing
-      C-nodes.</p>
-    <p>The decode and encode functions use a buffer an index into the
+      <c><![CDATA[ei]]></c>, but of legacy reasons, it does not allow for
+      multiple C-nodes. In general, <c><![CDATA[ei]]></c> is the preferred way
+      of doing C-nodes.</p>
+
+    <p>The decode and encode functions use a buffer and an index into the
       buffer, which points at the point where to encode and
       decode. The index is updated to point right after the term
       encoded/decoded. No checking is done whether the term fits in
       the buffer or not. If encoding goes outside the buffer, the
-      program may crash.</p>
-    <p>All functions takes two parameter, <c><![CDATA[buf]]></c> is a pointer to
-      the buffer where the binary data is / will be, <c><![CDATA[index]]></c> is a
-      pointer to an index into the buffer. This parameter will be
-      incremented with the size of the term decoded / encoded. The
-      data is thus at <c><![CDATA[buf[*index]]]></c> when an <c><![CDATA[ei]]></c> function is
-      called.</p>
-    <p>The encode functions all assumes that the <c><![CDATA[buf]]></c> and
-      <c><![CDATA[index]]></c> parameters points to a buffer big enough for the
-      data. To get the size of an encoded term, without encoding it,
-      pass <c><![CDATA[NULL]]></c> instead of a buffer pointer. The <c><![CDATA[index]]></c>
-      parameter will be incremented, but nothing will be encoded. This
+      program can crash.</p>
+
+    <p>All functions take two parameters:</p>
+
+    <list type="bulleted">
+      <item><p><c><![CDATA[buf]]></c> is a pointer to
+        the buffer where the binary data is or will be.</p>
+      </item>
+      <item><p><c><![CDATA[index]]></c> is a pointer to an index into the
+        buffer. This parameter is incremented with the size of the term
+        decoded/encoded.</p>
+      </item>
+    </list>
+
+    <p>The data is thus at <c><![CDATA[buf[*index]]]></c> when an
+      <c><![CDATA[ei]]></c> function is called.</p>
+
+    <p>All encode functions assume that the <c><![CDATA[buf]]></c> and
+      <c><![CDATA[index]]></c> parameters point to a buffer large enough for
+      the data. To get the size of an encoded term, without encoding it,
+      pass <c><![CDATA[NULL]]></c> instead of a buffer pointer. Parameter
+      <c><![CDATA[index]]></c> is incremented, but nothing will be encoded. This
       is the way in <c><![CDATA[ei]]></c> to "preflight" term encoding.</p>
-    <p>There are also encode-functions that uses a dynamic buffer. It
+
+    <p>There are also encode functions that use a dynamic buffer. It
       is often more convenient to use these to encode data. All encode
-      functions comes in two versions: those starting with <c><![CDATA[ei_x]]></c>,
-      uses a dynamic buffer.</p>
-    <p>All functions return <c><![CDATA[0]]></c> if successful, and <c><![CDATA[-1]]></c> if
-      not. (For instance, if a term is not of the expected type, or
-      the data to decode is not a valid erlang term.)</p>
-    <p>Some of the decode-functions needs a preallocated buffer. This
-      buffer must be allocated big enough, and for non compound types
+      functions comes in two versions; those starting with
+      <c><![CDATA[ei_x]]></c> use a dynamic buffer.</p>
+
+    <p>All functions return <c><![CDATA[0]]></c> if successful, otherwise
+      <c><![CDATA[-1]]></c> (for example, if a term is not of the expected
+      type, or the data to decode is an invalid Erlang term).</p>
+
+    <p>Some of the decode functions need a pre-allocated buffer. This
+      buffer must be allocated large enough, and for non-compound types
       the <c><![CDATA[ei_get_type()]]></c>
-      function returns the size required (note that for strings an
+      function returns the size required (notice that for strings an
       extra byte is needed for the 0 string terminator).</p>
   </description>
-  <section>
-    <title>DATA TYPES</title>
 
+  <section>
+    <title>Data Types</title>
     <taglist>
       <tag><marker id="erlang_char_encoding"/>erlang_char_encoding</tag>
        <item>
-	 <p/>
 	 <code type="none">
 typedef enum {
     ERLANG_ASCII = 1,
     ERLANG_LATIN1 = 2,
     ERLANG_UTF8 = 4
-}erlang_char_encoding;
-</code>
-         <p>The character encodings used for atoms. <c>ERLANG_ASCII</c> represents 7-bit ASCII.
-	 Latin1 and UTF8 are different extensions of 7-bit ASCII. All 7-bit ASCII characters
-	 are valid Latin1 and UTF8 characters. ASCII and Latin1 both represent each character
-	 by one byte. A UTF8 character can consist of one to four bytes. Note that these
-	 constants are bit-flags and can be combined with bitwise-or.</p>
+}erlang_char_encoding;</code>
+         <p>The character encodings used for atoms. <c>ERLANG_ASCII</c>
+           represents 7-bit ASCII. Latin-1 and UTF-8 are different extensions
+           of 7-bit ASCII. All 7-bit ASCII characters are valid Latin-1 and
+           UTF-8 characters. ASCII and Latin-1 both represent each character
+	   by one byte. An UTF-8 character can consist of 1-4 bytes.
+           Notice that these
+	   constants are bit-flags and can be combined with bitwise OR.</p>
       </item>
     </taglist>
   </section>
+
   <funcs>
       <func>
           <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name>
           <fsummary>Decode an atom.</fsummary>
           <desc>
-              <p>This function decodes an atom from the binary format.  The
-                  null terminated name of the atom is placed at <c><![CDATA[p]]></c>. There can be at most
-                  <c><![CDATA[MAXATOMLEN]]></c> bytes placed in the buffer.</p>
+              <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated
+                  name of the atom is placed at <c><![CDATA[p]]></c>. At most
+                  <c><![CDATA[MAXATOMLEN]]></c> bytes can be placed in the buffer.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name>
           <fsummary>Decode an atom.</fsummary>
           <desc>
-              <p>This function decodes an atom from the binary format. The
-                  null terminated name of the atom is placed in buffer at <c>p</c> of length
-                  <c>plen</c> bytes.</p>
-              <p>The wanted string encoding is specified by <seealso marker="#erlang_char_encoding">
-                      <c>want</c></seealso>. The original encoding used in the
-                  binary format (latin1 or utf8) can be obtained from <c>*was</c>. The actual encoding of the resulting string
-                  (7-bit ascii, latin1 or utf8) can be obtained from <c>*result</c>. Both <c>was</c> and <c>result</c> can be <c>NULL</c>.
-
-                  <c>*result</c> may differ from <c>want</c> if <c>want</c> is a bitwise-or'd combination like
-                  <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if <c>*result</c> turn out to be pure 7-bit ascii
-                  (compatible with both latin1 and utf8).</p>
+              <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated
+                  name of the atom is placed in buffer at <c>p</c> of length <c>plen</c>
+                  bytes.</p>
+              <p>The wanted string encoding is specified by
+                  <seealso marker="#erlang_char_encoding"><c>want</c></seealso>.
+                  The original encoding used in the binary format (Latin-1 or UTF-8) can
+                  be obtained from <c>*was</c>. The encoding of the resulting string
+                  (7-bit ASCII, Latin-1, or UTF-8) can be obtained from <c>*result</c>.
+                  Both <c>was</c> and <c>result</c> can be <c>NULL</c>. <c>*result</c>
+                  can differ from <c>want</c> if <c>want</c> is a bitwise OR'd
+                  combination like <c>ERLANG_LATIN1|ERLANG_UTF8</c> or if
+                  <c>*result</c> turns out to be pure 7-bit ASCII
+                  (compatible with both Latin-1 and UTF-8).</p>
               <p>This function fails if the atom is too long for the buffer
-                  or if it can not be represented with encoding <c>want</c>.</p>
-              <p>This function was introduced in R16 release of Erlang/OTP as part of a first step
-                  to support UTF8 atoms.</p>
+                  or if it cannot be represented with encoding <c>want</c>.</p>
+              <p>This function was introduced in Erlang/OTP R16 as part of a first
+                  step to support UTF-8 atoms.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name>
           <fsummary>Decode a GMP arbitrary precision integer.</fsummary>
           <desc>
-              <p>This function decodes an integer in the binary format to a GMP <c><![CDATA[mpz_t]]></c> integer.
-                  To use this function the ei library needs to be configured and compiled
-                  to use the GMP library. </p>
+              <p>Decodes an integer in the binary format to a GMP
+                  <c><![CDATA[mpz_t]]></c> integer. To use this function, the <c>ei</c>
+                  library must be configured and compiled to use the GMP library.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name>
           <fsummary>Decode a binary.</fsummary>
           <desc>
-              <p>This function decodes a binary from the binary format. The
-                  <c><![CDATA[len]]></c> parameter is set to the actual size of the
-                  binary. Note that <c><![CDATA[ei_decode_binary()]]></c> assumes that there
-                  are enough room for the binary. The size required can be
+              <p>Decodes a binary from the binary format. Parameter
+                  <c><![CDATA[len]]></c> is set to the actual size of the
+                  binary. Notice that <c><![CDATA[ei_decode_binary()]]></c> assumes that
+                  there is enough room for the binary. The size required can be
                   fetched by <c><![CDATA[ei_get_type()]]></c>.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name>
           <fsummary>Decode a boolean.</fsummary>
           <desc>
-              <p>This function decodes a boolean value from the binary
-                  format. A boolean is actually an atom, <c><![CDATA[true]]></c> decodes 1
+              <p>Decodes a boolean value from the binary format.
+                  A boolean is actually an atom, <c><![CDATA[true]]></c> decodes 1
                   and <c><![CDATA[false]]></c> decodes 0.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name>
           <fsummary>Decode an 8-bit integer between 0-255.</fsummary>
           <desc>
-              <p>This function decodes a char (8-bit) integer between 0-255
-                  from the binary format.
-                  Note that for historical reasons the returned integer is of
-                  type <c><![CDATA[char]]></c>. Your C code should consider the
+              <p>Decodes a char (8-bit) integer between 0-255 from the binary format.
+                  For historical reasons the returned integer is of
+                  type <c><![CDATA[char]]></c>. Your C code is to  consider the
                   returned value to be of type <c><![CDATA[unsigned char]]></c> even if
-                  the C compilers and system may define <c><![CDATA[char]]></c> to be
+                  the C compilers and system can define <c><![CDATA[char]]></c> to be
                   signed.</p>
           </desc>
       </func>
+
       <func>
           <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name>
           <fsummary>Decode a double.</fsummary>
           <desc>
-              <p>This function decodes an double-precision (64 bit) floating
+              <p>Decodes a double-precision (64-bit) floating
                   point number from the binary format.</p>
           </desc>
       </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name>
-      <fsummary>Decode a term, without prior knowledge of type.</fsummary>
-      <desc>
-        <p>This function decodes any term, or at least tries to. If the
-          term pointed at by <c><![CDATA[*index]]></c> in <c><![CDATA[buf]]></c> fits in the
-          <c><![CDATA[term]]></c> union, it is decoded, and the appropriate field
-          in <c><![CDATA[term->value]]></c> is set, and <c><![CDATA[*index]]></c> is
-          incremented by the term size.</p>
-        <p>The function returns 1 on successful decoding, -1 on error,
-          and 0 if the term seems alright, but does not fit in the
-          <c><![CDATA[term]]></c> structure. If it returns 1, the <c><![CDATA[index]]></c>
-          will be incremented, and the <c><![CDATA[term]]></c> contains the
-          decoded term.</p>
-        <p>The <c><![CDATA[term]]></c> structure will contain the arity for a tuple
-          or list, size for a binary, string or atom. It will contains
-          a term if it's any of the following: integer, float, atom,
-          pid, port or ref.</p>
+      <fsummary>Decode a term, without previous knowledge of type.</fsummary>
+      <desc>
+        <p>Decodes any term, or at least tries to. If the term
+          pointed at by <c><![CDATA[*index]]></c> in <c><![CDATA[buf]]></c> fits
+          in the <c><![CDATA[term]]></c> union, it is decoded, and the
+          appropriate field in <c><![CDATA[term->value]]></c> is set, and
+          <c><![CDATA[*index]]></c> is incremented by the term size.</p>
+        <p>The function returns <c>1</c> on successful decoding, <c>-1</c> on
+          error, and <c>0</c> if the term seems alright, but does not fit in the
+          <c><![CDATA[term]]></c> structure. If <c>1</c> is returned, the
+          <c><![CDATA[index]]></c> is incremented, and <c><![CDATA[term]]></c>
+          contains the decoded term.</p>
+        <p>The <c><![CDATA[term]]></c> structure contains the arity for a tuple
+          or list, size for a binary, string, or atom. It contains
+          a term if it is any of the following: integer, float, atom,
+          pid, port, or ref.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name>
       <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name>
       <fsummary>Decode a fun.</fsummary>
       <desc>
-        <p>This function decodes a fun from the binary format. The
-          <c><![CDATA[p]]></c> parameter should be NULL or point to an
+        <p>Decodes a fun from the binary format. Parameter
+          <c><![CDATA[p]]></c> is to be <c>NULL</c> or point to an
           <c><![CDATA[erlang_fun]]></c> structure. This is the only decode
-          function that allocates memory; when the <c><![CDATA[erlang_fun]]></c>
-          is no longer needed, it should be freed with
-          <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size of
-          the environment for a fun.)</p>
+          function that allocates memory. When the <c><![CDATA[erlang_fun]]></c>
+          is no longer needed, it is to be freed with
+          <c><![CDATA[free_fun]]></c>. (This has to do with the arbitrary size
+          of the environment for a fun.)</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name>
       <fsummary>Decode a list.</fsummary>
       <desc>
-        <p>This function decodes a list header from the binary
+        <p>Decodes a list header from the binary
           format. The number of elements is returned in
-          <c><![CDATA[arity]]></c>. The <c><![CDATA[arity+1]]></c> elements follows (the last
-          one is the tail of the list, normally an empty list.) If
-          <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it's an empty list.</p>
-        <p>Note that lists are encoded as strings, if they consist
-          entirely of integers in the range 0..255. This function will
+          <c><![CDATA[arity]]></c>. The <c><![CDATA[arity+1]]></c> elements
+          follow (the last one is the tail of the list, normally an empty list).
+          If <c><![CDATA[arity]]></c> is <c><![CDATA[0]]></c>, it is an empty
+          list.</p>
+        <p>Notice that lists are encoded as strings if they consist
+          entirely of integers in the range 0..255. This function do
           not decode such strings, use <c><![CDATA[ei_decode_string()]]></c>
           instead.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name>
       <fsummary>Decode integer.</fsummary>
       <desc>
-        <p>This function decodes a long integer from the binary format.
-          Note that if the code is 64 bits the function ei_decode_long() is
-          exactly the same as ei_decode_longlong().</p>
+        <p>Decodes a long integer from the binary format.
+          If the code is 64 bits, the function <c>ei_decode_long()</c> is
+          the same as <c>ei_decode_longlong()</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name>
       <fsummary>Decode integer.</fsummary>
       <desc>
-        <p>This function decodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c>
-          (64 bit) integer from the binary format.  Note that this
+        <p>Decodes a GCC <c><![CDATA[long long]]></c> or Visual C++
+          <c><![CDATA[__int64]]></c>
+          (64-bit) integer from the binary format. This
           function is missing in the VxWorks port.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name>
       <fsummary>Decode a map.</fsummary>
       <desc>
-        <p>This function decodes a map header from the binary
+        <p>Decodes a map header from the binary
           format. The number of key-value pairs is returned in
-          <c>*arity</c>. Keys and values follow in the following order:
+          <c>*arity</c>. Keys and values follow in this order:
 	  <c>K1, V1, K2, V2, ..., Kn, Vn</c>. This makes a total of
-	  <c>arity*2</c> terms. If <c>arity</c> is zero, it's an empty map.
+	  <c>arity*2</c> terms. If <c>arity</c> is zero, it is an empty map.
 	  A correctly encoded map does not have duplicate keys.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name>
       <fsummary>Decode a <c><![CDATA[pid]]></c>.</fsummary>
       <desc>
-        <p>Decodes a pid, process identifier, from the binary format.</p>
+        <p>Decodes a process identifier (pid) from the binary format.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name>
       <fsummary>Decode a port.</fsummary>
       <desc>
-        <p>This function decodes a port identifier from the binary
-          format.</p>
+        <p>Decodes a port identifier from the binary format.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name>
       <fsummary>Decode a reference.</fsummary>
       <desc>
-        <p>This function decodes a reference from the binary format.</p>
+        <p>Decodes a reference from the binary format.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name>
       <fsummary>Decode a string.</fsummary>
       <desc>
-        <p>This function decodes a string from the binary format. A
-          string in erlang is a list of integers between 0 and
-          255. Note that since the string is just a list, sometimes
+        <p>Decodes a string from the binary format. A
+          string in Erlang is a list of integers between 0 and
+          255. Notice that as the string is just a list, sometimes
           lists are encoded as strings by <c><![CDATA[term_to_binary/1]]></c>,
           even if it was not intended.</p>
-        <p>The string is copied to <c><![CDATA[p]]></c>, and enough space must be
-          allocated. The returned string is null terminated so you
-          need to add an extra byte to the memory requirement.</p>
+        <p>The string is copied to <c><![CDATA[p]]></c>, and enough space must
+          be allocated. The returned string is <c>NULL</c>-terminated, so you
+          must add an extra byte to the memory requirement.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name>
       <fsummary>Decode a <c><![CDATA[ETERM]]></c>.</fsummary>
       <desc>
-        <p>This function decodes a term from the binary format. The
-          term is return in <c><![CDATA[t]]></c> as a <c><![CDATA[ETERM*]]></c>, so <c><![CDATA[t]]></c>
-          is actually an <c><![CDATA[ETERM**]]></c> (see
-          <c><![CDATA[erl_interface(3)]]></c>. The term should later be
-          deallocated.</p>
-        <p>Note that this function is located in the erl_interface
+        <p>Decodes a term from the binary format. The term
+          is return in <c><![CDATA[t]]></c> as a <c><![CDATA[ETERM*]]></c>, so
+          <c><![CDATA[t]]></c> is actually an <c><![CDATA[ETERM**]]></c> (see
+          <seealso marker="erl_eterm"><c>erl_eterm</c></seealso>).
+          The term is later to be deallocated.</p>
+        <p>Notice that this function is located in the <c>Erl_Interface</c>
           library.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name>
       <fsummary>Decode a trace token.</fsummary>
       <desc>
-        <p>Decodes an erlang trace token from the binary format.</p>
+        <p>Decodes an Erlang trace token from the binary format.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name>
       <fsummary>Decode a tuple.</fsummary>
       <desc>
-        <p>This function decodes a tuple header, the number of elements
-          is returned in <c><![CDATA[arity]]></c>. The tuple elements follows in order in
-          the buffer.</p>
+        <p>Decodes a tuple header, the number of elements
+          is returned in <c><![CDATA[arity]]></c>. The tuple elements follow
+          in order in the buffer.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name>
       <fsummary>Decode unsigned integer.</fsummary>
       <desc>
-        <p>This function decodes an unsigned long integer from
-          the binary format.
-          Note that if the code is 64 bits the function ei_decode_ulong() is
-          exactly the same as ei_decode_ulonglong().</p>
+        <p>Decodes an unsigned long integer from the binary format.
+          If the code is 64 bits, the function <c>ei_decode_ulong()</c> is
+          the same as <c>ei_decode_ulonglong()</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name>
       <fsummary>Decode unsigned integer.</fsummary>
       <desc>
-        <p>This function decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++
-          <c><![CDATA[unsigned __int64]]></c> (64 bit) integer from the binary format.
-          Note that this function is missing in the VxWorks port.</p>
+        <p>Decodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++
+          <c><![CDATA[unsigned __int64]]></c> (64-bit) integer from the binary
+          format. This function is missing in the VxWorks port.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name>
-      <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>).</fsummary>
+      <fsummary>Decode an empty list (<c><![CDATA[nil]]></c>).</fsummary>
       <desc>
-        <p>This function decodes the version magic number for the
-          erlang binary term format. It must be the first token in a
+        <p>Decodes the version magic number for the
+          Erlang binary term format. It must be the first token in a
           binary term.</p>
       </desc>
     </func>
@@ -366,12 +406,14 @@ typedef enum {
       <name><ret>int</ret><nametext>ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</nametext></name>
       <fsummary>Encode an atom.</fsummary>
       <desc>
-        <p>Encodes an atom in the binary format. The <c><![CDATA[p]]></c> parameter
-          is the name of the atom in latin1 encoding. Only upto <c>MAXATOMLEN-1</c> bytes
-          are encoded. The name should be zero-terminated, except for
+        <p>Encodes an atom in the binary format. Parameter <c><![CDATA[p]]></c>
+          is the name of the atom in Latin-1 encoding. Only up to
+          <c>MAXATOMLEN-1</c> bytes
+          are encoded. The name is to be zero-terminated, except for
           the <c><![CDATA[ei_x_encode_atom_len()]]></c> function.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name>
       <name><ret>int</ret><nametext>ei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name>
@@ -380,30 +422,35 @@ typedef enum {
       <fsummary>Encode an atom.</fsummary>
       <desc>
         <p>Encodes an atom in the binary format with character encoding
-	<seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> (latin1 or utf8).
-	The <c>p</c> parameter is the name of the atom with character encoding
-	<seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso>  (ascii, latin1 or utf8).
-	The name must either be zero-terminated or a function variant with a <c>len</c>
-	parameter must be used. If <c>to_enc</c> is set to the bitwise-or'd combination
-	<c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, utf8 encoding is only used if the atom string
-	can not be represented in latin1 encoding.</p>
-	<p>The encoding will fail if <c>p</c> is not a valid string in encoding <c>from_enc</c>,
-	if the string is too long or if it can not be represented with character encoding <c>to_enc</c>.</p>
-	<p>These functions were introduced in R16 release of Erlang/OTP as part of a first step
-	to support UTF8 atoms. Atoms encoded with <c>ERLANG_UTF8</c>
-	can not be decoded by earlier releases than R16.</p>
+	  <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso>
+          (Latin-1 or UTF-8). Parameter <c>p</c> is the name of the atom with
+          character encoding
+          <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso>
+          (ASCII, Latin-1, or UTF-8). The name must either be zero-terminated or
+          a function variant with a <c>len</c> parameter must be used.
+          If <c>to_enc</c> is set to the bitwise OR'd combination
+	  <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, UTF-8 encoding is only used if the
+          atom string cannot be represented in Latin-1 encoding.</p>
+	<p>The encoding fails if <c>p</c> is an invalid string in encoding
+          <c>from_enc</c>, if the string is too long, or if it cannot be
+          represented with character encoding <c>to_enc</c>.</p>
+	<p>These functions were introduced in Erlang/OTP R16 as part of a first
+          step to support UTF-8 atoms. Atoms encoded with <c>ERLANG_UTF8</c>
+	  cannot be decoded by earlier releases than R16.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name>
       <fsummary>Encode an arbitrary precision integer.</fsummary>
       <desc>
         <p>Encodes a GMP <c><![CDATA[mpz_t]]></c> integer to binary format.
-          To use this function the ei library needs to be configured and compiled
-          to use the GMP library. </p>
+          To use this function, the <c>ei</c> library must be configured and
+          compiled to use the GMP library.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name>
@@ -413,72 +460,78 @@ typedef enum {
           <c><![CDATA[p]]></c>, of <c><![CDATA[len]]></c> bytes length.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name>
       <fsummary>Encode a boolean.</fsummary>
       <desc>
-        <p>Encodes a boolean value, as the atom <c><![CDATA[true]]></c> if p is not
-          zero or <c><![CDATA[false]]></c> if p is zero.</p>
+        <p>Encodes a boolean value as the atom <c><![CDATA[true]]></c> if
+          <c>p</c> is not zero, or <c><![CDATA[false]]></c> if <c>p</c> is
+          zero.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name>
       <fsummary>Encode an 8-bit integer between 0-255.</fsummary>
       <desc>
-        <p>Encodes a char (8-bit) as an integer between 0-255 in the binary format.
-          Note that for historical reasons the integer argument is of
-          type <c><![CDATA[char]]></c>. Your C code should consider the
-          given argument to be of type <c><![CDATA[unsigned char]]></c> even if
+        <p>Encodes a char (8-bit) as an integer between 0-255 in the binary
+          format. For historical reasons the integer argument is of
+          type <c><![CDATA[char]]></c>. Your C code is to consider the specified
+          argument to be of type <c><![CDATA[unsigned char]]></c> even if
           the C compilers and system may define <c><![CDATA[char]]></c> to be
           signed.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name>
       <fsummary>Encode a double float.</fsummary>
       <desc>
-        <p>Encodes a double-precision (64 bit) floating point number in
+        <p>Encodes a double-precision (64-bit) floating point number in
           the binary format.</p>
-      <p>
-          The function returns <c><![CDATA[-1]]></c> if the floating point number is not finite.
-      </p>
+        <p>Returns <c><![CDATA[-1]]></c> if the floating point
+          number is not finite.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name>
       <fsummary>Encode an empty list (<c><![CDATA[nil]]></c>).</fsummary>
       <desc>
-        <p>This function encodes an empty list. It's often used at the
-          tail of a list.</p>
+        <p>Encodes an empty list. It is often used at the tail of a list.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name>
       <fsummary>Encode a fun.</fsummary>
       <desc>
-        <p>Encodes a fun in the binary format. The <c><![CDATA[p]]></c> parameter
+        <p>Encodes a fun in the binary format. Parameter <c><![CDATA[p]]></c>
           points to an <c><![CDATA[erlang_fun]]></c> structure. The
           <c><![CDATA[erlang_fun]]></c> is not freed automatically, the
-          <c><![CDATA[free_fun]]></c> should be called if the fun is not needed
+          <c><![CDATA[free_fun]]></c> is to be called if the fun is not needed
           after encoding.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_list_header(char *buf, int *index, int arity)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_list_header(ei_x_buff* x, int arity)</nametext></name>
       <fsummary>Encode a list.</fsummary>
       <desc>
-        <p>This function encodes a list header, with a specified
+        <p>Encodes a list header, with a specified
           arity. The next <c><![CDATA[arity+1]]></c> terms are the elements
           (actually its <c><![CDATA[arity]]></c> cons cells) and the tail of the
           list. Lists and tuples are encoded recursively, so that a
-          list may contain another list or tuple.</p>
-        <p>E.g. to encode the list <c><![CDATA[[c, d, [e | f]]]]></c>:</p>
+          list can contain another list or tuple.</p>
+        <p>For example, to encode the list
+          <c><![CDATA[[c, d, [e | f]]]]></c>:</p>
         <pre>
 ei_encode_list_header(buf, &amp;i, 3);
 ei_encode_atom(buf, &amp;i, "c");
@@ -486,14 +539,13 @@ ei_encode_atom(buf, &amp;i, "d");
 ei_encode_list_header(buf, &amp;i, 1);
 ei_encode_atom(buf, &amp;i, "e");
 ei_encode_atom(buf, &amp;i, "f");
-ei_encode_empty_list(buf, &amp;i);
-        </pre>
+ei_encode_empty_list(buf, &amp;i);</pre>
         <note>
           <p>It may seem that there is no way to create a list without
             knowing the number of elements in advance. But indeed
-            there is a way. Note that the list <c><![CDATA[[a, b, c]]]></c> can be
-            written as <c><![CDATA[[a | [b | [c]]]]]></c>.  Using this, a list can
-            be written as conses.</p>
+            there is a way. Notice that the list <c><![CDATA[[a, b, c]]]></c>
+            can be written as <c><![CDATA[[a | [b | [c]]]]]></c>. 
+            Using this, a list can be written as conses.</p>
         </note>
         <p>To encode a list, without knowing the arity in advance:</p>
         <pre>
@@ -501,83 +553,89 @@ while (something()) {
     ei_x_encode_list_header(&amp;x, 1);
     ei_x_encode_ulong(&amp;x, i); /* just an example */
 }
-ei_x_encode_empty_list(&amp;x);
-        </pre>
+ei_x_encode_empty_list(&amp;x);</pre>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name>
       <fsummary>Encode integer.</fsummary>
       <desc>
         <p>Encodes a long integer in the binary format.
-          Note that if the code is 64 bits the function ei_encode_long() is
-          exactly the same as ei_encode_longlong().</p>
+          If the code is 64 bits, the function <c>ei_encode_long()</c> is
+          the same as <c>ei_encode_longlong()</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name>
       <fsummary>Encode integer.</fsummary>
       <desc>
-        <p>Encodes a GCC <c><![CDATA[long long]]></c> or Visual C++ <c><![CDATA[__int64]]></c> (64 bit)
-          integer in the binary format. Note that this function is missing
-          in the VxWorks port.</p>
+        <p>Encodes a GCC <c><![CDATA[long long]]></c> or Visual C++
+          <c><![CDATA[__int64]]></c> (64-bit) integer in the binary format.
+          This function is missing in the VxWorks port.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_map_header(char *buf, int *index, int arity)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_map_header(ei_x_buff* x, int arity)</nametext></name>
       <fsummary>Encode a map.</fsummary>
       <desc>
-        <p>This function encodes a map header, with a specified arity. The next
+        <p>Encodes a map header, with a specified arity. The next
 	   <c>arity*2</c> terms encoded will be the keys and values of the map
 	   encoded in the following order: <c>K1, V1, K2, V2, ..., Kn, Vn</c>.
 	</p>
-        <p>E.g. to encode the map <c>#{a => "Apple", b => "Banana"}</c>:</p>
+        <p>For example, to encode the map <c>#{a => "Apple", b =>
+          "Banana"}</c>:</p>
         <pre>
 ei_x_encode_map_header(&amp;x, 2);
 ei_x_encode_atom(&amp;x, "a");
 ei_x_encode_string(&amp;x, "Apple");
 ei_x_encode_atom(&amp;x, "b");
-ei_x_encode_string(&amp;x, "Banana");
-        </pre>
-	<p>A correctly encoded map can not have duplicate keys.</p>
+ei_x_encode_string(&amp;x, "Banana");</pre>
+	<p>A correctly encoded map cannot have duplicate keys.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name>
       <fsummary>Encode a pid.</fsummary>
       <desc>
-        <p>Encodes an erlang process identifier, pid, in the binary
-          format. The <c><![CDATA[p]]></c> parameter points to an
-          <c><![CDATA[erlang_pid]]></c> structure (which should have been obtained
-          earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p>
+        <p>Encodes an Erlang process identifier (pid) in the binary
+          format. Parameter <c><![CDATA[p]]></c> points to an
+          <c><![CDATA[erlang_pid]]></c> structure (which should have been
+          obtained earlier with <c><![CDATA[ei_decode_pid()]]></c>).</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name>
-      <fsummary>Encodes a port.</fsummary>
+      <fsummary>Encode a port.</fsummary>
       <desc>
-        <p>Encodes an erlang port in the binary format. The <c><![CDATA[p]]></c>
-          parameter points to a <c><![CDATA[erlang_port]]></c> structure (which
-          should have been obtained earlier with
-          <c><![CDATA[ei_decode_port()]]></c>.</p>
+        <p>Encodes an Erlang port in the binary format. Parameter
+          <c><![CDATA[p]]></c> points to a <c><![CDATA[erlang_port]]></c>
+          structure (which should have been obtained earlier with
+          <c><![CDATA[ei_decode_port()]]></c>).</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name>
-      <fsummary>Encodes a ref.</fsummary>
+      <fsummary>Encode a ref.</fsummary>
       <desc>
-        <p>Encodes an erlang reference in the binary format. The
-          <c><![CDATA[p]]></c> parameter points to a <c><![CDATA[erlang_ref]]></c> structure
-          (which should have been obtained earlier with
-          <c><![CDATA[ei_decode_ref()]]></c>.</p>
+        <p>Encodes an Erlang reference in the binary format. Parameter
+          <c><![CDATA[p]]></c> points to a <c><![CDATA[erlang_ref]]></c>
+          structure (which should have been obtained earlier with
+          <c><![CDATA[ei_decode_ref()]]></c>).</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name>
       <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name>
@@ -585,21 +643,22 @@ ei_x_encode_string(&amp;x, "Banana");
       <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name>
       <fsummary>Encode a string.</fsummary>
       <desc>
-        <p>Encodes a string in the binary format. (A string in erlang
+        <p>Encodes a string in the binary format. (A string in Erlang
           is a list, but is encoded as a character array in the binary
-          format.) The string should be zero-terminated, except for
+          format.) The string is to be zero-terminated, except for
           the <c><![CDATA[ei_x_encode_string_len()]]></c> function.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name>
-      <fsummary>Encode an <c><![CDATA[erl_interface]]></c>term.</fsummary>
+      <fsummary>Encode an <c><![CDATA[erl_interface]]></c> term.</fsummary>
       <desc>
-        <p>This function encodes an <c><![CDATA[ETERM]]></c>, as obtained from
-          <c><![CDATA[erl_interface]]></c>. The <c><![CDATA[t]]></c> parameter is actually an
-          <c><![CDATA[ETERM]]></c> pointer. This function doesn't free the
-          <c><![CDATA[ETERM]]></c>.</p>
+        <p>Encodes an <c><![CDATA[ETERM]]></c>, as obtained from
+          <c><![CDATA[erl_interface]]></c>. Parameter <c><![CDATA[t]]></c> is
+          actually an <c><![CDATA[ETERM]]></c> pointer. This function
+          does not free the <c><![CDATA[ETERM]]></c>.</p>
       </desc>
     </func>
     <func>
@@ -607,51 +666,54 @@ ei_x_encode_string(&amp;x, "Banana");
       <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name>
       <fsummary>Encode a trace token.</fsummary>
       <desc>
-        <p>This function encodes an erlang trace token in the binary
-          format. The <c><![CDATA[p]]></c> parameter points to a
+        <p>Encodes an Erlang trace token in the binary format.
+          Parameter <c><![CDATA[p]]></c> points to a
           <c><![CDATA[erlang_trace]]></c> structure (which should have been
-          obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>.</p>
+          obtained earlier with <c><![CDATA[ei_decode_trace()]]></c>).</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name>
       <fsummary>Encode a tuple.</fsummary>
       <desc>
-        <p>This function encodes a tuple header, with a specified
+        <p>Encodes a tuple header, with a specified
           arity. The next <c><![CDATA[arity]]></c> terms encoded will be the
           elements of the tuple. Tuples and lists are encoded
-          recursively, so that a tuple may contain another tuple or
-          list.</p>
-        <p>E.g. to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p>
+          recursively, so that a tuple can contain another tuple or list.</p>
+        <p>For example, to encode the tuple <c><![CDATA[{a, {b, {}}}]]></c>:</p>
         <pre>
 ei_encode_tuple_header(buf, &amp;i, 2);
 ei_encode_atom(buf, &amp;i, "a");
 ei_encode_tuple_header(buf, &amp;i, 2);
 ei_encode_atom(buf, &amp;i, "b");
-ei_encode_tuple_header(buf, &amp;i, 0);
-        </pre>
+ei_encode_tuple_header(buf, &amp;i, 0);</pre>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name>
       <fsummary>Encode unsigned integer.</fsummary>
       <desc>
         <p>Encodes an unsigned long integer in the binary format.
-          Note that if the code is 64 bits the function ei_encode_ulong() is
-          exactly the same as ei_encode_ulonglong().</p>
+          If the code is 64 bits, the function <c>ei_encode_ulong()</c> is
+          the same as <c>ei_encode_ulonglong()</c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name>
       <fsummary>Encode unsigned integer.</fsummary>
       <desc>
-        <p>Encodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++ <c><![CDATA[unsigned __int64]]></c> (64 bit) integer in the binary format.  Note that
-          this function is missing in the VxWorks port.</p>
+        <p>Encodes a GCC <c><![CDATA[unsigned long long]]></c> or Visual C++
+          <c><![CDATA[unsigned __int64]]></c> (64-bit) integer in the binary
+          format. This function is missing in the VxWorks port.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name>
@@ -661,43 +723,47 @@ ei_encode_tuple_header(buf, &amp;i, 0);
           be the first token in a binary term.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name>
       <fsummary>Fetch the type and size of an encoded term.</fsummary>
       <desc>
-        <p>This function returns the type in <c><![CDATA[type]]></c> and size in
-          <c><![CDATA[size]]></c> of the encoded term.
-          For strings and atoms, size
-          is the number of characters <em>not</em> including the
+        <p>Returns the type in <c><![CDATA[type]]></c> and size in
+          <c><![CDATA[size]]></c> of the encoded term. For strings and atoms,
+          size is the number of characters <em>not</em> including the
           terminating 0. For binaries, <c><![CDATA[size]]></c> is the number of
-          bytes. For lists and tuples, <c><![CDATA[size]]></c> is the arity of the
-          object. For other types, <c><![CDATA[size]]></c> is 0. In all cases,
-          <c><![CDATA[index]]></c> is left unchanged.</p>
+          bytes. For lists and tuples, <c><![CDATA[size]]></c> is the arity of
+          the object. For other types, <c><![CDATA[size]]></c> is 0. In all
+          cases, <c><![CDATA[index]]></c> is left unchanged.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name>
       <name><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name>
       <fsummary>Print a term in clear text.</fsummary>
       <desc>
-        <p>This function prints a term, in clear text, to the file
-          given by <c><![CDATA[fp]]></c>, or the buffer pointed to by <c><![CDATA[s]]></c>. It
-          tries to resemble the term printing in the erlang shell.</p>
-        <p>In <c><![CDATA[ei_s_print_term()]]></c>, the parameter <c><![CDATA[s]]></c> should
+        <p>Prints a term, in clear text, to the file
+          specified by <c><![CDATA[fp]]></c>, or the buffer pointed to by
+          <c><![CDATA[s]]></c>. It
+          tries to resemble the term printing in the Erlang shell.</p>
+        <p>In <c><![CDATA[ei_s_print_term()]]></c>, parameter
+          <c><![CDATA[s]]></c> is to
           point to a dynamically (malloc) allocated string of
-          <c><![CDATA[BUFSIZ]]></c> bytes or a NULL pointer. The string may be
-          reallocated (and <c><![CDATA[*s]]></c> may be updated) by this function
-          if the result is more than <c><![CDATA[BUFSIZ]]></c> characters. The
-          string returned is zero-terminated.</p>
-        <p>The return value is the number of characters written to the
-          file or string, or -1 if <c><![CDATA[buf[index]]]></c> doesn't contain a
-          valid term. Unfortunately, I/O errors on <c><![CDATA[fp]]></c> is not
-          checked.</p>
-        <p>The argument <c><![CDATA[index]]></c> is updated, i.e. this function can
-          be viewed as en decode function that decodes a term into a
-          human readable format.</p>
+          <c><![CDATA[BUFSIZ]]></c> bytes or a <c>NULL</c> pointer. The string
+          can be reallocated (and <c><![CDATA[*s]]></c> can be updated) by this
+          function if the result is more than <c><![CDATA[BUFSIZ]]></c>
+          characters. The string returned is zero-terminated.</p>
+        <p>The return value is the number of characters written to the file
+          or string, or <c>-1</c> if <c><![CDATA[buf[index]]]></c> does not
+          contain a valid term.
+          Unfortunately, I/O errors on <c><![CDATA[fp]]></c> is not checked.</p>
+        <p>Argument <c><![CDATA[index]]></c> is updated, that is, this function
+          can be viewed as a decode function that decodes a term into a
+          human-readable format.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name>
       <fsummary>Set the ei library in compatibility mode.</fsummary>
@@ -708,54 +774,58 @@ ei_encode_tuple_header(buf, &amp;i, 0);
         <marker id="ei_set_compat_rel"></marker>
         <p>By default, the <c><![CDATA[ei]]></c> library is only guaranteed
           to be compatible with other Erlang/OTP components from the same
-          release as the <c><![CDATA[ei]]></c> library itself. For example, <c><![CDATA[ei]]></c> from
-          the OTP R10 release is not compatible with an Erlang emulator
-          from the OTP R9 release by default.</p>
-        <p>A call to <c><![CDATA[ei_set_compat_rel(release_number)]]></c> sets the
-          <c><![CDATA[ei]]></c> library in compatibility mode of release
-          <c><![CDATA[release_number]]></c>. Valid range of <c><![CDATA[release_number]]></c>
-          is [7, current release]. This makes it possible to
+          release as the <c><![CDATA[ei]]></c> library itself. For example,
+          <c><![CDATA[ei]]></c> from
+          Erlang/OTP R10 is not compatible with an Erlang emulator
+          from Erlang/OTP R9 by default.</p>
+        <p>A call to <c><![CDATA[ei_set_compat_rel(release_number)]]></c> sets
+          the <c><![CDATA[ei]]></c> library in compatibility mode of release
+          <c><![CDATA[release_number]]></c>. Valid range of
+          <c><![CDATA[release_number]]></c>
+          is <c>[7, current release]</c>. This makes it possible to
           communicate with Erlang/OTP components from earlier releases.</p>
         <note>
-          <p>If this function is called, it may only be called once
-            and must be called before any other functions in the <c><![CDATA[ei]]></c>
-            library is called.</p>
+          <p>If this function is called, it can only be called once
+            and must be called before any other functions in the
+            <c><![CDATA[ei]]></c> library are called.</p>
         </note>
         <warning>
-          <p>You may run into trouble if this feature is used
-            carelessly. Always make sure that all communicating
+          <p>You can run into trouble if this feature is used
+            carelessly. Always ensure that all communicating
             components are either from the same Erlang/OTP release, or
             from release X and release Y where all components
             from release Y are in compatibility mode of release X.</p>
         </warning>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name>
-      <fsummary>skip a term.</fsummary>
+      <fsummary>Skip a term.</fsummary>
       <desc>
-        <p>This function skips a term in the given buffer, it
+        <p>Skips a term in the specified buffer;
           recursively skips elements of lists and tuples, so that a
           full term is skipped. This is a way to get the size of an
-          erlang term.</p>
+          Erlang term.</p>
         <p><c><![CDATA[buf]]></c> is the buffer.</p>
-        <p><c><![CDATA[index]]></c> is updated to point right after the term in the
-          buffer.</p>
+        <p><c><![CDATA[index]]></c> is updated to point right after the term
+          in the buffer.</p>
         <note>
           <p>This can be useful when you want to hold arbitrary
-            terms: just skip them and copy the binary term data to some
+            terms: skip them and copy the binary term data to some
             buffer.</p>
         </note>
-        <p>The function returns <c><![CDATA[0]]></c> on success and <c><![CDATA[-1]]></c> on
-          failure.</p>
+        <p>Returns <c><![CDATA[0]]></c> on success, otherwise
+          <c><![CDATA[-1]]></c>.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name>
-      <fsummary>Appends a buffer at the end.</fsummary>
+      <fsummary>Append a buffer at the end.</fsummary>
       <desc>
-        <p>These functions appends data at the end of the buffer <c><![CDATA[x]]></c>.</p>
+        <p>Appends data at the end of buffer <c><![CDATA[x]]></c>.</p>
       </desc>
     </func>
 
@@ -764,69 +834,69 @@ ei_encode_tuple_header(buf, &amp;i, 0);
       <name><ret>int</ret><nametext>ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</nametext></name>
       <fsummary>Format a term from a format string and parameters.</fsummary>
       <desc>
-        <p>Format a term, given as a string, to a buffer. This
-          functions works like a sprintf for erlang terms. The
+        <p>Formats a term, given as a string, to a buffer.
+          Works like a sprintf for Erlang terms.
           <c><![CDATA[fmt]]></c> contains a format string, with arguments like
           <c><![CDATA[~d]]></c>, to insert terms from variables. The following
           formats are supported (with the C types given):</p>
-        <p></p>
         <pre>
-~a - an atom, char*
-~c - a character, char
-~s - a string, char*
-~i - an integer, int
-~l - a long integer, long int
-~u - a unsigned long integer, unsigned long int
-~f - a float, float
-~d - a double float, double float
-~p - an Erlang PID, erlang_pid*
-        </pre>
-        <p>For instance, to encode a tuple with some stuff:</p>
+~a  An atom, char*
+~c  A character, char
+~s  A string, char*
+~i  An integer, int
+~l  A long integer, long int
+~u  A unsigned long integer, unsigned long int
+~f  A float, float
+~d  A double float, double float
+~p  An Erlang pid, erlang_pid*</pre>
+        <p>For example, to encode a tuple with some stuff:</p>
         <pre>
 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
-encodes the tuple {numbers,12,3.14159}
-        </pre>
-        <p>The <c><![CDATA[ei_x_format_wo_ver()]]></c> formats into a buffer, without
-          the initial version byte.</p>
+encodes the tuple {numbers,12,3.14159}</pre>
+        <p><c><![CDATA[ei_x_format_wo_ver()]]></c> formats into a buffer,
+          without the initial version byte.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name>
-      <fsummary>Frees a buffer.</fsummary>
+      <fsummary>Free a buffer.</fsummary>
       <desc>
-        <p>This function frees an <c><![CDATA[ei_x_buff]]></c> buffer. The memory
-          used by the buffer is returned to the OS.</p>
+        <p>Frees an <c><![CDATA[ei_x_buff]]></c> buffer.
+          The memory used by the buffer is returned to the OS.</p>
       </desc>
     </func>
+
     <func>
       <name><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name>
       <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name>
       <fsummary>Allocate a new buffer.</fsummary>
       <desc>
-        <p>This function allocates a new <c><![CDATA[ei_x_buff]]></c> buffer. The
-          fields of the structure pointed to by <c><![CDATA[x]]></c> parameter is
-          filled in, and a default buffer is allocated. The
-          <c><![CDATA[ei_x_new_with_version()]]></c> also puts an initial version
-          byte, that is used in the binary format. (So that
-          <c><![CDATA[ei_x_encode_version()]]></c> won't be needed.)</p>
+        <p>Allocates a new <c><![CDATA[ei_x_buff]]></c> buffer. The
+          fields of the structure pointed to by parameter <c><![CDATA[x]]></c>
+          is filled in, and a default buffer is allocated.
+          <c><![CDATA[ei_x_new_with_version()]]></c> also puts an initial
+          version byte, which is used in the binary format (so that
+          <c><![CDATA[ei_x_encode_version()]]></c> will not be needed.)</p>
       </desc>
     </func>
- </funcs>
+  </funcs>
 
   <section>
     <title>Debug Information</title>
-    <p>Some tips on what to check when the emulator doesn't seem to
-      receive the terms that you send.</p>
+    <p>Some tips on what to check when the emulator does not seem to
+      receive the terms that you send:</p>
+
     <list type="bulleted">
-      <item>be careful with the version header, use
-      <c><![CDATA[ei_x_new_with_version()]]></c> when appropriate</item>
-      <item>turn on distribution tracing on the erlang node</item>
-      <item>check the result codes from ei_decode_-calls</item>
+      <item>Be careful with the version header, use
+        <c><![CDATA[ei_x_new_with_version()]]></c> when appropriate.</item>
+      <item>Turn on distribution tracing on the Erlang node.</item>
+      <item>Check the result codes from <c>ei_decode_-calls</c>.</item>
     </list>
   </section>
 
   <section>
     <title>See Also</title>
-    <p>erl_interface(3)</p>
+    <p><seealso marker="erl_eterm"><c>erl_eterm</c></seealso></p>
   </section>
 </cref>