diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 5618a80..7f78183 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -545,7 +545,8 @@
  { 'command': 'migrate_recover',
    'data': { 'uri': 'str' }, 'allow-oob': true }
 
-See qmp-spec.txt for out-of-band execution syntax and semantics.
+See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
+and semantics.
 
 Commands supporting out-of-band execution can still be executed
 in-band.
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 6351ff9..ed65395 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -15,6 +15,7 @@
    dbus-display
    live-block-operations
    pr-helper
+   qmp-spec
    qemu-ga
    qemu-ga-ref
    qemu-qmp-ref
diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
deleted file mode 100644
index 1c745a7..0000000
--- a/docs/interop/qmp-intro.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-                          QEMU Machine Protocol
-                          =====================
-
-Introduction
-------------
-
-The QEMU Machine Protocol (QMP) allows applications to operate a
-QEMU instance.
-
-QMP is JSON[1] based and features the following:
-
-- Lightweight, text-based, easy to parse data format
-- Asynchronous messages support (ie. events)
-- Capabilities Negotiation
-
-For detailed information on QMP's usage, please, refer to the following files:
-
-o qmp-spec.txt      QEMU Machine Protocol current specification
-o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time)
-
-[1] https://www.json.org
-
-Usage
------
-
-You can use the -qmp option to enable QMP. For example, the following
-makes QMP available on localhost port 4444:
-
-$ qemu [...] -qmp tcp:localhost:4444,server=on,wait=off
-
-However, for more flexibility and to make use of more options, the -mon
-command-line option should be used. For instance, the following example
-creates one HMP instance (human monitor) on stdio and one QMP instance
-on localhost port 4444:
-
-$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
-             -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
-             -mon chardev=mon1,mode=control,pretty=on
-
-Please, refer to QEMU's manpage for more information.
-
-Simple Testing
---------------
-
-To manually test QMP one can connect with telnet and issue commands by hand:
-
-$ telnet localhost 4444
-Trying 127.0.0.1...
-Connected to localhost.
-Escape character is '^]'.
-{
-    "QMP": {
-        "version": {
-            "qemu": {
-                "micro": 0,
-                "minor": 0,
-                "major": 3
-            },
-            "package": "v3.0.0"
-        },
-        "capabilities": [
-            "oob"
-        ]
-    }
-}
-
-{ "execute": "qmp_capabilities" }
-{
-    "return": {
-    }
-}
-
-{ "execute": "query-status" }
-{
-    "return": {
-        "status": "prelaunch", 
-        "singlestep": false, 
-        "running": false
-    }
-}
-
-Please refer to docs/interop/qemu-qmp-ref.* for a complete command
-reference, generated from qapi/qapi-schema.json.
-
-QMP wiki page
--------------
-
-https://wiki.qemu.org/QMP
diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst
new file mode 100644
index 0000000..5633441
--- /dev/null
+++ b/docs/interop/qmp-spec.rst
@@ -0,0 +1,439 @@
+..
+    Copyright (C) 2009-2016 Red Hat, Inc.
+
+    This work is licensed under the terms of the GNU GPL, version 2 or
+    later. See the COPYING file in the top-level directory.
+
+
+===================================
+QEMU Machine Protocol Specification
+===================================
+
+The QEMU Machine Protocol (QMP) is a JSON-based
+protocol which is available for applications to operate QEMU at the
+machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
+is available for host applications to interact with the guest
+operating system. This page specifies the general format of
+the protocol; details of the commands and data structures can
+be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`.
+
+.. contents::
+
+Protocol Specification
+======================
+
+This section details the protocol format. For the purpose of this
+document, "Server" is either QEMU or the QEMU Guest Agent, and
+"Client" is any application communicating with it via QMP.
+
+JSON data structures, when mentioned in this document, are always in the
+following format:
+
+    json-DATA-STRUCTURE-NAME
+
+Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
+by the `JSON standard <http://www.ietf.org/rfc/rfc8259.txt>`_.
+
+The server expects its input to be encoded in UTF-8, and sends its
+output encoded in ASCII.
+
+For convenience, json-object members mentioned in this document will
+be in a certain order. However, in real protocol usage they can be in
+ANY order, thus no particular order should be assumed. On the other
+hand, use of json-array elements presumes that preserving order is
+important unless specifically documented otherwise.  Repeating a key
+within a json-object gives unpredictable results.
+
+Also for convenience, the server will accept an extension of
+``'single-quoted'`` strings in place of the usual ``"double-quoted"``
+json-string, and both input forms of strings understand an additional
+escape sequence of ``\'`` for a single quote. The server will only use
+double quoting on output.
+
+General Definitions
+-------------------
+
+All interactions transmitted by the Server are json-objects, always
+terminating with CRLF.
+
+All json-objects members are mandatory when not specified otherwise.
+
+Server Greeting
+---------------
+
+Right when connected the Server will issue a greeting message, which signals
+that the connection has been successfully established and that the Server is
+ready for capabilities negotiation (for more information refer to section
+`Capabilities Negotiation`_).
+
+The greeting message format is:
+
+::
+
+  { "QMP": { "version": json-object, "capabilities": json-array } }
+
+Where:
+
+- The ``version`` member contains the Server's version information (the format
+  is the same as for the query-version command).
+- The ``capabilities`` member specifies the availability of features beyond the
+  baseline specification; the order of elements in this array has no
+  particular significance.
+
+Capabilities
+------------
+
+Currently supported capabilities are:
+
+``oob``
+  the QMP server supports "out-of-band" (OOB) command
+  execution, as described in section `Out-of-band execution`_.
+
+Issuing Commands
+----------------
+
+The format for command execution is:
+
+::
+
+  { "execute": json-string, "arguments": json-object, "id": json-value }
+
+or
+
+::
+
+  { "exec-oob": json-string, "arguments": json-object, "id": json-value }
+
+Where:
+
+- The ``execute`` or ``exec-oob`` member identifies the command to be
+  executed by the server.  The latter requests out-of-band execution.
+- The ``arguments`` member is used to pass any arguments required for the
+  execution of the command, it is optional when no arguments are
+  required. Each command documents what contents will be considered
+  valid when handling the json-argument.
+- The ``id`` member is a transaction identification associated with the
+  command execution, it is optional and will be part of the response
+  if provided.  The ``id`` member can be any json-value.  A json-number
+  incremented for each successive command works fine.
+
+The actual commands are documented in the :doc:`qemu-qmp-ref`.
+
+Out-of-band execution
+---------------------
+
+The server normally reads, executes and responds to one command after
+the other.  The client therefore receives command responses in issue
+order.
+
+With out-of-band execution enabled via `capabilities negotiation`_,
+the server reads and queues commands as they arrive.  It executes
+commands from the queue one after the other.  Commands executed
+out-of-band jump the queue: the command get executed right away,
+possibly overtaking prior in-band commands.  The client may therefore
+receive such a command's response before responses from prior in-band
+commands.
+
+To be able to match responses back to their commands, the client needs
+to pass ``id`` with out-of-band commands.  Passing it with all commands
+is recommended for clients that accept capability ``oob``.
+
+If the client sends in-band commands faster than the server can
+execute them, the server will stop reading requests until the request
+queue length is reduced to an acceptable range.
+
+To ensure commands to be executed out-of-band get read and executed,
+the client should have at most eight in-band commands in flight.
+
+Only a few commands support out-of-band execution.  The ones that do
+have ``"allow-oob": true`` in the output of ``query-qmp-schema``.
+
+Commands Responses
+------------------
+
+There are two possible responses which the Server will issue as the result
+of a command execution: success or error.
+
+As long as the commands were issued with a proper ``id`` field, then the
+same ``id`` field will be attached in the corresponding response message
+so that requests and responses can match.  Clients should drop all the
+responses that have an unknown ``id`` field.
+
+Success
+-------
+
+The format of a success response is:
+
+::
+
+  { "return": json-value, "id": json-value }
+
+Where:
+
+- The ``return`` member contains the data returned by the command, which
+  is defined on a per-command basis (usually a json-object or
+  json-array of json-objects, but sometimes a json-number, json-string,
+  or json-array of json-strings); it is an empty json-object if the
+  command does not return data.
+- The ``id`` member contains the transaction identification associated
+  with the command execution if issued by the Client.
+
+Error
+-----
+
+The format of an error response is:
+
+::
+
+  { "error": { "class": json-string, "desc": json-string }, "id": json-value }
+
+Where:
+
+- The ``class`` member contains the error class name (eg. ``"GenericError"``).
+- The ``desc`` member is a human-readable error message. Clients should
+  not attempt to parse this message.
+- The ``id`` member contains the transaction identification associated with
+  the command execution if issued by the Client.
+
+NOTE: Some errors can occur before the Server is able to read the ``id`` member;
+in these cases the ``id`` member will not be part of the error response, even
+if provided by the client.
+
+Asynchronous events
+-------------------
+
+As a result of state changes, the Server may send messages unilaterally
+to the Client at any time, when not in the middle of any other
+response. They are called "asynchronous events".
+
+The format of asynchronous events is:
+
+::
+
+  { "event": json-string, "data": json-object,
+    "timestamp": { "seconds": json-number, "microseconds": json-number } }
+
+Where:
+
+- The ``event`` member contains the event's name.
+- The ``data`` member contains event specific data, which is defined in a
+  per-event basis. It is optional.
+- The ``timestamp`` member contains the exact time of when the event
+  occurred in the Server. It is a fixed json-object with time in
+  seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
+  there is a failure to retrieve host time, both members of the
+  timestamp will be set to -1.
+
+The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`.
+
+Some events are rate-limited to at most one per second.  If additional
+"similar" events arrive within one second, all but the last one are
+dropped, and the last one is delayed.  "Similar" normally means same
+event type.
+
+Forcing the JSON parser into known-good state
+---------------------------------------------
+
+Incomplete or invalid input can leave the server's JSON parser in a
+state where it can't parse additional commands.  To get it back into
+known-good state, the client should provoke a lexical error.
+
+The cleanest way to do that is sending an ASCII control character
+other than ``\t`` (horizontal tab), ``\r`` (carriage return), or
+``\n`` (new line).
+
+Sadly, older versions of QEMU can fail to flag this as an error.  If a
+client needs to deal with them, it should send a 0xFF byte.
+
+QGA Synchronization
+-------------------
+
+When a client connects to QGA over a transport lacking proper
+connection semantics such as virtio-serial, QGA may have read partial
+input from a previous client.  The client needs to force QGA's parser
+into known-good state using the previous section's technique.
+Moreover, the client may receive output a previous client didn't read.
+To help with skipping that output, QGA provides the
+``guest-sync-delimited`` command.  Refer to its documentation for
+details.
+
+
+QMP Examples
+============
+
+This section provides some examples of real QMP usage, in all of them
+``->`` marks text sent by the Client and ``<-`` marks replies by the Server.
+
+.. admonition:: Example
+
+  Server greeting
+
+  .. code-block:: QMP
+
+    <- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
+         "package": "v3.0.0"}, "capabilities": ["oob"] } }
+
+.. admonition:: Example
+
+  Capabilities negotiation
+
+  .. code-block:: QMP
+
+    -> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
+    <- { "return": {}}
+
+.. admonition:: Example
+
+  Simple 'stop' execution
+
+  .. code-block:: QMP
+
+    -> { "execute": "stop" }
+    <- { "return": {} }
+
+.. admonition:: Example
+
+  KVM information
+
+  .. code-block:: QMP
+
+    -> { "execute": "query-kvm", "id": "example" }
+    <- { "return": { "enabled": true, "present": true }, "id": "example"}
+
+.. admonition:: Example
+
+  Parsing error
+
+  .. code-block:: QMP
+
+    -> { "execute": }
+    <- { "error": { "class": "GenericError", "desc": "JSON parse error, expecting value" } }
+
+.. admonition:: Example
+
+  Powerdown event
+
+  .. code-block:: QMP
+
+    <- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
+        "event": "POWERDOWN" }
+
+.. admonition:: Example
+
+  Out-of-band execution
+
+  .. code-block:: QMP
+
+    -> { "exec-oob": "migrate-pause", "id": 42 }
+    <- { "id": 42,
+         "error": { "class": "GenericError",
+          "desc": "migrate-pause is currently only supported during postcopy-active state" } }
+
+
+Capabilities Negotiation
+========================
+
+When a Client successfully establishes a connection, the Server is in
+Capabilities Negotiation mode.
+
+In this mode only the ``qmp_capabilities`` command is allowed to run; all
+other commands will return the ``CommandNotFound`` error. Asynchronous
+messages are not delivered either.
+
+Clients should use the ``qmp_capabilities`` command to enable capabilities
+advertised in the `Server Greeting`_ which they support.
+
+When the ``qmp_capabilities`` command is issued, and if it does not return an
+error, the Server enters Command mode where capabilities changes take
+effect, all commands (except ``qmp_capabilities``) are allowed and asynchronous
+messages are delivered.
+
+Compatibility Considerations
+============================
+
+All protocol changes or new features which modify the protocol format in an
+incompatible way are disabled by default and will be advertised by the
+capabilities array (in the `Server Greeting`_). Thus, Clients can check
+that array and enable the capabilities they support.
+
+The QMP Server performs a type check on the arguments to a command.  It
+generates an error if a value does not have the expected type for its
+key, or if it does not understand a key that the Client included.  The
+strictness of the Server catches wrong assumptions of Clients about
+the Server's schema.  Clients can assume that, when such validation
+errors occur, they will be reported before the command generated any
+side effect.
+
+However, Clients must not assume any particular:
+
+- Length of json-arrays
+- Size of json-objects; in particular, future versions of QEMU may add
+  new keys and Clients should be able to ignore them
+- Order of json-object members or json-array elements
+- Amount of errors generated by a command, that is, new errors can be added
+  to any existing command in newer versions of the Server
+
+Any command or member name beginning with ``x-`` is deemed experimental,
+and may be withdrawn or changed in an incompatible manner in a future
+release.
+
+Of course, the Server does guarantee to send valid JSON.  But apart from
+this, a Client should be "conservative in what they send, and liberal in
+what they accept".
+
+Downstream extension of QMP
+===========================
+
+We recommend that downstream consumers of QEMU do *not* modify QMP.
+Management tools should be able to support both upstream and downstream
+versions of QMP without special logic, and downstream extensions are
+inherently at odds with that.
+
+However, we recognize that it is sometimes impossible for downstreams to
+avoid modifying QMP.  Both upstream and downstream need to take care to
+preserve long-term compatibility and interoperability.
+
+To help with that, QMP reserves JSON object member names beginning with
+``__`` (double underscore) for downstream use ("downstream names").  This
+means upstream will never use any downstream names for its commands,
+arguments, errors, asynchronous events, and so forth.
+
+Any new names downstream wishes to add must begin with ``__``.  To
+ensure compatibility with other downstreams, it is strongly
+recommended that you prefix your downstream names with ``__RFQDN_`` where
+RFQDN is a valid, reverse fully qualified domain name which you
+control.  For example, a qemu-kvm specific monitor command would be:
+
+::
+
+    (qemu) __org.linux-kvm_enable_irqchip
+
+Downstream must not change the `server greeting`_ other than
+to offer additional capabilities.  But see below for why even that is
+discouraged.
+
+The section `Compatibility Considerations`_ applies to downstream as well
+as to upstream, obviously.  It follows that downstream must behave
+exactly like upstream for any input not containing members with
+downstream names ("downstream members"), except it may add members
+with downstream names to its output.
+
+Thus, a client should not be able to distinguish downstream from
+upstream as long as it doesn't send input with downstream members, and
+properly ignores any downstream members in the output it receives.
+
+Advice on downstream modifications:
+
+1. Introducing new commands is okay.  If you want to extend an existing
+   command, consider introducing a new one with the new behaviour
+   instead.
+
+2. Introducing new asynchronous messages is okay.  If you want to extend
+   an existing message, consider adding a new one instead.
+
+3. Introducing new errors for use in new commands is okay.  Adding new
+   errors to existing commands counts as extension, so 1. applies.
+
+4. New capabilities are strongly discouraged.  Capabilities are for
+   evolving the basic protocol, and multiple diverging basic protocol
+   dialects are most undesirable.
diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt
deleted file mode 100644
index b0e8351..0000000
--- a/docs/interop/qmp-spec.txt
+++ /dev/null
@@ -1,406 +0,0 @@
-                      QEMU Machine Protocol Specification
-
-0. About This Document
-======================
-
-Copyright (C) 2009-2016 Red Hat, Inc.
-
-This work is licensed under the terms of the GNU GPL, version 2 or
-later. See the COPYING file in the top-level directory.
-
-1. Introduction
-===============
-
-This document specifies the QEMU Machine Protocol (QMP), a JSON-based
-protocol which is available for applications to operate QEMU at the
-machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
-is available for host applications to interact with the guest
-operating system.
-
-2. Protocol Specification
-=========================
-
-This section details the protocol format. For the purpose of this
-document, "Server" is either QEMU or the QEMU Guest Agent, and
-"Client" is any application communicating with it via QMP.
-
-JSON data structures, when mentioned in this document, are always in the
-following format:
-
-    json-DATA-STRUCTURE-NAME
-
-Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
-by the JSON standard:
-
-http://www.ietf.org/rfc/rfc8259.txt
-
-The server expects its input to be encoded in UTF-8, and sends its
-output encoded in ASCII.
-
-For convenience, json-object members mentioned in this document will
-be in a certain order. However, in real protocol usage they can be in
-ANY order, thus no particular order should be assumed. On the other
-hand, use of json-array elements presumes that preserving order is
-important unless specifically documented otherwise.  Repeating a key
-within a json-object gives unpredictable results.
-
-Also for convenience, the server will accept an extension of
-'single-quoted' strings in place of the usual "double-quoted"
-json-string, and both input forms of strings understand an additional
-escape sequence of "\'" for a single quote. The server will only use
-double quoting on output.
-
-2.1 General Definitions
------------------------
-
-2.1.1 All interactions transmitted by the Server are json-objects, always
-      terminating with CRLF
-
-2.1.2 All json-objects members are mandatory when not specified otherwise
-
-2.2 Server Greeting
--------------------
-
-Right when connected the Server will issue a greeting message, which signals
-that the connection has been successfully established and that the Server is
-ready for capabilities negotiation (for more information refer to section
-'4. Capabilities Negotiation').
-
-The greeting message format is:
-
-{ "QMP": { "version": json-object, "capabilities": json-array } }
-
- Where,
-
-- The "version" member contains the Server's version information (the format
-  is the same of the query-version command)
-- The "capabilities" member specify the availability of features beyond the
-  baseline specification; the order of elements in this array has no
-  particular significance.
-
-2.2.1 Capabilities
-------------------
-
-Currently supported capabilities are:
-
-- "oob": the QMP server supports "out-of-band" (OOB) command
-  execution, as described in section "2.3.1 Out-of-band execution".
-
-2.3 Issuing Commands
---------------------
-
-The format for command execution is:
-
-{ "execute": json-string, "arguments": json-object, "id": json-value }
-
-or
-
-{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
-
- Where,
-
-- The "execute" or "exec-oob" member identifies the command to be
-  executed by the server.  The latter requests out-of-band execution.
-- The "arguments" member is used to pass any arguments required for the
-  execution of the command, it is optional when no arguments are
-  required. Each command documents what contents will be considered
-  valid when handling the json-argument
-- The "id" member is a transaction identification associated with the
-  command execution, it is optional and will be part of the response
-  if provided.  The "id" member can be any json-value.  A json-number
-  incremented for each successive command works fine.
-
-The actual commands are documented in the QEMU QMP reference manual
-docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
-
-2.3.1 Out-of-band execution
----------------------------
-
-The server normally reads, executes and responds to one command after
-the other.  The client therefore receives command responses in issue
-order.
-
-With out-of-band execution enabled via capability negotiation (section
-4.), the server reads and queues commands as they arrive.  It executes
-commands from the queue one after the other.  Commands executed
-out-of-band jump the queue: the command get executed right away,
-possibly overtaking prior in-band commands.  The client may therefore
-receive such a command's response before responses from prior in-band
-commands.
-
-To be able to match responses back to their commands, the client needs
-to pass "id" with out-of-band commands.  Passing it with all commands
-is recommended for clients that accept capability "oob".
-
-If the client sends in-band commands faster than the server can
-execute them, the server will stop reading requests until the request
-queue length is reduced to an acceptable range.
-
-To ensure commands to be executed out-of-band get read and executed,
-the client should have at most eight in-band commands in flight.
-
-Only a few commands support out-of-band execution.  The ones that do
-have "allow-oob": true in output of query-qmp-schema.
-
-2.4 Commands Responses
-----------------------
-
-There are two possible responses which the Server will issue as the result
-of a command execution: success or error.
-
-As long as the commands were issued with a proper "id" field, then the
-same "id" field will be attached in the corresponding response message
-so that requests and responses can match.  Clients should drop all the
-responses that have an unknown "id" field.
-
-2.4.1 success
--------------
-
-The format of a success response is:
-
-{ "return": json-value, "id": json-value }
-
- Where,
-
-- The "return" member contains the data returned by the command, which
-  is defined on a per-command basis (usually a json-object or
-  json-array of json-objects, but sometimes a json-number, json-string,
-  or json-array of json-strings); it is an empty json-object if the
-  command does not return data
-- The "id" member contains the transaction identification associated
-  with the command execution if issued by the Client
-
-2.4.2 error
------------
-
-The format of an error response is:
-
-{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
-
- Where,
-
-- The "class" member contains the error class name (eg. "GenericError")
-- The "desc" member is a human-readable error message. Clients should
-  not attempt to parse this message.
-- The "id" member contains the transaction identification associated with
-  the command execution if issued by the Client
-
-NOTE: Some errors can occur before the Server is able to read the "id" member,
-in these cases the "id" member will not be part of the error response, even
-if provided by the client.
-
-2.5 Asynchronous events
------------------------
-
-As a result of state changes, the Server may send messages unilaterally
-to the Client at any time, when not in the middle of any other
-response. They are called "asynchronous events".
-
-The format of asynchronous events is:
-
-{ "event": json-string, "data": json-object,
-  "timestamp": { "seconds": json-number, "microseconds": json-number } }
-
- Where,
-
-- The "event" member contains the event's name
-- The "data" member contains event specific data, which is defined in a
-  per-event basis, it is optional
-- The "timestamp" member contains the exact time of when the event
-  occurred in the Server. It is a fixed json-object with time in
-  seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
-  there is a failure to retrieve host time, both members of the
-  timestamp will be set to -1.
-
-The actual asynchronous events are documented in the QEMU QMP
-reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
-
-Some events are rate-limited to at most one per second.  If additional
-"similar" events arrive within one second, all but the last one are
-dropped, and the last one is delayed.  "Similar" normally means same
-event type.
-
-2.6 Forcing the JSON parser into known-good state
--------------------------------------------------
-
-Incomplete or invalid input can leave the server's JSON parser in a
-state where it can't parse additional commands.  To get it back into
-known-good state, the client should provoke a lexical error.
-
-The cleanest way to do that is sending an ASCII control character
-other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
-line).
-
-Sadly, older versions of QEMU can fail to flag this as an error.  If a
-client needs to deal with them, it should send a 0xFF byte.
-
-2.7 QGA Synchronization
------------------------
-
-When a client connects to QGA over a transport lacking proper
-connection semantics such as virtio-serial, QGA may have read partial
-input from a previous client.  The client needs to force QGA's parser
-into known-good state using the previous section's technique.
-Moreover, the client may receive output a previous client didn't read.
-To help with skipping that output, QGA provides the
-'guest-sync-delimited' command.  Refer to its documentation for
-details.
-
-
-3. QMP Examples
-===============
-
-This section provides some examples of real QMP usage, in all of them
-"C" stands for "Client" and "S" stands for "Server".
-
-3.1 Server greeting
--------------------
-
-S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
-     "package": "v3.0.0"}, "capabilities": ["oob"] } }
-
-3.2 Capabilities negotiation
-----------------------------
-
-C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
-S: { "return": {}}
-
-3.3 Simple 'stop' execution
----------------------------
-
-C: { "execute": "stop" }
-S: { "return": {} }
-
-3.4 KVM information
--------------------
-
-C: { "execute": "query-kvm", "id": "example" }
-S: { "return": { "enabled": true, "present": true }, "id": "example"}
-
-3.5 Parsing error
-------------------
-
-C: { "execute": }
-S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
-
-3.6 Powerdown event
--------------------
-
-S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
-    "event": "POWERDOWN" }
-
-3.7 Out-of-band execution
--------------------------
-
-C: { "exec-oob": "migrate-pause", "id": 42 }
-S: { "id": 42,
-     "error": { "class": "GenericError",
-      "desc": "migrate-pause is currently only supported during postcopy-active state" } }
-
-
-4. Capabilities Negotiation
-===========================
-
-When a Client successfully establishes a connection, the Server is in
-Capabilities Negotiation mode.
-
-In this mode only the qmp_capabilities command is allowed to run, all
-other commands will return the CommandNotFound error. Asynchronous
-messages are not delivered either.
-
-Clients should use the qmp_capabilities command to enable capabilities
-advertised in the Server's greeting (section '2.2 Server Greeting') they
-support.
-
-When the qmp_capabilities command is issued, and if it does not return an
-error, the Server enters in Command mode where capabilities changes take
-effect, all commands (except qmp_capabilities) are allowed and asynchronous
-messages are delivered.
-
-5 Compatibility Considerations
-==============================
-
-All protocol changes or new features which modify the protocol format in an
-incompatible way are disabled by default and will be advertised by the
-capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
-that array and enable the capabilities they support.
-
-The QMP Server performs a type check on the arguments to a command.  It
-generates an error if a value does not have the expected type for its
-key, or if it does not understand a key that the Client included.  The
-strictness of the Server catches wrong assumptions of Clients about
-the Server's schema.  Clients can assume that, when such validation
-errors occur, they will be reported before the command generated any
-side effect.
-
-However, Clients must not assume any particular:
-
-- Length of json-arrays
-- Size of json-objects; in particular, future versions of QEMU may add
-  new keys and Clients should be able to ignore them.
-- Order of json-object members or json-array elements
-- Amount of errors generated by a command, that is, new errors can be added
-  to any existing command in newer versions of the Server
-
-Any command or member name beginning with "x-" is deemed experimental,
-and may be withdrawn or changed in an incompatible manner in a future
-release.
-
-Of course, the Server does guarantee to send valid JSON.  But apart from
-this, a Client should be "conservative in what they send, and liberal in
-what they accept".
-
-6. Downstream extension of QMP
-==============================
-
-We recommend that downstream consumers of QEMU do *not* modify QMP.
-Management tools should be able to support both upstream and downstream
-versions of QMP without special logic, and downstream extensions are
-inherently at odds with that.
-
-However, we recognize that it is sometimes impossible for downstreams to
-avoid modifying QMP.  Both upstream and downstream need to take care to
-preserve long-term compatibility and interoperability.
-
-To help with that, QMP reserves JSON object member names beginning with
-'__' (double underscore) for downstream use ("downstream names").  This
-means upstream will never use any downstream names for its commands,
-arguments, errors, asynchronous events, and so forth.
-
-Any new names downstream wishes to add must begin with '__'.  To
-ensure compatibility with other downstreams, it is strongly
-recommended that you prefix your downstream names with '__RFQDN_' where
-RFQDN is a valid, reverse fully qualified domain name which you
-control.  For example, a qemu-kvm specific monitor command would be:
-
-    (qemu) __org.linux-kvm_enable_irqchip
-
-Downstream must not change the server greeting (section 2.2) other than
-to offer additional capabilities.  But see below for why even that is
-discouraged.
-
-Section '5 Compatibility Considerations' applies to downstream as well
-as to upstream, obviously.  It follows that downstream must behave
-exactly like upstream for any input not containing members with
-downstream names ("downstream members"), except it may add members
-with downstream names to its output.
-
-Thus, a client should not be able to distinguish downstream from
-upstream as long as it doesn't send input with downstream members, and
-properly ignores any downstream members in the output it receives.
-
-Advice on downstream modifications:
-
-1. Introducing new commands is okay.  If you want to extend an existing
-   command, consider introducing a new one with the new behaviour
-   instead.
-
-2. Introducing new asynchronous messages is okay.  If you want to extend
-   an existing message, consider adding a new one instead.
-
-3. Introducing new errors for use in new commands is okay.  Adding new
-   errors to existing commands counts as extension, so 1. applies.
-
-4. New capabilities are strongly discouraged.  Capabilities are for
-   evolving the basic protocol, and multiple diverging basic protocol
-   dialects are most undesirable.
diff --git a/python/qemu/qmp/models.py b/python/qemu/qmp/models.py
index de87f87..da52848 100644
--- a/python/qemu/qmp/models.py
+++ b/python/qemu/qmp/models.py
@@ -54,7 +54,7 @@
 
 class Greeting(Model):
     """
-    Defined in qmp-spec.txt, section 2.2, "Server Greeting".
+    Defined in qmp-spec.rst, section "Server Greeting".
 
     :param raw: The raw Greeting object.
     :raise KeyError: If any required fields are absent.
@@ -82,7 +82,7 @@
 
 class QMPGreeting(Model):
     """
-    Defined in qmp-spec.txt, section 2.2, "Server Greeting".
+    Defined in qmp-spec.rst, section "Server Greeting".
 
     :param raw: The raw QMPGreeting object.
     :raise KeyError: If any required fields are absent.
@@ -104,7 +104,7 @@
 
 class ErrorResponse(Model):
     """
-    Defined in qmp-spec.txt, section 2.4.2, "error".
+    Defined in qmp-spec.rst, section "Error".
 
     :param raw: The raw ErrorResponse object.
     :raise KeyError: If any required fields are absent.
@@ -126,7 +126,7 @@
 
 class ErrorInfo(Model):
     """
-    Defined in qmp-spec.txt, section 2.4.2, "error".
+    Defined in qmp-spec.rst, section "Error".
 
     :param raw: The raw ErrorInfo object.
     :raise KeyError: If any required fields are absent.
diff --git a/python/qemu/qmp/qmp_client.py b/python/qemu/qmp/qmp_client.py
index 9d73ae6..2a817f9 100644
--- a/python/qemu/qmp/qmp_client.py
+++ b/python/qemu/qmp/qmp_client.py
@@ -369,7 +369,7 @@
             # This is very likely a server parsing error.
             # It doesn't inherently belong to any pending execution.
             # Instead of performing clever recovery, just terminate.
-            # See "NOTE" in qmp-spec.txt, section 2.4.2
+            # See "NOTE" in qmp-spec.rst, section "Error".
             raise ServerParseError(
                 ("Server sent an error response without an ID, "
                  "but there are no ID-less executions pending. "
@@ -377,7 +377,7 @@
                 msg
             )
 
-        # qmp-spec.txt, section 2.4:
+        # qmp-spec.rst, section "Commands Responses":
         # 'Clients should drop all the responses
         # that have an unknown "id" field.'
         self.logger.log(
diff --git a/qapi/control.json b/qapi/control.json
index 6a7c5af..a91fa33 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -27,7 +27,7 @@
 # Notes: This command is valid exactly when first connecting: it must
 #     be issued before any other command will be accepted, and will
 #     fail once the monitor is accepting other commands.  (see qemu
-#     docs/interop/qmp-spec.txt)
+#     docs/interop/qmp-spec.rst)
 #
 #     The QMP client needs to explicitly enable QMP capabilities,
 #     otherwise all the QMP capabilities will be turned off by
@@ -46,7 +46,7 @@
 # connection, used for agreeing on particular QMP extension behaviors.
 #
 # @oob: QMP ability to support out-of-band requests.  (Please refer to
-#     qmp-spec.txt for more information on OOB)
+#     qmp-spec.rst for more information on OOB)
 #
 # Since: 2.12
 ##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 31e0b36..6594afb 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -29,7 +29,8 @@
 #   -> data issued by the Client
 #   <- Server data response
 #
-# Please, refer to the QMP specification (docs/interop/qmp-spec.txt)
+# Please refer to the
+# :doc:`QEMU Machine Protocol Specification </interop/qmp-spec>`
 # for detailed information on the Server command and response formats.
 ##
 
diff --git a/qemu-options.hx b/qemu-options.hx
index 30690d9..e456614 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4170,26 +4170,42 @@
     QEMU_ARCH_ALL)
 SRST
 ``-qmp dev``
-    Like -monitor but opens in 'control' mode.
+    Like ``-monitor`` but opens in 'control' mode. For example, to make
+    QMP available on localhost port 4444::
+
+        -qmp tcp:localhost:4444,server=on,wait=off
+
+    Not all options are configurable via this syntax; for maximum
+    flexibility use the ``-mon`` option and an accompanying ``-chardev``.
+
 ERST
 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
     QEMU_ARCH_ALL)
 SRST
 ``-qmp-pretty dev``
-    Like -qmp but uses pretty JSON formatting.
+    Like ``-qmp`` but uses pretty JSON formatting.
 ERST
 
 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
     "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
 SRST
 ``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
-    Setup monitor on chardev name. ``mode=control`` configures 
-    a QMP monitor (a JSON RPC-style protocol) and it is not the
-    same as HMP, the human monitor that has a "(qemu)" prompt.
-    ``pretty`` is only valid when ``mode=control``, 
+    Set up a monitor connected to the chardev ``name``.
+    QEMU supports two monitors: the Human Monitor Protocol
+    (HMP; for human interaction), and the QEMU Monitor Protocol
+    (QMP; a JSON RPC-style protocol).
+    The default is HMP; ``mode=control`` selects QMP instead.
+    ``pretty`` is only valid when ``mode=control``,
     turning on JSON pretty printing to ease
     human reading and debugging.
+
+    For example::
+
+      -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
+      -mon chardev=mon1,mode=control,pretty=on
+
+    enables the QMP monitor on localhost port 4444 with pretty-printing.
 ERST
 
 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
diff --git a/qobject/json-lexer.c b/qobject/json-lexer.c
index 632320d..51341d9 100644
--- a/qobject/json-lexer.c
+++ b/qobject/json-lexer.c
@@ -139,7 +139,7 @@
          * bytes '\xFE', '\xFF'.  Structural characters and line
          * endings are promising resynchronization points.  Clients
          * may use the others to force the JSON parser into known-good
-         * state; see docs/interop/qmp-spec.txt.
+         * state; see docs/interop/qmp-spec.rst.
          */
         [0 ... 0x1F] = IN_START | LOOKAHEAD,
         [0x20 ... 0xFD] = IN_RECOVERY,
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 1ff334e..22e7bcc 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -675,8 +675,8 @@
         match = self._match_at_name_colon(line)
         if match:
             raise QAPIParseError(self._parser,
-                                 "'@%s:' can't follow '%s' section"
-                                 % (match.group(1), self.sections[0].name))
+                                 "description of '@%s:' follows a section"
+                                 % match.group(1))
         match = self._match_section_tag(line)
         if match:
             line = line[match.end():]
diff --git a/tests/qapi-schema/doc-interleaved-section.err b/tests/qapi-schema/doc-interleaved-section.err
index 715d58c..e5d1ef5 100644
--- a/tests/qapi-schema/doc-interleaved-section.err
+++ b/tests/qapi-schema/doc-interleaved-section.err
@@ -1 +1 @@
-doc-interleaved-section.json:15:1: '@foobar:' can't follow 'Note' section
+doc-interleaved-section.json:15:1: description of '@foobar:' follows a section