Re: [PATCH 07/29] qapi/block-core.json: Use literal block for ascii art

[Markus Armbruster]

Peter Maydell <address@hidden> writes:

> The ascii-art graph in the BlockLatencyHistogramInfo
> documentation doesn't render correctly in either the HTML
> or the manpage output, because in both cases the whitespace
> is collapsed.

Plain text and PDF output is just as bad.  Suggest "doesn't render
correctly, because the whitespace is collapsed".

> Use the '|' format that emits a literal 'example' block
> so the graph is displayed correctly.
>
> Signed-off-by: Peter Maydell <address@hidden>
> ---
>  qapi/block-core.json | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index ef94a296868..372f35ee5f0 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -550,13 +550,13 @@
>  #        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

Wow, we're acquiring a second use of the '|' feature.

It's actually broken, because the doc generator puts each | line in its
own @example environment.

Doesn't really matter, because PATCH 26 replaces it by rST markup that
actually works.  A note in the commit message could make sense, though.

But instead of making it differently broken until PATCH 26 fixes it for
good, I'd simply leave it broken until then :)

If you decide to keep the patch: can we keep the table aligned with the
preceding paragraph?  Like this:

   # |      5|           *
   # |      4|           *
   # |      3| *         *
   # |      2| *         *    *
   # |      1| *    *    *    *
   # |       +------------------
   # |           10   50   100

>  #
>  # Since: 4.0
>  ##