[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 05/11] docs: add qapi texi template
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v2 05/11] docs: add qapi texi template |
Date: |
Thu, 27 Oct 2016 16:55:40 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Marc-André Lureau <address@hidden> writes:
> The qapi2texi scripts uses a template for the texi file. Since we are
> going to generate the documentation in multiple formats, move qmp-intro
> to qemu-qapi template. (it would be nice to write something similar for
> qemu-ga, but this is left for a future patch)
>
> Signed-off-by: Marc-André Lureau <address@hidden>
I'm not exactly a Texinfo expert, but I can compare to the Texinfo
manual.
Lots of comments below. Please don't let them discourage you! Your two
manuals are pretty slick already, and a most welcome step forward.
> ---
> docs/qemu-ga-qapi.template.texi | 58 ++++++++++++++++
> docs/qemu-qapi.template.texi | 148
> ++++++++++++++++++++++++++++++++++++++++
> docs/qmp-intro.txt | 87 -----------------------
> 3 files changed, 206 insertions(+), 87 deletions(-)
> create mode 100644 docs/qemu-ga-qapi.template.texi
> create mode 100644 docs/qemu-qapi.template.texi
> delete mode 100644 docs/qmp-intro.txt
>
> diff --git a/docs/qemu-ga-qapi.template.texi b/docs/qemu-ga-qapi.template.texi
> new file mode 100644
> index 0000000..3ddbf56
> --- /dev/null
> +++ b/docs/qemu-ga-qapi.template.texi
> @@ -0,0 +1,58 @@
> +\input texinfo
The Texinfo manual uses
\input texinfo @c -*-texinfo-*-
but my version of Emacs seems to be fine without this.
> address@hidden qemu-ga-qapi
Not wrong, but the Texinfo manual recommends to replace the extension
(here: .texi) with .info, so let's do that:
@setfilename qemu-ga-qapi.info
> address@hidden en
This overrides the default en_US to just en. Is that what we want?
> address@hidden 0
> address@hidden 0
> +
> address@hidden QEMU-GA QAPI Reference Manual
What is "QAPI", and why would the reader care? I think the manual is
about the QEMU Guest Agent Protocol. The fact that its implementation
relies on QAPI is immaterial here. What about:
@settitle QEMU Guest Agent Protocol Reference
But then the filenames are off. Rename to qemu-ga-ref.*.
> +
I think we need a copyright note. Something like:
@copying
This is the QEMU Guest Agent QAPI reference manual.
Copyright @copyright{} 2016 The QEMU Project developers
@quotation
Permission is granted to ...
@end quotation
@end copying
> address@hidden
@dircategory QEMU
Should be added to qemu-doc.texi as well.
> address@hidden
> +* QEMU-GA-QAPI: (qemu-doc). QEMU-GA QAPI Reference Manual
Pasto: (qemu-doc)
The description should start at column 32, not 31.
If we retitle and rename as suggested, this becomes:
* QEMU-GA-Ref: (qemu-ga-ref): QEMU Guest Agent Protocol Reference
> address@hidden direntry
> address@hidden ifinfo
Are you sure we need @ifinfo?
> +
> address@hidden
> address@hidden
> address@hidden 7
> address@hidden @titlefont{{QEMU Guest Agent {version}}}
{version} seems to get replaced by qapi2texi.py. Worth a comment.
> address@hidden 1
> address@hidden @titlefont{{QAPI Reference Manual}}
Protocol Reference Manual
> address@hidden 3
Isn't @sp right before @end titlepage redundant?
We need to include the copyright notice:
@page
@vskip 0pt plus 1filll
@insertcopying
> address@hidden titlepage
> address@hidden iftex
Are you sure we need @iftex?
We can also let Texinfo do the spacing, like this:
@titlepage
@title QEMU Guest Agent {version}
@subtitle Protocol Reference Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
The @title isn't really the title, though. Could reshuffle things a
bit, e.g.
@title QEMU Guest Agent Protocol Reference Manual
@subtitle for QEMU {version}
Your choice.
The examples in Texinfo manual Appendix C "Sample Texinfo Files" have
@contents right here, after the title page.
> +
> address@hidden
> address@hidden Top
> address@hidden
@top QEMU Guest Agent QAPI reference
> +
> +This is the QEMU Guest Agent QAPI reference for QEMU {version}.
"protocol reference manual for"
According to the Texinfo manual's examples, the @end ifnottex goes
here...
> +
> address@hidden
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> address@hidden menu
> +
> address@hidden ifnottex
... and not here.
> +
> address@hidden
Suggest to move this up, as mentioned above.
> +
> address@hidden API Reference
> address@hidden API Reference
> +
> address@hidden man begin DESCRIPTION
What does this @c man magic do? Suggest to explain in a comment.
> +{qapi}
This seems to get replaced with the generated reference documentation by
qapi2texi.py. Worth a comment.
> address@hidden man end
> +
> address@hidden man begin SEEALSO
> +The HTML documentation of QEMU for more precise information.
> address@hidden man end
More @c man magic.
> +
> address@hidden Commands and Events Index
> address@hidden Commands and Events Index
> address@hidden fn
Blank line here, please.
> address@hidden Data Types Index
> address@hidden Data Types Index
> address@hidden tp
And here.
> address@hidden
> diff --git a/docs/qemu-qapi.template.texi b/docs/qemu-qapi.template.texi
> new file mode 100644
> index 0000000..102c8d9
> --- /dev/null
> +++ b/docs/qemu-qapi.template.texi
The comments above largely apply; I won't repeat them.
> @@ -0,0 +1,148 @@
> +\input texinfo
> address@hidden qemu-qapi
> address@hidden en
> address@hidden 0
> address@hidden 0
> +
> address@hidden QEMU QAPI Reference Manual
Again, QAPI is detail; it's the QEMU QMP reference manual. Except it
has more than just QMP, because we choose to use qapi-schema.json for
purely internal types in addition to QMP.
Options:
* Claim this is the QMP reference manual, include the internal types
anyway.
* Filter out the internal types automatically, similar to
qmp-introspect.py.
* Filter out the internal types manually, by annotating them in the
schema. Feels error-prone.
* Split the QAPI schema.
* Reflect the curious mix of QMP protocol and internal data type
reference in the title.
We don't need a perfect solution to commit this, but an understanding of
what we want to do would be nice.
> +
> address@hidden
> address@hidden
> +* QEMU: (qemu-doc). QEMU QAPI Reference Manual
> address@hidden direntry
> address@hidden ifinfo
> +
> address@hidden
> address@hidden
> address@hidden 7
> address@hidden @titlefont{{QEMU Emulator {version}}}
> address@hidden 1
> address@hidden @titlefont{{QAPI Reference Manual}}
> address@hidden 3
> address@hidden titlepage
> address@hidden iftex
> +
> address@hidden
> address@hidden Top
> address@hidden
> +
> +This is the QMP QAPI reference for QEMU {version}.
> +
> address@hidden
> +* Introduction::
> +* API Reference::
> +* Commands and Events Index::
> +* Data Types Index::
> address@hidden menu
> +
> address@hidden ifnottex
> +
> address@hidden
> +
> address@hidden Introduction
> address@hidden Introduction
> +
> +The QEMU Machine Protocol (@acronym{{QMP}}) allows applications to
> +operate a QEMU instance.
> +
> +QMP is @uref{{http://www.json.org, JSON}} based and features the
> +following:
> +
> address@hidden @minus
@bullet is more common. Matter of taste.
> address@hidden
> +Lightweight, text-based, easy to parse data format
Suggest "plain text" instead of "text-based".
JSON is "easy to parse" until you hit the potholes in its specification.
See "Parsing JSON is a Minefield" <http://seriot.ch/parsing_json.html>.
QMP provides the following features:
@itemize @bullet
@item
Simple @uref{{http://www.json.org, JSON}} syntax
> address@hidden
> +Asynchronous messages support (ie. events)
i.e.
But I'd say
@item
Synchronous commands and replies
@item
Asynchronous messages ("events")
> address@hidden
> +Capabilities Negotiation
I'd add
@item
Introspection
> address@hidden itemize
> +
> +For detailed information on QEMU Machine Protocol, the specification
> +is in @file{{qmp-spec.txt}}.
> +
> address@hidden Usage
> +
> +You can use the @option{{-qmp}} option to enable QMP. For example, the
> +following makes QMP available on localhost port 4444:
> +
> address@hidden
> +$ qemu [...] -qmp tcp:localhost:4444,server,nowait
> address@hidden example
> +
> +However, for more flexibility and to make use of more options, the
> address@hidden command-line option should be used. For instance, the
> +following example creates one HMP instance (human monitor) on stdio
> +and one QMP instance on localhost port 4444:
This sounds a bit like we don't want people to use -qmp. What about
However, for more flexibility and to make use of more options, the
@option{{-mon}} command-line option should be used. For instance, the
following example creates one HMP instance (human monitor) on stdio
and one QMP instance on localhost port 4444:
> +
> address@hidden
> +$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
> + -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
> + -mon chardev=mon1,mode=control,pretty=on
> address@hidden example
Not sure we want to drag in HMP here.
> +
> +Please, refer to QEMU's manpage for more information.
Drop the comma.
Hrmmm, I just realized this is merely moved from qmp-intro.txt. I guess
I should read your commit message before your patch %-)
I'm not sure a *reference* manual is a good home for an *introduction*
to use. It's certainly not where I'd look first.
We can decide this isn't a reference manual after all, and change title,
file name and so forth accordingly.
Or we can stick to the reference manual idea, and include qmp-intro.txt
by reference.
> +
> address@hidden Simple testing
> +
> +To manually test QMP one can connect with telnet and issue commands by
> +hand:
> +
> address@hidden
> +$ telnet localhost 4444
> +Trying 127.0.0.1...
> +Connected to localhost.
> +Escape character is '^]'.
> address@hidden
> + "QMP": @{{
> + "version": @{{
> + "qemu": @{{
> + "micro": 50,
> + "minor": 6,
> + "major": 1
> + @}},
> + "package": ""
> + @}},
> + "capabilities": [
> + ]
> + @}}
> address@hidden
> +
> address@hidden "execute": "qmp_capabilities" @}}
> address@hidden
> + "return": @{{
> + @}}
> address@hidden
> +
> address@hidden "execute": "query-status" @}}
> address@hidden
> + "return": @{{
> + "status": "prelaunch",
> + "singlestep": false,
> + "running": false
> + @}}
> address@hidden
> address@hidden example
> +
> address@hidden Wiki
> +
> +Please refer to the @uref{{http://wiki.qemu-project.org/QMP, QMP QEMU
> + wiki page}} for more details on QMP.
> +
> address@hidden API Reference
> address@hidden API Reference
> +
> address@hidden man begin DESCRIPTION
> +{qapi}
> 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
> @@ -1,87 +0,0 @@
> - QEMU Machine Protocol
> - =====================
> -
> -Introduction
> -------------
> -
> -The QEMU Machine Protocol (QMP) allows applications to operate a
> -QEMU instance.
> -
> -QMP is JSON[1] based and features the following:
> -
> -- Lightweight, text-based, easy to parse data format
> -- Asynchronous messages support (ie. events)
> -- Capabilities Negotiation
> -
> -For detailed information on QMP's usage, please, refer to the following
> files:
> -
> -o qmp-spec.txt QEMU Machine Protocol current specification
> -o qmp-commands.txt QMP supported commands (auto-generated at build-time)
> -o qmp-events.txt List of available asynchronous events
> -
> -[1] http://www.json.org
> -
> -Usage
> ------
> -
> -You can use the -qmp option to enable QMP. For example, the following
> -makes QMP available on localhost port 4444:
> -
> -$ qemu [...] -qmp tcp:localhost:4444,server,nowait
> -
> -However, for more flexibility and to make use of more options, the -mon
> -command-line option should be used. For instance, the following example
> -creates one HMP instance (human monitor) on stdio and one QMP instance
> -on localhost port 4444:
> -
> -$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
> - -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
> - -mon chardev=mon1,mode=control,pretty=on
> -
> -Please, refer to QEMU's manpage for more information.
> -
> -Simple Testing
> ---------------
> -
> -To manually test QMP one can connect with telnet and issue commands by hand:
> -
> -$ telnet localhost 4444
> -Trying 127.0.0.1...
> -Connected to localhost.
> -Escape character is '^]'.
> -{
> - "QMP": {
> - "version": {
> - "qemu": {
> - "micro": 50,
> - "minor": 6,
> - "major": 1
> - },
> - "package": ""
> - },
> - "capabilities": [
> - ]
> - }
> -}
> -
> -{ "execute": "qmp_capabilities" }
> -{
> - "return": {
> - }
> -}
> -
> -{ "execute": "query-status" }
> -{
> - "return": {
> - "status": "prelaunch",
> - "singlestep": false,
> - "running": false
> - }
> -}
> -
> -Please, refer to the qapi-schema.json file for a complete command reference.
> -
> -QMP wiki page
> --------------
> -
> -http://wiki.qemu-project.org/QMP
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: [Qemu-devel] [PATCH v2 05/11] docs: add qapi texi template,
Markus Armbruster <=