qmp-intro.txt is quite small and provides very little information
that isn't already in the documentation elsewhere.  Fold the example
command lines into qemu-options.hx, and delete the now-unneeded plain
text document.

While we're touching the qemu-options.hx documentation text,
wordsmith it a little bit and improve the rST formatting.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
v1->v2: removed a trailing space spotted by Eric
---
 docs/interop/qmp-intro.txt | 88 --------------------------------------
 qemu-options.hx            | 28 +++++++++---
 2 files changed, 22 insertions(+), 94 deletions(-)
 delete mode 100644 docs/interop/qmp-intro.txt

diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
deleted file mode 100644
index 1c745a7af04..00000000000
--- 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/qemu-options.hx b/qemu-options.hx
index 42b9094c10f..920f9640155 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4170,26 +4170,42 @@ DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
     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, \
-- 
2.34.1

Peter Maydell <peter.maydell@linaro.org> writes:

> qmp-intro.txt is quite small and provides very little information
> that isn't already in the documentation elsewhere.  Fold the example
> command lines into qemu-options.hx, and delete the now-unneeded plain
> text document.

A friendly introduction can be worth some redundancy.  But I can't see
how to fit it into our greater doc framework, and standalone plaintext
documents likely isn't where someone in need of a friendly intro would
look for one.  Since I have nothing better to offer, no objection.

> While we're touching the qemu-options.hx documentation text,
> wordsmith it a little bit and improve the rST formatting.
>
> Reviewed-by: Eric Blake <eblake@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v1->v2: removed a trailing space spotted by Eric
> ---
>  docs/interop/qmp-intro.txt | 88 --------------------------------------
>  qemu-options.hx            | 28 +++++++++---
>  2 files changed, 22 insertions(+), 94 deletions(-)
>  delete mode 100644 docs/interop/qmp-intro.txt
>
> diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
> deleted file mode 100644
> index 1c745a7af04..00000000000
> --- 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/qemu-options.hx b/qemu-options.hx
> index 42b9094c10f..920f9640155 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4170,26 +4170,42 @@ DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
>      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).

We can't quite decide whether the M in QMP means "machine" or "monitor":

    $ git-grep -i "machine protocol"
    docs/about/deprecated.rst:QEMU Machine Protocol (QMP) commands
    docs/about/removed-features.rst:QEMU Machine Protocol (QMP) commands
    docs/interop/qmp-spec.rst:QEMU Machine Protocol Specification
    docs/interop/qmp-spec.rst:The QEMU Machine Protocol (QMP) is a JSON-based

    $ git-grep -i "monitor protocol"
    docs/about/deprecated.rst:Human Monitor Protocol (HMP) commands
    docs/about/removed-features.rst:Human Monitor Protocol (HMP) commands
    docs/devel/qapi-code-gen.rst:format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
    docs/sphinx/qmp_lexer.py:# QEMU Monitor Protocol Lexer Extension
    docs/system/introduction.rst::ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to
    docs/system/introduction.rst:state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well
    docs/tools/qemu-storage-daemon.rst:Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
    python/qemu/qmp/__init__.py:QEMU Monitor Protocol (QMP) development library & tooling.
    python/qemu/qmp/legacy.py:    Provide an API to connect to QEMU via QEMU Monitor Protocol (QMP)
    qemu-options.hx:    QEMU supports two monitors: the Human Monitor Protocol
    qemu-options.hx:    (HMP; for human interaction), and the QEMU Monitor Protocol

Not this patch's fault.

> +    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, \

Reviewed-by: Markus Armbruster <armbru@redhat.com>