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