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
>
>
--
Marc-André Lureau