| Message ID | 20200206173040.17337-8-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> > --- > 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 > ##
On Fri, 7 Feb 2020 at 08:50, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> > > --- > > 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
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 # # Since: 4.0 ##
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. Use the '|' format that emits a literal 'example' block so the graph is displayed correctly. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- qapi/block-core.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)