| Message ID | 20171002152552.27999-4-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | Command line QAPIfication | expand |
Hi On Mon, Oct 2, 2017 at 5:25 PM, Markus Armbruster <armbru@redhat.com> wrote: > Instead of quoting example text so that the @example environment shows > it verbatim, simply use the @verbatim environment. > Not sure if this is really worth it, unless we have a real use-case of @ in examples. > Examples are no longer indented in output, because makeinfo doesn't > indent @verbatim, unlike @example. > TODO keep indentation somehow? > > Signed-off-by: Markus Armbruster <armbru@redhat.com> > --- > scripts/qapi2texi.py | 12 +++++------- > tests/qapi-schema/doc-good.json | 2 +- > tests/qapi-schema/doc-good.out | 2 +- > tests/qapi-schema/doc-good.texi | 16 ++++++++-------- > 4 files changed, 15 insertions(+), 17 deletions(-) > > diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py > index 92e2af2cd6..1500afc553 100755 > --- a/scripts/qapi2texi.py > +++ b/scripts/qapi2texi.py > @@ -52,13 +52,11 @@ def subst_braces(doc): > > > def texi_example(doc): > - """Format @example""" > - # TODO: Neglects to escape @ characters. > - # We should probably escape them in subst_braces(), and rename the > - # function to subst_special() or subs_texi_special(). If we do that, we > - # need to delay it until after subst_vars() in texi_format(). > - doc = subst_braces(doc).strip('\n') > - return EXAMPLE_FMT(code=doc) > + """Format example text""" > + return """@verbatim > +{code} > +@end verbatim > +""".format(code=doc.strip('\n')) > > > def texi_format(doc): > diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json > index 44098d7f1a..54a0012d5f 100644 > --- a/tests/qapi-schema/doc-good.json > +++ b/tests/qapi-schema/doc-good.json > @@ -117,7 +117,7 @@ > # <- out > # Examples: > # - *verbatim* > -# - @at sign BUG: gets passed to Texinfo unescaped > +# - @at sign > # - {braces} > # Since: 2.10 > ## > diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out > index b732b81119..a62d2d879c 100644 > --- a/tests/qapi-schema/doc-good.out > +++ b/tests/qapi-schema/doc-good.out > @@ -138,7 +138,7 @@ Duis aute irure dolor > <- out > section=Examples > - *verbatim* > -- @at sign BUG: gets passed to Texinfo unescaped > +- @at sign > - {braces} > section=Since > 2.10 > diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi > index 840a492249..3b77f2f675 100644 > --- a/tests/qapi-schema/doc-good.texi > +++ b/tests/qapi-schema/doc-good.texi > @@ -201,17 +201,17 @@ Ut enim ad minim veniam > Duis aute irure dolor > > @b{Example:} > -@example > +@verbatim > -> in > <- out > -@end example > +@end verbatim > > @b{Examples:} > -@example > +@verbatim > - *verbatim* > -- @at sign BUG: gets passed to Texinfo unescaped > -- @{braces@} > -@end example > +- @at sign > +- {braces} > +@end verbatim > > @b{Since:} > 2.10 > @@ -227,11 +227,11 @@ If you're bored enough to read this, go see a video of boxed cats > @b{Arguments:} the members of @code{Object} > > @b{Example:} > -@example > +@verbatim > -> in > > <- out > -@end example > +@end verbatim > > @end deftypefn > > -- > 2.13.6 > >
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index 92e2af2cd6..1500afc553 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -52,13 +52,11 @@ def subst_braces(doc): def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, we - # need to delay it until after subst_vars() in texi_format(). - doc = subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=doc) + """Format example text""" + return """@verbatim +{code} +@end verbatim +""".format(code=doc.strip('\n')) def texi_format(doc): diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 44098d7f1a..54a0012d5f 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -117,7 +117,7 @@ # <- out # Examples: # - *verbatim* -# - @at sign BUG: gets passed to Texinfo unescaped +# - @at sign # - {braces} # Since: 2.10 ## diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index b732b81119..a62d2d879c 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -138,7 +138,7 @@ Duis aute irure dolor <- out section=Examples - *verbatim* -- @at sign BUG: gets passed to Texinfo unescaped +- @at sign - {braces} section=Since 2.10 diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 840a492249..3b77f2f675 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -201,17 +201,17 @@ Ut enim ad minim veniam Duis aute irure dolor @b{Example:} -@example +@verbatim -> in <- out -@end example +@end verbatim @b{Examples:} -@example +@verbatim - *verbatim* -- @at sign BUG: gets passed to Texinfo unescaped -- @{braces@} -@end example +- @at sign +- {braces} +@end verbatim @b{Since:} 2.10 @@ -227,11 +227,11 @@ If you're bored enough to read this, go see a video of boxed cats @b{Arguments:} the members of @code{Object} @b{Example:} -@example +@verbatim -> in <- out -@end example +@end verbatim @end deftypefn
Instead of quoting example text so that the @example environment shows it verbatim, simply use the @verbatim environment. Examples are no longer indented in output, because makeinfo doesn't indent @verbatim, unlike @example. TODO keep indentation somehow? Signed-off-by: Markus Armbruster <armbru@redhat.com> --- scripts/qapi2texi.py | 12 +++++------- tests/qapi-schema/doc-good.json | 2 +- tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.texi | 16 ++++++++-------- 4 files changed, 15 insertions(+), 17 deletions(-)