Copy-edit the spec, part 3

protocol/specification/descriptive.rst

@@ -72,6 +72,8 @@ Optional SEC Node Properties
      *see* :issue:`004 The Timeout SEC Node Property`.
 
 
+.. _module-description:
+
 Module Description
 ------------------
 

protocol/specification/future.rst

@@ -1,66 +1,79 @@
 .. _future-compatibility:
 
-Future Compatibility - notes for implementors
-=============================================
+Future Compatibility
+====================
 
-notes for implementors of current specification
------------------------------------------------
+Notes for implementors of the current specification
+---------------------------------------------------
 
-# As JSON can not handle non-numerical quantities like 'Inf' or 'NaN',
-  either an appropriate error message should be generated, or the closest representable
+* As JSON can not handle non-numerical quantities like 'Inf' or 'NaN', either an
+  appropriate error message should be generated, or the closest representable
   numerical value (+/- double_max?) should be used.
 
-# all values transferred between ECS and SEC node should be validated on both sides.
-  This may be relaxed in future specifications.
-  Errors, which arise from the validation of SEC node values on the ECS-side should not crash the ECS
-  and should inform the user about this violation of specification along with the data, the validator and why validation failed.
+* All values transferred between ECS and SEC node should be validated on both
+  sides.  This may be relaxed in future specifications.  Errors, which arise
+  from the validation of SEC node values on the ECS-side should not crash the
+  ECS and should inform the user about this violation of specification along
+  with the data, the validator and why validation failed.
+
 
 Foreseen extension mechanisms
 -----------------------------
 
-The herein specified protocol has foreseen some extension mechanisms in its design:
+The herein specified protocol has foreseen some extension mechanisms in its
+design:
+
+* Add messages, keeping the 'triple' structure of message/specifier/data.
 
-* add actions, keeping the 'triple' structure of action/specifier/data
+  .. note:: That is why custom messages MUST be prefixed with an underscore.
 
-  :Note:
-      That is why custom actions MUST be prefixed with an underscore.
+* Extend specifiers with ':' separated identifiers, getting more and more
+  specific.
 
-* extent specifier with ':' separated identifiers, getting more and more specific
+  An empty string as specifier addresses the SEC node, ``<module>`` addresses a
+  module, and ``<module>:<accessible>`` addresses an accessible of a module.
 
-  An empty string as specifier addresses the SEC node, ``<module>`` addresses a module,
-  and ``<module>:<accessible>`` addresses an accessible of a module.
+  If there will ever be such things as node-accessibles, they will be addressed
+  as ``:<accessible>``.  Also properties may be addressed like
+  ``<module>:<accessible>:<property>``.
 
-  If there will ever be such things as node-accessibles, they will be addressed as ``:<accessible>``.
-  Also properties may be addressed like ``<module>:<accessible>:<property>``.
+  In the same sense as an empty string selects the whole SEC node, ``<module>:``
+  may at some point select ALL parameters of a module.
 
-  In the same sense as an empty string selects the whole SEC node, ``<module>:`` may select ALL parameters of a module.
+* Define additional parameter/command/property names.
 
-* define additional parameter/command/property names
+  .. note:: That is why custom parameters, commands and properties MUST be
+            prefixed with an underscore.
 
-* extend reports (only append to them, never changing the already defined fields)
+* Extend reports (only append to them, never changing the already defined
+  fields).
 
-  :Note:
-      The structure report may need to be nested inside a JSON-array in the future, should we need to extend that.
+  The structure report may need to be nested inside a JSON array in the future,
+  should we need to extend that.
 
-* use so far unused datafields (there are not so many).
+* Use so far unused data fields (there are not so many).
 
-* define additional status groups or statuscodes
+* Define additional status groups or statuscodes.
 
-* define additional interface classes
+* Define additional interface classes.
+
+* Define additional features, listed in an additional property.
 
-* define additional features, being listed in an additional property
 
 Message Handling
 ----------------
 
 For this, see :ref:`message-overview`.
 
+
 Binary representations of the protocol
 --------------------------------------
 
