minor edits

docs/source/eli5-etf.rst

@@ -19,17 +19,20 @@ The main requirements to the format:
 
 To encode a term see ``erlang:term_to_binary`` and the opposite operation is
 ``erlang:binary_to_term``.
-Decoding handcrafted binary also allows constructing terms which are
-impossible to make otherwise, like ports and pids.
+
+Decoding a crafted binary allows us to construct terms which are impossible to
+make with standard library functions, such as non-existing ports and pids.
 
 Usually atoms are encoded as strings.
-In distributed mode over the network, to further reduce the protocol size,
-a distribution header can be added.
-It contains table of atom names which are included in the encoded message.
-Then atoms in the message are replaced with indexes in this table.
+But in the distributed mode (over the network) to further reduce the protocol
+size a distribution header can be added.
+It contains a table of atom names which are included in the encoded message.
+Atoms in the message are placed in this table and their occurences are replaced
+with indexes.
 
 It is impossible to encode internal VM value types which never appear in
-Erlang programs, such as ``THE_NON_VALUE``, references to registers, CP etc.
+Erlang programs, such as ``THE_NON_VALUE``, references to registers, CP
+(continuation pointer) etc.
 
 .. seealso::
     `External Term Format <http://erlang.org/doc/apps/erts/erl_ext_dist.html>`_

docs/source/eli5-tracing.rst

@@ -10,10 +10,9 @@ A call to ``dbg:tracer()`` starts a process which will receive this stream.
 You can create your own tracer with its own state and feed events to it.
 
 Tracing is able to produce overwhelming amount of irrelevant data.
-To limit this data a trace filter is applied with ``dbg:tp/4`` (and similar)
-caller.
+To limit this data a trace filter is applied with ``dbg:tp/4`` (and similar).
 
-When everything is prepared: a tracer and a filter, it is time to open the
+When everything is prepared: a tracer and a filter, it is time to open the2
 valve. A call to ``dbg:p/2`` (and similar) sets the trace target (a process,
 a port, spawn and exit events, everything, and so on).
 It will start sending everything that matches trace target and the filter
@@ -35,5 +34,8 @@ Each entry in this new table is a simple call to ``erts_bif_trace`` with a
 function name and arguments.
 This function performs the real call and sends trace messages.
 
-At certain moments another trick is used. Special BEAM opcode is pushed onto
-stack before BIF is finished, which will send trace event.
+At certain moments, when we want to trace a BIF trapping and returning to
+execution later, another trick is used.
+Address to a special BEAM opcode is pushed onto the stack before the BIF is
+finished. This allows to catch up when trap continues execution and will send
+the trace event correctly when the BIF was finished.

docs/source/indepth-beam-file.rst

@@ -185,12 +185,12 @@ Parse the value ``tag``:
 *   If the base tag was Extended=7, the byte>>4 + 7 will become extended tag:
     Float=8, List=9, FloatReg=10, AllocList=11, Literal=12.
 
-`Github read signed word <https://github.com/kvakvs/gluonvm1/blob/master/emulator/src/beam_loader.cpp#L513-L533>`_
+`Github example of reading signed word <https://github.com/kvakvs/gluonvm1/blob/master/emulator/src/beam_loader.cpp#L513-L533>`_
 routine used to read signed words later:
 
 .. _beam-parse-smallint:
 
-`Github parse small integer <https://github.com/kvakvs/gluonvm1/blob/master/emulator/src/beam_loader.cpp#L535-L555>`_:
+`Github example of parsing a small integer <https://github.com/kvakvs/gluonvm1/blob/master/emulator/src/beam_loader.cpp#L535-L555>`_:
 (used to read SmallInt values later).
 
 *   Look into the first byte read, bit #3:
@@ -215,9 +215,12 @@ Now how to parse an encoded term:
     *   Tag=Label: use as label index, or 0 means invalid value.
     *   Tag=XRegister, Tag=YRegister: use as register index.
     *   Tag=Character (an Unicode symbol): use val as unsigned.
-    *   Tag=Extended List: create tuple of size smallint. For smallint/2 do: parse
-        a term (``case of`` value), parse a small int (label index), place them
-        into the tuple.
+    *   Tag=Extended List: contains pairs of terms.
+        Read smallint=``Size``. Create tuple of ``Size``, which will contain
+        ``Size/2`` values.
+        For ``Size/2`` do:
+        read and parse a term (``case of`` value),
+        read a small int (label index), place them into the tuple.
 
 .. _beam-code-format:
 
@@ -231,7 +234,9 @@ To read an encoded term see :ref:`BEAM Term format <beam-term-format>`.
     Opcode is converted into a label address (for threaded interpreter) or
     a pointer to handler function.
 *   Query opcode table and get arity for this opcode.
-*   Until ``arity``: parse term and put it into the output
+*   Until ``arity``: parse term and put it into the output one term or word at
+    a time. VM loop will read the opcode later and expect that ``arity``
+    args will follow it.
 *   If any of the parsed terms was a label value, remember its output position
     to later revisit it and overwrite with actual label address in memory
     (it is not known until code parsing is done).