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 <[email protected]> --- 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
