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

[Peter Maydell]

On Fri, 7 Feb 2020 at 08:50, Markus Armbruster <address@hidden> wrote:
>
> 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 :)

IIRC I need to fix it early, because without the '|' prefix it's
a syntax error in rST because of the inconsistent indent. (Otherwise
I probably wouldn't have noticed it at all.)

> 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
> >  ##

Sure, why not.

-- PMM