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

[Markus Armbruster]

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

Marc-André Lureau <address@hidden> 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 <address@hidden>
> ---
>  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
> address@hidden qemu-ga-ref.info
> +
> address@hidden 0
> address@hidden 0
> +
> address@hidden QEMU Guest Agent Protocol Reference
> +
> address@hidden
> +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

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

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

> +
> address@hidden
> address@hidden Guest Agent Protocol Reference Manual
> address@hidden QEMU version @value{VERSION}
> address@hidden
> address@hidden 0pt plus 1filll
> address@hidden
> address@hidden titlepage
> +
> address@hidden
> +
> address@hidden
> address@hidden Top
> address@hidden QEMU Guest Agent protocol reference
> address@hidden ifnottex
> +
> address@hidden
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> address@hidden menu
> +
> address@hidden API Reference
> address@hidden API Reference
> +
> address@hidden for texi2pod:
> address@hidden man begin DESCRIPTION
> +
> address@hidden qemu-ga-qapi.texi
> +
> address@hidden man end
> +
> address@hidden man begin SEEALSO
> +The HTML documentation of QEMU for more information.
> address@hidden man end
> +
> address@hidden Commands and Events Index
> address@hidden Commands and Events Index
> address@hidden fn
> +
> address@hidden Data Types Index
> address@hidden Data Types Index
> address@hidden tp
> +
> address@hidden
> 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
> address@hidden qemu-qmp-ref.info
> +
> address@hidden 0
> address@hidden 0
> +
> address@hidden QEMU QMP Reference Manual
> +
> address@hidden
> +This is the QEMU QMP reference manual.
> +
> +Copyright @copyright{} 2016 The QEMU Project developers
> address@hidden copying
> +
> address@hidden
> address@hidden QEMU
> address@hidden
> +* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual
> address@hidden direntry
> address@hidden ifinfo
> +
> address@hidden
> address@hidden QMP Reference Manual
> address@hidden QEMU version @value{VERSION}
> address@hidden
> address@hidden 0pt plus 1filll
> address@hidden
> address@hidden titlepage
> +
> address@hidden
> +
> address@hidden
> address@hidden Top
> address@hidden QEMU QMP reference
> address@hidden ifnottex
> +
> address@hidden
> +* Introduction::
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> address@hidden menu
[Skipping chapter Introduction...]
> address@hidden API Reference
> address@hidden API Reference
> +
> address@hidden for texi2pod:
> address@hidden man begin DESCRIPTION
> +
> address@hidden qemu-qapi.texi
> +
> address@hidden man end
> +
> address@hidden man begin SEEALSO
> +The HTML documentation of QEMU for more precise information.
> address@hidden man end
> +
> address@hidden Commands and Events Index
> address@hidden Commands and Events Index
> address@hidden fn
> +
> address@hidden Data Types Index
> address@hidden Data Types Index
> address@hidden tp
> +
> address@hidden
> 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/