Re: [Qemu-devel] [PATCH v3 10/14] docs: add master qapi texi files

[Markus Armbruster <armbru@redhat.com>]

I see you managed to turn the templates into master files.  A welcome
simplification of the build process.

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> The qapi2texi scripts generates a file to be included in a texi

script (singular)

> file. Add "QEMU QMP Reference Manual" and "QEMU Guest Agent Protocol
> Reference" master texi files. Move qmp-intro.txt into qemu-qmp-ref.texi,
> to widen its content on various installed target
> formats (man/txt/html/pdf/info..)

I feel replacing qmp-intro.txt in this patch as well is one step too
many.  Let's do exactly the same both for QGA and QMP in this patch.
Actually, in this series, because I want to commit it sooner rather than
later, and the way to do that is to factor out and postpone inessential
parts that are eating precious review bandwidth.

> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/qemu-ga-ref.texi         |  65 ++++++++++++++++++
>  docs/qemu-qmp-ref.texi        | 156 ++++++++++++++++++++++++++++++++++++++++++
>  docs/qmp-intro.txt            |  87 -----------------------
>  docs/writing-qmp-commands.txt |   2 +-
>  4 files changed, 222 insertions(+), 88 deletions(-)
>  create mode 100644 docs/qemu-ga-ref.texi
>  create mode 100644 docs/qemu-qmp-ref.texi
>  delete mode 100644 docs/qmp-intro.txt
>
> diff --git a/docs/qemu-ga-ref.texi b/docs/qemu-ga-ref.texi
> new file mode 100644
> index 0000000..ad90712
> --- /dev/null
> +++ b/docs/qemu-ga-ref.texi
> @@ -0,0 +1,65 @@
> +\input texinfo
> +@setfilename qemu-ga-ref.info
> +
> +@exampleindent 0
> +@paragraphindent 0
> +
> +@settitle QEMU Guest Agent Protocol Reference
> +
> +@copying
> +This is the QEMU Guest Agent Protocol reference manual.
> +
> +Copyright @copyright{} 2016 The QEMU Project developers

Need something on permissions, because without, we don't grant any.
Since much of the contents comes from existing files without an explicit
license notice, I guess we need to stick to GPLv2+.  Here's my try,
patterned after the notice carried by "The Debian Administrator's
Handbook"[*]:

   @quotation

   This manual is free documentation: you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation, either version 2 of the
   License, or (at your option) any later version.

   This manual is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this manual.  If not, see http://www.gnu.org/licenses/.
   @end quotation

> +@end copying
> +
> +@ifinfo
> +@dircategory QEMU
> +@direntry
> +* QEMU-GA-Ref: (qemu-ga-ref).   QEMU Guest Agent Protocol Reference
> +@end direntry
> +@end ifinfo

I don't think the redundant @ifinfo buys us anything.

> +
> +@titlepage
> +@title Guest Agent Protocol Reference Manual
> +@subtitle QEMU version @value{VERSION}
> +@page
> +@vskip 0pt plus 1filll
> +@insertcopying
> +@end titlepage
> +
> +@contents
> +
> +@ifnottex
> +@node Top
> +@top QEMU Guest Agent protocol reference
> +@end ifnottex
> +
> +@menu
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> +@end menu
> +
> +@node API Reference
> +@chapter API Reference
> +
> +@c for texi2pod:
> +@c man begin DESCRIPTION
> +
> +@include qemu-ga-qapi.texi
> +
> +@c man end
> +
> +@c man begin SEEALSO
> +The HTML documentation of QEMU for more information.
> +@c man end
> +
> +@node Commands and Events Index
> +@unnumbered Commands and Events Index
> +@printindex fn
> +
> +@node Data Types Index
> +@unnumbered Data Types Index
> +@printindex tp
> +
> +@bye
> diff --git a/docs/qemu-qmp-ref.texi b/docs/qemu-qmp-ref.texi
> new file mode 100644
> index 0000000..c1740ae
> --- /dev/null
> +++ b/docs/qemu-qmp-ref.texi
> @@ -0,0 +1,156 @@

Comments on the previous file apply.

> +\input texinfo
> +@setfilename qemu-qmp-ref.info
> +
> +@exampleindent 0
> +@paragraphindent 0
> +
> +@settitle QEMU QMP Reference Manual
> +
> +@copying
> +This is the QEMU QMP reference manual.
> +
> +Copyright @copyright{} 2016 The QEMU Project developers
> +@end copying
> +
> +@ifinfo
> +@dircategory QEMU
> +@direntry
> +* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual
> +@end direntry
> +@end ifinfo
> +
> +@titlepage
> +@title QMP Reference Manual
> +@subtitle QEMU version @value{VERSION}
> +@page
> +@vskip 0pt plus 1filll
> +@insertcopying
> +@end titlepage
> +
> +@contents
> +
> +@ifnottex
> +@node Top
> +@top QEMU QMP reference
> +@end ifnottex
> +
> +@menu
> +* Introduction::
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> +@end menu
[Skipping chapter Introduction...]
> +@node API Reference
> +@chapter API Reference
> +
> +@c for texi2pod:
> +@c man begin DESCRIPTION
> +
> +@include qemu-qapi.texi
> +
> +@c man end
> +
> +@c man begin SEEALSO
> +The HTML documentation of QEMU for more precise information.
> +@c man end
> +
> +@node Commands and Events Index
> +@unnumbered Commands and Events Index
> +@printindex fn
> +
> +@node Data Types Index
> +@unnumbered Data Types Index
> +@printindex tp
> +
> +@bye
> diff --git a/docs/qmp-intro.txt b/docs/qmp-intro.txt
> deleted file mode 100644
> index f6a3a03..0000000
> --- a/docs/qmp-intro.txt
> +++ /dev/null
[Skipping...]
> diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
> index 44c14db..de54977 100644
> --- a/docs/writing-qmp-commands.txt
> +++ b/docs/writing-qmp-commands.txt
[Skipping...]


[*] https://www.debian.org/doc/manuals/debian-handbook/