Re: [Qemu-devel] [RFC PATCH 03/32] qapi2texi: Fix for examples containing '@'

[Marc-André Lureau]

Hi

On Mon, Oct 2, 2017 at 5:25 PM, Markus Armbruster <address@hidden> 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 <address@hidden>
> ---
>  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}
> address@hidden 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:}
> address@hidden
> address@hidden
>  -> in
>  <- out
> address@hidden example
> address@hidden verbatim
>
>  @b{Examples:}
> address@hidden
> address@hidden
>  - *verbatim*
> -- @at sign BUG: gets passed to Texinfo unescaped
> -- @address@hidden
> address@hidden example
> +- @at sign
> +- {braces}
> address@hidden 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:}
> address@hidden
> address@hidden
>  -> in
>
>  <- out
> address@hidden example
> address@hidden verbatim
>
>  @end deftypefn
>
> --
> 2.13.6
>
>



-- 
Marc-André Lureau