should we have a new 'tools' manual?

should we have a new 'tools' manual?

[Peter Maydell]

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

Re: should we have a new 'tools' manual?

[Daniel P. Berrangé]

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 :|

Re: should we have a new 'tools' manual?

[Paolo Bonzini]

[-- 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 --]

Re: should we have a new 'tools' manual?

[Eric Blake]

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

Re: should we have a new 'tools' manual?

[Paolo Bonzini]

[-- 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 --]

Re: should we have a new 'tools' manual?

[Dr. David Alan Gilbert]

* 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

Re: should we have a new 'tools' manual?

[Peter Maydell]

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

Re: should we have a new 'tools' manual?

[Aleksandar Markovic]

[-- 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 --]

Re: should we have a new 'tools' manual?

[Peter Maydell]

On Mon, 17 Feb 2020 at 14:49, Aleksandar Markovic
<aleksandar.m.mail@gmail.com> wrote:
> But, we also should create some sort of action item lists for appropriate people about completing existing and/or creating missing documentation parts.

https://wiki.qemu.org/Features/Documentation is where I've
been tracking progress on this.

thanks
-- PMM

Re: should we have a new 'tools' manual?

[G 3]

[-- Attachment #1: Type: text/plain, Size: 1219 bytes --]

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

I think adding a tool section is a good idea and a more natural fit for
something like qemu-img. I think a tool is a program that is not QEMU but
comes with QEMU.

[-- Attachment #2: Type: text/html, Size: 1560 bytes --]