From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39536) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZXBRD-0002bZ-Tf for qemu-devel@nongnu.org; Wed, 02 Sep 2015 13:03:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZXBR9-0004TA-It for qemu-devel@nongnu.org; Wed, 02 Sep 2015 13:03:07 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46982) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZXBR9-0004T2-Ay for qemu-devel@nongnu.org; Wed, 02 Sep 2015 13:03:03 -0400 References: <1440714174-13261-1-git-send-email-lvivier@redhat.com> From: Eric Blake Message-ID: <55E72BC1.7010704@redhat.com> Date: Wed, 2 Sep 2015 11:02:57 -0600 MIME-Version: 1.0 In-Reply-To: <1440714174-13261-1-git-send-email-lvivier@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="Nuwgm1l5kgOxk2BRXbIBfV3HOLQ96xtuX" Subject: Re: [Qemu-devel] [PATCH v3 1/2] Use help sub-sections to create sub-help options List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Laurent Vivier , Paolo Bonzini , qemu-devel@nongnu.org, marcandre.lureau@gmail.com Cc: armbru@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --Nuwgm1l5kgOxk2BRXbIBfV3HOLQ96xtuX Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 08/27/2015 04:22 PM, Laurent Vivier wrote: > As '-help' output is 400 lines long it is not easy > to find information, but generally we know from > which area we want the information. >=20 > As subsections already exist in the help description, > add some command options to only display the wanted > subsection. >=20 > As more is better, this patch adds 13 lines to the -help output: >=20 > -help-standard display standard options > -help-block display block options > -help-usb display usb options > -help-display display display options > -help-machine display machine options > -help-network display network options > -help-character display character options > -help-url display url options > -help-bt display bt options > -help-tpm display tpm options > -help-kernel display kernel options > -help-expert display expert options > -help-object display object options Here you are proposing multiple options, which each cause an exit. If I = do: $ ./x86_64-softmmu/qemu-system-x86_64 --help-block --help-usb I do NOT get usb help, because --help-block already caused an exit. I think a nicer approach might be: --help[=3DLIST] so that I could do: $ ./x86_64-softmmu/qemu-system-x86_64 --help short help, that documents that I can add =3DLIST for more details $ ./x86_64-softmmu/qemu-system-x86_64 --help=3Dblock,usb both the block and usb help blurbs $ ./x86_64-softmmu/qemu-system-x86_64 --help=3Dall all help > Example: >=20 > $ qemu-system-x86_64 -help-kernel > Linux/Multiboot boot specific: > -kernel bzImage use 'bzImage' as kernel image > -append cmdline use 'cmdline' as kernel command line > -initrd file use 'file' as initial ram disk > -dtb file use 'file' as device tree image >=20 > Signed-off-by: Laurent Vivier > --- > v3: add a 2nd patch to add an help section, -help displays only this se= ction > v2: simplify the dance of #define/#undef, thanks to Marc-Andr=C3=A9. I like the idea of breaking help into sections, but think that adding separate options rather than an optional list to a single option is more useful. Also, I think you'll get a better review of v4 if it occurs as a top-level thread. > qemu-options.hx | 150 ++++++++++++++++++++++++++++++++++++++++++++++++= ++++++-- > vl.c | 134 ++++++++++++++++++++++++++++++++++++++++++++++++= ++ > 2 files changed, 280 insertions(+), 4 deletions(-) >=20 > diff --git a/qemu-options.hx b/qemu-options.hx > index 77f5853..49b78df 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -6,17 +6,123 @@ HXCOMM construct option structures, enums and help m= essage for specified > HXCOMM architectures. > HXCOMM HXCOMM can be used for comments, discarded from both texi and C= > =20 > +#if defined(QEMU_HELP_SELECT_STANDARD) || !defined(QEMU_HELP_SELECT) > +#undef QEMU_HELP_SELECT_STANDARD > DEFHEADING(Standard options:) > STEXI > @table @option > ETEXI > =20 > DEF("help", 0, QEMU_OPTION_h, > - "-h or -help display this help and exit\n", QEMU_ARCH_ALL) > + "-h or -help display all help options and exit\n", QEMU_ARCH_A= LL) > STEXI > @item -h > @findex -h > -Display help and exit > +Display all help options and exit > +ETEXI > + > +DEF("help-standard", 0, QEMU_OPTION_h_standard, > + "-help-standard display standard options\n", QEMU_ARCH_ALL) > +STEXI This documents all the sub-helps up front. But I'd rather see a simple '--help' to output at most a screenful of information; if that is not possible, then I'd rather see the sub-helps mentioned at the END of the long help (that is, if I don't know that --help is going to be multiple screenfuls or that subhelps even exist, then the LAST thing left on my screen should be the information that helps me further refine my next command line). > +#if defined(QEMU_HELP_SELECT_EXPERT) || !defined(QEMU_HELP_SELECT) > +#undef QEMU_HELP_SELECT_EXPERT > DEFHEADING(Debug/Expert options:) > STEXI > @table @option > @@ -3510,7 +3649,7 @@ DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vms= tate, > " Output vmstate information in JSON format to file= =2E\n" > " Use the scripts/vmstate-static-checker.py file to= \n" > " check for possible regressions in migration code\= n" > - " by comparing two such vmstate dumps.", > + " by comparing two such vmstate dumps.\n", > QEMU_ARCH_ALL) It might help to separate minor whitespace changes (adding or rearranging where newlines appear) to be a different patch than the one turning on grouping. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --Nuwgm1l5kgOxk2BRXbIBfV3HOLQ96xtuX Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJV5yvBAAoJEKeha0olJ0NqLiYH/ij2cTRtBSertmNtLGvGYbyg 07UqMDqhDKk9K/b2+ZAtX7/6/2I+Y2+2lq/nTqsK6+mRxp8i+bdb2jqclc2a+URG JQ63BO/itOewvzjoIip81L7+TI6C6X/P+uo1FKZPJpx/A/EAWVHf0nngSM+9es7v WWopbXYkJTuPqqSgxwWO3IruAU7PMHQvutBhVji9XaB1yG3Pt+YU+iuHPF5JKhB9 VoXovML/FYV0nVNVqa+63LZplwqL4xdK41G9QS2dvqgeMGLtL5woXEhnGx5NmlOk F5Vh16vxo+43ZIgL3lj3uuzp9mmi/T//xlDTWdzZA6dR9TxPGhyfhyXwP7E5oVY= =7Ewa -----END PGP SIGNATURE----- --Nuwgm1l5kgOxk2BRXbIBfV3HOLQ96xtuX--