* Re: should we have a new 'tools' manual?
2020-02-07 11:50 should we have a new 'tools' manual? Peter Maydell
@ 2020-02-07 11:59 ` Daniel P. Berrangé
2020-02-07 12:37 ` Paolo Bonzini
` (3 subsequent siblings)
4 siblings, 0 replies; 10+ messages in thread
From: Daniel P. Berrangé @ 2020-02-07 11:59 UTC (permalink / raw)
To: Peter Maydell
Cc: Paolo Bonzini, QEMU Developers, Stefan Hajnoczi, Dr. David Alan Gilbert
On Fri, Feb 07, 2020 at 11:50:37AM +0000, Peter Maydell wrote:
> So far we've been converting docs to Sphinx and assigning them
> to manuals according to the division originally set out by
> Paolo on the wiki: https://wiki.qemu.org/Features/Documentation
>
> * QEMU User-mode Emulation User's Guide (docs/user)
> * QEMU System Emulation User's Guide (docs/system)
> * QEMU System Emulation Management and Interoperability Guide (docs/interop)
> * QEMU System Emulation Guest Hardware Specifications (docs/specs)
> * QEMU Developer's Guide (docs/devel, not shipped to end-users)
>
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
> * qemu-img
> * qemu-nbd
> * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
>
> The proposal from Dan and David was that we should add a sixth
> top-level manual
> * QEMU Tools Guide (docs/tools)
>
> which would be a more coherent place for these to live.
>
> This seems like a good idea to me -- do people agree? What's
> our definition of a "tool", or do we just know one when we see it?
> What in particular should go in tools/ ?
There are essentially two consumers of our docs
- Sysadmins running / interacting with QEMU
- Application developers building QEMU mgmt tools
In the sysadmin use case, they'll primarily care about docs describing
the system emulator configuration & usage, and the various tools usage.
The app devs will care about nearly all of our documentation, except for
stuff that is purely QEMU internals.
The downside of mixing tools into the general "interop" doc is that it
makes it harder to find IMHO. Thus having a dedicated "tools" doc will
be a useful grouping for sysadmins to quickly find docs relevant to
daily admin tasks.
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: should we have a new 'tools' manual?
2020-02-07 11:50 should we have a new 'tools' manual? Peter Maydell
2020-02-07 11:59 ` Daniel P. Berrangé
@ 2020-02-07 12:37 ` Paolo Bonzini
2020-02-07 14:32 ` Eric Blake
` (2 subsequent siblings)
4 siblings, 0 replies; 10+ messages in thread
From: Paolo Bonzini @ 2020-02-07 12:37 UTC (permalink / raw)
To: Peter Maydell
Cc: Daniel P. Berrange, QEMU Developers, Stefan Hajnoczi,
Dr. David Alan Gilbert
[-- Attachment #1: Type: text/plain, Size: 1287 bytes --]
Sure. However I would keep qemu-ga in interop/.
Paolo
Il ven 7 feb 2020, 12:50 Peter Maydell <peter.maydell@linaro.org> ha
scritto:
> So far we've been converting docs to Sphinx and assigning them
> to manuals according to the division originally set out by
> Paolo on the wiki: https://wiki.qemu.org/Features/Documentation
>
> * QEMU User-mode Emulation User's Guide (docs/user)
> * QEMU System Emulation User's Guide (docs/system)
> * QEMU System Emulation Management and Interoperability Guide
> (docs/interop)
> * QEMU System Emulation Guest Hardware Specifications (docs/specs)
> * QEMU Developer's Guide (docs/devel, not shipped to end-users)
>
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
> * qemu-img
> * qemu-nbd
> * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
>
> The proposal from Dan and David was that we should add a sixth
> top-level manual
> * QEMU Tools Guide (docs/tools)
>
> which would be a more coherent place for these to live.
>
> This seems like a good idea to me -- do people agree? What's
> our definition of a "tool", or do we just know one when we see it?
> What in particular should go in tools/ ?
>
> thanks
> -- PMM
>
>
[-- Attachment #2: Type: text/html, Size: 1799 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: should we have a new 'tools' manual?
2020-02-07 11:50 should we have a new 'tools' manual? Peter Maydell
2020-02-07 11:59 ` Daniel P. Berrangé
2020-02-07 12:37 ` Paolo Bonzini
@ 2020-02-07 14:32 ` Eric Blake
2020-02-07 14:42 ` Paolo Bonzini
2020-02-07 15:24 ` Dr. David Alan Gilbert
2020-02-17 14:36 ` Peter Maydell
4 siblings, 1 reply; 10+ messages in thread
From: Eric Blake @ 2020-02-07 14:32 UTC (permalink / raw)
To: Peter Maydell, QEMU Developers
Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
Stefan Hajnoczi
On 2/7/20 5:50 AM, Peter Maydell wrote:
> So far we've been converting docs to Sphinx and assigning them
> to manuals according to the division originally set out by
> Paolo on the wiki: https://wiki.qemu.org/Features/Documentation
>
> * QEMU User-mode Emulation User's Guide (docs/user)
> * QEMU System Emulation User's Guide (docs/system)
> * QEMU System Emulation Management and Interoperability Guide (docs/interop)
> * QEMU System Emulation Guest Hardware Specifications (docs/specs)
> * QEMU Developer's Guide (docs/devel, not shipped to end-users)
>
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
> * qemu-img
> * qemu-nbd
> * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
>
> The proposal from Dan and David was that we should add a sixth
> top-level manual
> * QEMU Tools Guide (docs/tools)
>
> which would be a more coherent place for these to live.
>
> This seems like a good idea to me -- do people agree? What's
> our definition of a "tool", or do we just know one when we see it?
> What in particular should go in tools/ ?
Moving the documentation for both qemu-img and qemu-nbd to tools/
instead of interop/ makes sense to me. I don't know if qemu-io is
documented well (it's more of an internal tool than a user-visible
tool), but it could also live in tools/.
As it is, I would love to move toplevel/qemu-nbd.c into a
tools/qemu-nbd.c directory. But when I spent a mere 30 minutes seeing
what it would take, I quickly learned that there is enough arcane
Makefile magic going on in building from subdirectories that it wasn't
worth my time to figure out how, especially if all that magic gets
rewritten anyway during Paolo's conversion to meson.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: should we have a new 'tools' manual?
2020-02-07 14:32 ` Eric Blake
@ 2020-02-07 14:42 ` Paolo Bonzini
0 siblings, 0 replies; 10+ messages in thread
From: Paolo Bonzini @ 2020-02-07 14:42 UTC (permalink / raw)
To: Eric Blake
Cc: Peter Maydell, Daniel P. Berrange, QEMU Developers,
Stefan Hajnoczi, Dr. David Alan Gilbert
[-- Attachment #1: Type: text/plain, Size: 617 bytes --]
Il ven 7 feb 2020, 15:32 Eric Blake <eblake@redhat.com> ha scritto:
> But when I spent a mere 30 minutes seeing
> what it would take, I quickly learned that there is enough arcane
> Makefile magic going on in building from subdirectories that it wasn't
> worth my time to figure out how, especially if all that magic gets
> rewritten anyway during Paolo's conversion to meson.
>
Heh, maybe that could be a convincing example. It should be pure code
movement.
> --
> Eric Blake, Principal Software Engineer
> Red Hat, Inc. +1-919-301-3226
> Virtualization: qemu.org | libvirt.org
>
>
[-- Attachment #2: Type: text/html, Size: 1316 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: should we have a new 'tools' manual?
2020-02-07 11:50 should we have a new 'tools' manual? Peter Maydell
` (2 preceding siblings ...)
2020-02-07 14:32 ` Eric Blake
@ 2020-02-07 15:24 ` Dr. David Alan Gilbert
2020-02-17 14:36 ` Peter Maydell
4 siblings, 0 replies; 10+ messages in thread
From: Dr. David Alan Gilbert @ 2020-02-07 15:24 UTC (permalink / raw)
To: Peter Maydell
Cc: Paolo Bonzini, Daniel P. Berrange, QEMU Developers, Stefan Hajnoczi
* Peter Maydell (peter.maydell@linaro.org) wrote:
> So far we've been converting docs to Sphinx and assigning them
> to manuals according to the division originally set out by
> Paolo on the wiki: https://wiki.qemu.org/Features/Documentation
>
> * QEMU User-mode Emulation User's Guide (docs/user)
> * QEMU System Emulation User's Guide (docs/system)
> * QEMU System Emulation Management and Interoperability Guide (docs/interop)
> * QEMU System Emulation Guest Hardware Specifications (docs/specs)
> * QEMU Developer's Guide (docs/devel, not shipped to end-users)
>
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
> * qemu-img
> * qemu-nbd
> * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
>
> The proposal from Dan and David was that we should add a sixth
> top-level manual
> * QEMU Tools Guide (docs/tools)
>
> which would be a more coherent place for these to live.
>
> This seems like a good idea to me -- do people agree? What's
> our definition of a "tool", or do we just know one when we see it?
> What in particular should go in tools/ ?
The virtiofs security guide that Stefan wrote doesn't really fit in the existing ones.
It's not about the use of qemu itself so it's not docs/user or
docs/system.
It's not specifying protocols or commands so it's not docs/interop.
It's not hardware.
And it's for end users not developers, so it's not docs/devel.
However, there's a question about whether it makes sense to bundle
the docs for all of the tools into one big manual when they're
really independent.
Dave
> thanks
> -- PMM
>
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: should we have a new 'tools' manual?
2020-02-07 11:50 should we have a new 'tools' manual? Peter Maydell
` (3 preceding siblings ...)
2020-02-07 15:24 ` Dr. David Alan Gilbert
@ 2020-02-17 14:36 ` Peter Maydell
2020-02-17 14:48 ` Aleksandar Markovic
4 siblings, 1 reply; 10+ messages in thread
From: Peter Maydell @ 2020-02-17 14:36 UTC (permalink / raw)
To: QEMU Developers
Cc: Paolo Bonzini, Daniel P. Berrange, Dr. David Alan Gilbert,
Stefan Hajnoczi
On Fri, 7 Feb 2020 at 11:50, Peter Maydell <peter.maydell@linaro.org> wrote:
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
> * qemu-img
> * qemu-nbd
> * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
>
> The proposal from Dan and David was that we should add a sixth
> top-level manual
> * QEMU Tools Guide (docs/tools)
>
> which would be a more coherent place for these to live.
OK, consensus seems to be that this is a good idea. Here's
what I specifically intend to move:
docs/interop/qemu-img.rst
docs/interop/qemu-nbd.rst
docs/interop/virtfs-proxy-helper.rst
docs/interop/qemu-trace-stap.rst
docs/interop/virtiofsd.rst
Nothing else (in particular including qemu-ga.rst) moves;
none of the as-yet unconverted documents need to move either.
thanks
-- PMM
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: should we have a new 'tools' manual?
2020-02-17 14:36 ` Peter Maydell
@ 2020-02-17 14:48 ` Aleksandar Markovic
2020-02-17 15:01 ` Peter Maydell
0 siblings, 1 reply; 10+ messages in thread
From: Aleksandar Markovic @ 2020-02-17 14:48 UTC (permalink / raw)
To: Peter Maydell
Cc: Paolo Bonzini, Daniel P. Berrange, QEMU Developers,
Stefan Hajnoczi, Dr. David Alan Gilbert
[-- Attachment #1: Type: text/plain, Size: 1276 bytes --]
3:37 PM Pon, 17.02.2020. Peter Maydell <peter.maydell@linaro.org> је
написао/ла:
>
> On Fri, 7 Feb 2020 at 11:50, Peter Maydell <peter.maydell@linaro.org>
wrote:
> > but some of our documentation has always been a bit of an awkward
> > fit into this classification:
> > * qemu-img
> > * qemu-nbd
> > * virtfs-proxy-helper
> > etc. I've tended to put these things into interop/.
> >
> > The proposal from Dan and David was that we should add a sixth
> > top-level manual
> > * QEMU Tools Guide (docs/tools)
> >
> > which would be a more coherent place for these to live.
>
> OK, consensus seems to be that this is a good idea.
Hi,
I add the same good opinion to the consensus.
But, we also should create some sort of action item lists for appropriate
people about completing existing and/or creating missing documentation
parts.
Truly yours,
Aleksandar
> Here's
> what I specifically intend to move:
> docs/interop/qemu-img.rst
> docs/interop/qemu-nbd.rst
> docs/interop/virtfs-proxy-helper.rst
> docs/interop/qemu-trace-stap.rst
> docs/interop/virtiofsd.rst
>
> Nothing else (in particular including qemu-ga.rst) moves;
> none of the as-yet unconverted documents need to move either.
>
> thanks
> -- PMM
>
[-- Attachment #2: Type: text/html, Size: 1760 bytes --]
^ permalink raw reply [flat|nested] 10+ messages in thread