Re: [PATCH v5 12/20] qapi: Use rST markup for literal blocks

[Markus Armbruster <armbru@redhat.com>]

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

> There are exactly two places in our json doc comments where we
> use the markup accepted by the texi doc generator where a '|' in
> the first line of a doc comment means the line should be emitted
> as a literal block (fixed-width font, whitespace preserved).

Has always been pretty broken, though: each line ends up in its own
@example environment.  See doc-good.texi.

> Since we use this syntax so rarely, instead of making the rST
> generator support it, instead just convert the two uses to
> rST-format literal blocks, which are indented and introduced
> with '::'.

Also, we should not reinvent what reST already provides.

> (The rST generator doesn't complain about the old style syntax,
> it just emits it with the '|' and with the whitespace not
> preserved, which looks odd, but means we can safely leave this
> change until after we've stopped generating texinfo.)

In other words, the recent switch to the reST generator messed these
examples up, and this commit tidies up.

> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  qapi/block-core.json  | 16 +++++++++-------
>  qapi/qapi-schema.json |  6 ++++--
>  2 files changed, 13 insertions(+), 9 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 535b2b2e7bf..12758116e85 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -566,13 +566,15 @@
>  #        For the example above, @bins may be something like [3, 1, 5, 2],
>  #        and corresponding histogram looks like:
>  #
> -# |      5|           *
> -# |      4|           *
> -# |      3| *         *
> -# |      2| *         *    *
> -# |      1| *    *    *    *
> -# |       +------------------
> -# |           10   50   100
> +# ::
> +#
> +#        5|           *
> +#        4|           *
> +#        3| *         *
> +#        2| *         *    *
> +#        1| *    *    *    *
> +#         +------------------
> +#             10   50   100
>  #
>  # Since: 4.0
>  ##

Could exploit that reST is the Perl of ASCII-based markups, and write

   #        For the example above, @bins may be something like [3, 1, 5, 2],
   #        and corresponding histogram looks like::
   #
   #        5|           *
   #        4|           *
   #        3| *         *
   #        2| *         *    *
   #        1| *    *    *    *
   #         +------------------
   #             10   50   100
   #
   # Since: 4.0
   ##

Matter of taste.  I find both similarly arcane.

> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index 5fc0771eb04..c19b4267058 100644
> --- a/qapi/qapi-schema.json
> +++ b/qapi/qapi-schema.json
> @@ -23,8 +23,10 @@
>  #
>  # Example:
>  #
> -# | -> data issued by the Client
> -# | <- Server data response
> +# ::
> +#
> +#   -> data issued by the Client
> +#   <- Server data response
>  #
>  # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
>  # detailed information on the Server command and response formats.

Likewise.

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