Re: [PATCH v2 2/2] docs/interop: Delete qmp-intro.txt

[Markus Armbruster]

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>