On Mon, Mar 13, 2017 at 10:23 AM Markus Armbruster <armbru@redhat.com>
wrote:
> We use tag #optional to mark optional members, like this:
>
> # @name: #optional The name of the guest
>
> texi_body() strips #optional, but not whitespace around it. For the
> above, we get in qemu-qmp-qapi.texi
>
> @item @code{'name'} (optional)
> The name of the guest
> @end table
>
> The extra space can lead to artifacts in output, e.g in
> qemu-qmp-ref.7.pod
>
> =item C<'name'> (optional)
>
> The name of the guest
>
> and then in qemu-qmp-ref.7
>
> .IX Item "name (optional)"
> .Vb 1
> \& The name of the guest
> .Ve
>
> instead of intended plain
>
> .IX Item "name (optional)"
> The name of the guest
>
> Get rid of these artifacts by removing whitespace around #optional
> along with it.
>
> This turns three minus signs in qapi-schema.json into markup, because
> they're now at the beginning of the line. Drop them, they're unwanted
> there.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
> qapi-schema.json | 6 +++---
> scripts/qapi2texi.py | 3 ++-
> 2 files changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 17c766e..52141cd 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -3779,11 +3779,11 @@
> #
> # @dstport: #optional destination port - mandatory for udp, optional for
> ip
> #
> -# @ipv6: #optional - force the use of ipv6
> +# @ipv6: #optional force the use of ipv6
> #
> -# @udp: #optional - use the udp version of l2tpv3 encapsulation
> +# @udp: #optional use the udp version of l2tpv3 encapsulation
> #
> -# @cookie64: #optional - use 64 bit coookies
> +# @cookie64: #optional use 64 bit coookies
> #
> # @counter: #optional have sequence counter
> #
> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
> index 06d6abf..0f3e573 100755
> --- a/scripts/qapi2texi.py
> +++ b/scripts/qapi2texi.py
> @@ -137,7 +137,8 @@ def texi_body(doc):
> desc = str(section)
> opt = ''
> if "#optional" in desc:
> - desc = desc.replace("#optional", "")
> + desc = re.sub(r'^ *#optional *\n?|\n? *#optional
> *$|#optional',
> + '', desc)
> opt = ' (optional)'
> body += "@item @code{'%s'}%s\n%s\n" % (arg, opt,
> texi_format(desc))
> --
> 2.7.4
>
>
> --
Marc-André Lureau