Fix cross-references

Author: birkenfeld

protocol/specification/classes.rst

@@ -13,9 +13,9 @@ but earlier definitions will stay intact, i.e. no removals or redefinitions will
 occur.
 
 The module class is in fact a list of classes (highest level class first) and is
-stored in the module-property `interface_classes`.  The ECS chooses the first
-class from the list which is known to it.  The last one in the list must be one
-of the base classes listed below.
+stored in the module-property `interface_classes <mod.interface_classes>`.  The
+ECS chooses the first class from the list which is known to it.  The last one in
+the list must be one of the base classes listed below.
 
 .. admonition:: Remark
 
@@ -46,7 +46,7 @@ Base classes
     It must have a `target` parameter in addition to what a `Readable` has.
     It does not have a `stop` command. A module which needs time to reach
     the target but cannot be stopped has also to be represented as a `Writable`,
-    with a `BUSY` item (code 300...389) in the status enum.
+    with a ``BUSY`` item (code 300...389) in the status enum.
 
 .. baseclass:: Drivable
 

protocol/specification/descriptive.rst

@@ -501,6 +501,6 @@ description.
 
 As for all custom extensions, their names must be prefixed with an underscore.
 The meaning of custom properties depends on the implementor, given by the
-`implementor` module property.  An ECS that doesn't know the meaning of a
-custom property MUST ignore it.  The data type of a custom property is not
-pre-defined, an ECS should be prepared to handle anything here.
+`implementor <mod.implementor>` module property.  An ECS that doesn't know the
+meaning of a custom property MUST ignore it.  The data type of a custom property
+is not pre-defined, an ECS should be prepared to handle anything here.

protocol/specification/messages.rst

@@ -43,7 +43,7 @@ The ``<`` or ``>`` marks whether messages are sent to or received from the node.
  Message intent          Kind           Message structure
 ======================= ============== ==================
  Identification          request        `*IDN?`
-      \                  reply          `ISSE&SINE2020,SECoP,revision,version`
+      \                  reply          `ISSE,SECoP,revision,version <ISSE,SECoP,<revision>,<version>>`
  Description             request        `describe`
       \                  reply          `describing . structure-report <describing>`
  Activate updates        request        `activate`
@@ -59,7 +59,7 @@ The ``<`` or ``>`` marks whether messages are sent to or received from the node.
  Execute command         request        `do mod:cmd value <do>`
       \                  reply          `done mod:cmd data-report <done>`
  Value update event      event          `update mod:param data-report <update>`
- Error reply             reply          `error_action specifier error-report <error>`
+ Error reply             reply          `error_action specifier error-report <error_*>`
  Checking (\*)           request        `check mod:param value <check>`
       \                  reply          `checked mod:param data-report <checked>`
  Logging (\*)            request        `logging mod level <logging>`

protocol/specification/messages/activation.rst

@@ -28,6 +28,7 @@
 
 .. message:: [request] deactivate [<module>]
              [reply] inactive [<module>]
+             [reply] error_deactivate [<module>] <error-report>
 
     A parameterless message.  After the "inactive" reply no more updates are
     delivered if not triggered by a read message.

protocol/specification/messages/commands.rst

@@ -17,7 +17,7 @@
     conform to the declared datatypes from the datatype of the command argument.
 
     A command may have a return value, which may also be structured.  The "done"
-    reply always contains a `data-report` with the return value.  If no value is
+    reply always contains a :ref:`data-report` with the return value.  If no value is
     returned, the data part is set to "null".  The "done" message should be returned
     quickly, the time scale should be in the order of the time needed for
     communications.  Still, all side-effects need to be realized and communicated

protocol/specification/messages/errors.rst

@@ -3,23 +3,28 @@
 ``error_*``: Error replies
 --------------------------
 
-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,
-containing possibly implementation specific information about the error (stack
-dump etc.).
+.. message:: [reply] error_* <specifier> <error-report>
 
-Example:
+    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, containing possibly implementation specific
+    information about the error (stack dump etc.).
+
+Examples:
 
 .. code::
 
     > read tx:target
     < error_read tx:target ["NoSuchModule","tx is not configured on this SEC node", {}]
+
     > change ts:target 12
     < error_change ts:target ["NoSuchParameter","ts has no parameter target", {}]
+
     > change t:target -9
     < error_change t:target ["BadValue","requested value (-9) is outside limits (0..300)", {}]
+
     > meas:volt?
     < error_meas:volt?  ["ProtocolError","unknown action", {}]
 

protocol/specification/messages/heartbeat.rst

@@ -9,7 +9,7 @@
     a space and should be short and not be re-used.  It may be omitted.  The reply
     will contain exactly the same id.
 
-    A SEC node replies with a `pong` message with a `data-report` of a null value.
+    A SEC node replies with a `pong` message with a :ref:`data-report` of a null value.
     The :ref:`qualifiers` part SHOULD only contain the timestamp (as member "t") if
     the SEC node supports timestamping.  This can be used to synchronize the time
     between ECS and SEC node.

protocol/specification/messages/optional.rst

@@ -17,8 +17,8 @@ and should reply with a `ProtocolError` error to indicate this.
     command.  This check goes beyond a simple validity check based on the
     accessible's datainfo and may depend on the current configuration of the
     entire SEC node.  Upon successful completion of the check, a `checked`
-    response is sent, containing a `data-report` of the verified value.  The
-    accessible property `checkable` indicates whether an accessible can be
+    response is sent, containing a :ref:`data-report` of the verified value.
+    The accessible property `checkable` indicates whether an accessible can be
     checked.
 
     .. admonition:: Remarks

protocol/specification/messages/readwrite.rst

@@ -32,7 +32,7 @@ Example:
     value to be set.  The value is JSON formatted.  As soon as the set-value is read
     back from the hardware, all clients, having activated the parameter/module in
     question, get an "update" message.  After all side-effects are communicated, a
-    "changed" reply is then send, containing a `data-report` of the read-back value.
+    "changed" reply is then send, containing a :ref:`data-report` of the read-back value.
 
     .. admonition:: Remarks
 

protocol/specification/messages/update.rst

@@ -5,7 +5,7 @@
              [event] error_update <module>:<parameter> <error-report>
 
     When activated, update messages are delivered without explicit request from the
-    client.  The value is a `data-report`, i.e. a JSON array with the value as its
+    client.  The value is a :ref:`data-report`, i.e. a JSON array with the value as its
     first element, and an JSON object containing the :ref:`qualifiers` as its second
     element.