| Message ID | 20200213175647.17628-8-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
6:59 PM Čet, 13.02.2020. Peter Maydell <peter.maydell@linaro.org> је написао/ла: > > The ascii-art graph Just out of couriousity, are unicode characters allowed in rst files? The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters. Aleksandar > in the BlockLatencyHistogramInfo documentation > doesn't render correctly, because the whitespace is collapsed. > > Use the '|' format that emits a literal 'example' block so the graph > is displayed correctly. > > Strictly the texinfo generated is still wrong because each line > goes into its own @example environment, but it renders better > than what we had before. > > Fixing this rendering is a necessary prerequisite for the rST > generator, which otherwise complains about the inconsistent > indentation in the ascii-art graph. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > v1->v2: tweaked commit message, made graph still line up > with preceding paragraph text > --- > 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..db9ca688d49 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 > ## > -- > 2.20.1 > > <p dir="ltr"></p> <p dir="ltr">6:59 PM Čet, 13.02.2020. Peter Maydell <<a href="mailto:peter.maydell@linaro.org">peter.maydell@linaro.org</a>> је написао/ла:<br> ><br> > The ascii-art graph</p> <p dir="ltr">Just out of couriousity, are unicode characters allowed in rst files?</p> <p dir="ltr">The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters.</p> <p dir="ltr">Aleksandar</p> <p dir="ltr">> in the BlockLatencyHistogramInfo documentation<br> > doesn't render correctly, because the whitespace is collapsed.<br> ><br> > Use the '|' format that emits a literal 'example' block so the graph<br> > is displayed correctly.<br> ><br> > Strictly the texinfo generated is still wrong because each line<br> > goes into its own @example environment, but it renders better<br> > than what we had before.<br> ><br> > Fixing this rendering is a necessary prerequisite for the rST<br> > generator, which otherwise complains about the inconsistent<br> > indentation in the ascii-art graph.<br> ><br> > Signed-off-by: Peter Maydell <<a href="mailto:peter.maydell@linaro.org">peter.maydell@linaro.org</a>><br> > ---<br> > v1->v2: tweaked commit message, made graph still line up<br> > with preceding paragraph text<br> > ---<br> > qapi/block-core.json | 14 +++++++-------<br> > 1 file changed, 7 insertions(+), 7 deletions(-)<br> ><br> > diff --git a/qapi/block-core.json b/qapi/block-core.json<br> > index ef94a296868..db9ca688d49 100644<br> > --- a/qapi/block-core.json<br> > +++ b/qapi/block-core.json<br> > @@ -550,13 +550,13 @@<br> > # For the example above, @bins may be something like [3, 1, 5, 2],<br> > # and corresponding histogram looks like:<br> > #<br> > -# 5| *<br> > -# 4| *<br> > -# 3| * *<br> > -# 2| * * *<br> > -# 1| * * * *<br> > -# +------------------<br> > -# 10 50 100<br> > +# | 5| *<br> > +# | 4| *<br> > +# | 3| * *<br> > +# | 2| * * *<br> > +# | 1| * * * *<br> > +# | +------------------<br> > +# | 10 50 100<br> > #<br> > # Since: 4.0<br> > ##<br> > -- <br> > 2.20.1<br> ><br> ><br> </p>
Peter Maydell <peter.maydell@linaro.org> writes: > The ascii-art graph in the BlockLatencyHistogramInfo documentation > doesn't render correctly, because the whitespace is collapsed. > > Use the '|' format that emits a literal 'example' block so the graph > is displayed correctly. > > Strictly the texinfo generated is still wrong because each line > goes into its own @example environment, but it renders better > than what we had before. > > Fixing this rendering is a necessary prerequisite for the rST > generator, which otherwise complains about the inconsistent > indentation in the ascii-art graph. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > v1->v2: tweaked commit message, made graph still line up > with preceding paragraph text > --- > 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..db9ca688d49 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 > ## Reviewed-by: Markus Armbruster <armbru@redhat.com>
Hi Aleksandar, On Fri, Feb 14, 2020 at 12:04 AM Aleksandar Markovic <aleksandar.m.mail@gmail.com> wrote: > > 6:59 PM Čet, 13.02.2020. Peter Maydell <peter.maydell@linaro.org> је написао/ла: > > > > The ascii-art graph > > Just out of couriousity, are unicode characters allowed in rst files? I remember 2 years ago a blind developer thanked the QEMU community to still restrict commits to 80 characters, because while 4K display are available, he and other visually impaired developers cloud still browse the QEMU codebase with their refreshable Braille display (which was 80 cels). I don't know how many visually impaired developers are following this project. A quick google returns " There is no concept of Unicode in Braille. In that sense Braille is similar to old 8-bit code pages which represented different symbols in different languages for the same symbol code." (https://superuser.com/questions/629443/represent-unicode-characters-in-braille). (I'm Cc'ing Samuel who cares about Braille displays.) > > The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters. > > Aleksandar
9:56 PM Sub, 15.02.2020. Philippe Mathieu-Daudé <philippe@mathieu-daude.net> је написао/ла: > > Hi Aleksandar, > > On Fri, Feb 14, 2020 at 12:04 AM Aleksandar Markovic > <aleksandar.m.mail@gmail.com> wrote: > > > > 6:59 PM Čet, 13.02.2020. Peter Maydell <peter.maydell@linaro.org> је написао/ла: > > > > > > The ascii-art graph > > > > Just out of couriousity, are unicode characters allowed in rst files? > > I remember 2 years ago a blind developer thanked the QEMU community to > still restrict commits to 80 characters, because while 4K display are > available, he and other visually impaired developers cloud still > browse the QEMU codebase with their refreshable Braille display (which > was 80 cels). I don't know how many visually impaired developers are > following this project. A quick google returns " There is no concept > of Unicode in Braille. In that sense Braille is similar to old 8-bit > code pages which represented different symbols in different languages > for the same symbol code." > ( https://superuser.com/questions/629443/represent-unicode-characters-in-braille ). > > (I'm Cc'ing Samuel who cares about Braille displays.) > Got it. > > > > The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters. > > > > Aleksandar <p dir="ltr"></p> <p dir="ltr">9:56 PM Sub, 15.02.2020. Philippe Mathieu-Daudé <<a href="mailto:philippe@mathieu-daude.net">philippe@mathieu-daude.net</a>> је написао/ла:<br> ><br> > Hi Aleksandar,<br> ><br> > On Fri, Feb 14, 2020 at 12:04 AM Aleksandar Markovic<br> > <<a href="mailto:aleksandar.m.mail@gmail.com">aleksandar.m.mail@gmail.com</a>> wrote:<br> > ><br> > > 6:59 PM Čet, 13.02.2020. Peter Maydell <<a href="mailto:peter.maydell@linaro.org">peter.maydell@linaro.org</a>> је написао/ла:<br> > > ><br> > > > The ascii-art graph<br> > ><br> > > Just out of couriousity, are unicode characters allowed in rst files?<br> ><br> > I remember 2 years ago a blind developer thanked the QEMU community to<br> > still restrict commits to 80 characters, because while 4K display are<br> > available, he and other visually impaired developers cloud still<br> > browse the QEMU codebase with their refreshable Braille display (which<br> > was 80 cels). I don't know how many visually impaired developers are<br> > following this project. A quick google returns " There is no concept<br> > of Unicode in Braille. In that sense Braille is similar to old 8-bit<br> > code pages which represented different symbols in different languages<br> > for the same symbol code."<br> > (<a href="https://superuser.com/questions/629443/represent-unicode-characters-in-braille">https://superuser.com/questions/629443/represent-unicode-characters-in-braille</a>).<br> ><br> > (I'm Cc'ing Samuel who cares about Braille displays.)<br> ></p> <p dir="ltr">Got it. <br> > ><br> > > The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters.<br> > ><br> > > Aleksandar<br> </p>
On Sat, Feb 15, 2020 at 10:01 PM Aleksandar Markovic <aleksandar.m.mail@gmail.com> wrote: > 9:56 PM Sub, 15.02.2020. Philippe Mathieu-Daudé <philippe@mathieu-daude.net> је написао/ла: > > On Fri, Feb 14, 2020 at 12:04 AM Aleksandar Markovic > > <aleksandar.m.mail@gmail.com> wrote: > > > > > > 6:59 PM Čet, 13.02.2020. Peter Maydell <peter.maydell@linaro.org> је написао/ла: > > > > > > > > The ascii-art graph > > > > > > Just out of couriousity, are unicode characters allowed in rst files? > > > > I remember 2 years ago a blind developer thanked the QEMU community to > > still restrict commits to 80 characters, because while 4K display are > > available, he and other visually impaired developers cloud still > > browse the QEMU codebase with their refreshable Braille display (which > > was 80 cels). I don't know how many visually impaired developers are > > following this project. A quick google returns " There is no concept > > of Unicode in Braille. In that sense Braille is similar to old 8-bit > > code pages which represented different symbols in different languages > > for the same symbol code." > > (https://superuser.com/questions/629443/represent-unicode-characters-in-braille). > > > > (I'm Cc'ing Samuel who cares about Braille displays.) > > > > Got it. AFAIK there are no particular care in the project regarding visually impaired developers, maybe we are already using things that exclude them. IOW without a project policy to include visually impaired developers, my comment is irrelevant and it shouldn't restrict the use of unicode to improve documentation. Personally I'd rather we keep the project open to all possible contributors. > > > > > > The boxes could've been rendered in a much more beautifull way using "lines and corners" group of unicode characters. > > > > > > Aleksandar
Hello, Philippe Mathieu-Daudé, le lun. 17 févr. 2020 01:44:35 +0100, a ecrit: > On Sat, Feb 15, 2020 at 10:01 PM Aleksandar Markovic > <aleksandar.m.mail@gmail.com> wrote: > > 9:56 PM Sub, 15.02.2020. Philippe Mathieu-Daudé <philippe@mathieu-daude.net> је написао/ла: > > > On Fri, Feb 14, 2020 at 12:04 AM Aleksandar Markovic > > > <aleksandar.m.mail@gmail.com> wrote: > > > > > > > > 6:59 PM Čet, 13.02.2020. Peter Maydell <peter.maydell@linaro.org> је написао/ла: > > > > > > > > > > The ascii-art graph > > > > > > > > Just out of couriousity, are unicode characters allowed in rst files? > > > > > > I remember 2 years ago a blind developer thanked the QEMU community to > > > still restrict commits to 80 characters, because while 4K display are > > > available, he and other visually impaired developers cloud still > > > browse the QEMU codebase with their refreshable Braille display (which > > > was 80 cels). I don't know how many visually impaired developers are > > > following this project. A quick google returns " There is no concept > > > of Unicode in Braille. In that sense Braille is similar to old 8-bit > > > code pages which represented different symbols in different languages > > > for the same symbol code." > > > (https://superuser.com/questions/629443/represent-unicode-characters-in-braille). > > > > > > (I'm Cc'ing Samuel who cares about Braille displays.) Nowadays' screen reader do provide some translations for some unicode fancies. But the analogy with codepage remains true: since there are only 256 braille pattern, there will be ambiguity between representation of plain text and representation of unicode fancies. Using plain ascii avoids this issue, i.e. blind developers will know that '|' and '-' are commonly used for drawing, and their Braille representations are not ambiguous. So that's indeed better to keep them ascii. More generally, ascii art is however hard to catch with a Braille device anyway... Samuel
diff --git a/qapi/block-core.json b/qapi/block-core.json index ef94a296868..db9ca688d49 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, because the whitespace is collapsed. Use the '|' format that emits a literal 'example' block so the graph is displayed correctly. Strictly the texinfo generated is still wrong because each line goes into its own @example environment, but it renders better than what we had before. Fixing this rendering is a necessary prerequisite for the rST generator, which otherwise complains about the inconsistent indentation in the ascii-art graph. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- v1->v2: tweaked commit message, made graph still line up with preceding paragraph text --- qapi/block-core.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) -- 2.20.1