-so far only the above described, textual protocol is defined.
-Since this is not optimal for bandwidth limited connections (e.g. RS232), a shorter, binary representation
-may be developed. This will essentially keep the structure of the messages, but replace the components
-of a message with shorter, binary representations.
+So far only the above described, textual protocol is defined.  Since this is not
+optimal for bandwidth limited connections (e.g. RS232), a shorter, binary
+representation may be developed.  This will essentially keep the structure of
+the messages, but replace the components of a message with shorter, binary
+representations.
 
-Good candidates for this are CBOR (see :RFC:`7049`) and MessagePack (see https://msgpack.org/).
+Good candidates for this are CBOR (see :RFC:`7049`) and MessagePack (see
+https://msgpack.org/).

protocol/specification/messages.rst

@@ -295,19 +295,19 @@ first element, and an JSON object containing the :ref:`qualifiers` as its second
 element.
 
 If an error occurs while determining a parameter, an ``error_update`` message
-has to be sent, which includes an <:ref:`error-report`> stating the problem.
+has to be sent, which includes an :ref:`prop-error-report` stating the problem.
 
 Example:
 
 .. code::
 
-  > activate
-  < update t1:value [295.13,{"t":150539648.188388,"e":0.01}]
-  < update t1:status [[400,"heater broken or disconnected"],{"t":1505396348.288388}]
-  < active
-  < error_update t1:_heaterpower ["HardwareError","heater broken or disconnected",{"t":1505396349.20}]
-  < update t1:value [295.14,{"t":1505396349.259845,"e":0.01}]
-  < update t1:value [295.13,{"t":1505396350.324752,"e":0.01}]
+    > activate
+    < update t1:value [295.13,{"t":150539648.188388,"e":0.01}]
+    < update t1:status [[400,"heater broken or disconnected"],{"t":1505396348.288388}]
+    < active
+    < error_update t1:_heaterpower ["HardwareError","heater broken or disconnected",{"t":1505396349.20}]
+    < update t1:value [295.14,{"t":1505396349.259845,"e":0.01}]
+    < update t1:value [295.13,{"t":1505396350.324752,"e":0.01}]
 
 The example shows an ``activate`` request triggering an initial update of two
 values: ``t1:value`` and ``t1:status``, followed by the ``active`` reply.  Also,
@@ -526,9 +526,9 @@ Error Reply
 ~~~~~~~~~~~
 
 Contains an error class from the list below as its second item (the specifier).
-The third item of the message is an :ref:`error-report`, containing the request
-message (minus line endings) as a string in its first element, a (short) human
-readable text as its second element.  The third element is a JSON object,
+The third item of the message is an :ref:`prop-error-report`, containing the
+request message (minus line endings) as a string in its first element, a (short)
+human readable text as its second element.  The third element is a JSON object,
 containing possibly implementation specific information about the error (stack
 dump etc.).
 
@@ -674,7 +674,7 @@ Logging is an optional message, i.e. a SEC node is not forced to implement it.
     "debug"
         All log messages are logged remotely.
 
-    A SEC node should reply with an :ref:`error-report` (``ProtocolError``) if
+    A SEC node should reply with an :ref:`prop-error-report` (``ProtocolError``) if
     it doesn't implement this message.  Otherwise it should mirror the request,
     which may be updated with the logging-level actually in use.  I.e. if an SEC
     node does not implement the "debug" level, but "error" and "info" and an ECS
@@ -743,8 +743,8 @@ Example:
 
 .. code::
 
-  > ping 123
-  < pong 123 [null, {"t": 1505396348.543}]
+    > ping 123
+    < pong 123 [null, {"t": 1505396348.543}]
 
 .. admonition:: Related Issues
 
@@ -798,15 +798,15 @@ correctly.
 
 Similarly, the reports need to be handled like this:
 
-.. _`data-report`:
+.. _data-report:
 
 .. compound::
     Data report:
 
     .. image:: images/data-report.svg
        :alt: data_report ::= "[" JSON-value "," qualifiers ("," ignored_value)* "]"
 
-.. _`error-report`:
+.. _error-report:
 
 .. compound::
     Error report: