[Qemu-devel] RFC: unified --help information

[Qemu-devel] RFC: unified --help information

[Eric Blake]

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

I noticed that some utilities provide a handy link to the website (which
in turn connects the users to bug database, mailing list, online docs,
...); for example, look at 'ls --help | tail -n3':

GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/ls>
or available locally via: info '(coreutils) ls invocation'

or 'm4 --help | tail -n3':
Report bugs to: bug-m4@gnu.org
GNU M4 home page: <http://www.gnu.org/software/m4/>
General help using GNU software: <http://www.gnu.org/gethelp/>

In our executables, we are rather inconsistent with --help

qemu-nbd mentions: Report bugs to <qemu-devel@nongnu.org>
qemu-ga mentions: Report bugs to <mdroth@linux.vnet.ibm.com>

while qemu-system-*, qemu-img, and qemu-io mention nothing at all.  Is
it worth unifying these to all mention qemu-devel@nongnu.org as the
primary bug-report site, and/or to add mention of <http://qemu.org> as a
site for further information?

Likewise, with --version, qemu-io and qemu-ga lack the git suffix
present in qemu-system-* and just added in qemu-nbd.

I can submit patches to make things consistent, and think it is 2.10
material, but first want to get consensus on what the behavior should be.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] RFC: unified --help information

[Paolo Bonzini]

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

On 26/07/2017 12:53, Eric Blake wrote:
> 
> GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
> Full documentation at: <http://www.gnu.org/software/coreutils/ls>
> or available locally via: info '(coreutils) ls invocation'
> 
> or 'm4 --help | tail -n3':
> Report bugs to: bug-m4@gnu.org
> GNU M4 home page: <http://www.gnu.org/software/m4/>
> General help using GNU software: <http://www.gnu.org/gethelp/>
> 
> In our executables, we are rather inconsistent with --help
> 
> qemu-nbd mentions: Report bugs to <qemu-devel@nongnu.org>
> qemu-ga mentions: Report bugs to <mdroth@linux.vnet.ibm.com>
> 
> while qemu-system-*, qemu-img, and qemu-io mention nothing at all.  Is
> it worth unifying these to all mention qemu-devel@nongnu.org as the
> primary bug-report site, and/or to add mention of <http://qemu.org> as a
> site for further information?

I think we should point to a more specific bugreport URL.

Currently it's http://wiki.qemu.org/Contribute/ReportABug.  If we want
an URL on qemu.org, we can either add a redirect from qemu.org to the
wiki, or move the contents to qemu.org (it's static enough that it
shouldn't be a big issue).  I've sent out a patch for the latter.

> Likewise, with --version, qemu-io and qemu-ga lack the git suffix
> present in qemu-system-* and just added in qemu-nbd.
> 
> I can submit patches to make things consistent, and think it is 2.10
> material, but first want to get consensus on what the behavior should be.

I agree it's better to be consistent.

Paolo


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [Qemu-devel] RFC: unified --help information

[Eric Blake]

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

On 07/26/2017 06:11 AM, Paolo Bonzini wrote:

>>
>> qemu-nbd mentions: Report bugs to <qemu-devel@nongnu.org>
>> qemu-ga mentions: Report bugs to <mdroth@linux.vnet.ibm.com>
>>
>> while qemu-system-*, qemu-img, and qemu-io mention nothing at all.  Is
>> it worth unifying these to all mention qemu-devel@nongnu.org as the
>> primary bug-report site, and/or to add mention of <http://qemu.org> as a
>> site for further information?
> 
> I think we should point to a more specific bugreport URL.
> 
> Currently it's http://wiki.qemu.org/Contribute/ReportABug.  If we want
> an URL on qemu.org, we can either add a redirect from qemu.org to the
> wiki, or move the contents to qemu.org (it's static enough that it
> shouldn't be a big issue).  I've sent out a patch for the latter.

So something like these two lines (via a macro) in all of the
executables, ideally at the tail end of --help output?

See <https://qemu.org/contribute/report-a-bug> for bug reports.
More information on the qemu project at <https://qemu.org>

(assuming your recent patch goes in).  I'm also open to bikeshedding on
better wording, or requests on which content is most useful vs. too verbose.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] RFC: unified --help information

[Peter Maydell]

On 26 July 2017 at 12:22, Eric Blake <eblake@redhat.com> wrote:
> So something like these two lines (via a macro) in all of the
> executables, ideally at the tail end of --help output?
>
> See <https://qemu.org/contribute/report-a-bug> for bug reports.
> More information on the qemu project at <https://qemu.org>

Text looks good to me. A minor nit: better not use https://
URLs til we fix the website (which currently makes firefox
warn about an invalid security certificate...)

Would be good to put this in GUI about dialog boxes
and the like too.

thanks
-- PMM