[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v5 12/20] qapi: Use rST markup for literal blocks
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v5 12/20] qapi: Use rST markup for literal blocks |
Date: |
Fri, 04 Sep 2020 15:02:15 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
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>
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: [PATCH v5 12/20] qapi: Use rST markup for literal blocks,
Markus Armbruster <=