On Thu, Jun 07, 2018 at 09:50:41AM +0200, Thomas Huth wrote: > On 07.06.2018 08:57, Markus Armbruster wrote: > > Thomas Huth <th...@redhat.com> writes: > > > >> On 05.06.2018 00:40, Eric Blake wrote: > >>> On 06/04/2018 05:34 AM, Thomas Huth wrote: > >>>> On 04.06.2018 09:18, Markus Armbruster wrote: > >>>>> Roman Kagan <rka...@virtuozzo.com> writes: > >>>>> > >>>>>> Add helper functions to query the block drivers actually supported by > >>>>>> QEMU using "-drive format=?". This allows to skip certain tests that > >>>>>> require drivers not built in or whitelisted in QEMU. > >>>>>> > >>> > >>>>>> + supported_formats=$($QEMU_PROG $QEMU_OPTIONS -drive format=\? > >>>>>> 2>&1 | \ > >>>>> > >>>>> Use of '?' to get help is deprecated. Please use 'format=help', and > >>>>> update your commit message accordingly. > >>>> > >>>> Is it? Where did we document that? > >>> > >>> Hmm, we haven't documented it yet, but it's been that way since commit > >>> c8057f95, in Aug 2012, when we added 'help' as the preferred synonym, > >>> and have tried to avoid mention of '?' in new documentation (as it > >>> requires additional shell quoting). I'm guessing we'll probably see a > >>> patch from you to start an official deprecation window? > >> > >> I'm using '?' regularly on my own, so don't expect a patch from > >> my side here ;-) > >> Anyway, we still use the question mark in our documentation, e.g.: > >> > >> options > >> > >> is a comma separated list of format specific options in a name=value > >> format. > >> Use -o ? for an overview of the options supported by the used format > >> or see > >> the format descriptions below for details. > >> > >> or: > >> > >> -b, --blacklist=list > >> > >> Comma-separated list of RPCs to disable (no spaces, ‘?’ to list > >> available RPCs) > > > > These are bugs, and we need to fix them. > > > >> So calling it deprecated sounds wrong to me. > > > > Our intent to deprecate it was pretty clear in commit c8057f95: > > > > /** > > * is_help_option: > > * @s: string to test > > * > > * Check whether @s is one of the standard strings which indicate > > * that the user is asking for a list of the valid values for a > > * command option like -cpu or -M. The current accepted strings > > --> * are 'help' and '?'. '?' is deprecated (it is a shell wildcard > > * which makes it annoying to use in a reliable way) but provided > > * for backwards compatibility. > > * > > * Returns: true if @s is a request for a list. > > */ > > static inline bool is_help_option(const char *s) > > > > Predates today's more formal deprecation policy. Simpler times. > > Sure, but finding such messages in the sources can be quite cumbersome... > > > There's no real need to kill off '?', unless it gets in the way of > > steering people towards 'help'. We should steer them toward 'help', > > because '?' is a trap for insufficiently sophisticated users of > > shell[*]. > > ... and I agree with your points here. > > => I think we need a second list of deprecated feature (maybe we should > call them "legacy features" instead of "deprecated"?), i.e. a list of > features which we don't recommend for new code / scripts anymore, but > which we do not intend to remove via our official deprecation policy any > time soon. Things like "--enable-kvm" / "-no-kvm" or maybe even "-net" > go into the same category.
I don't see much point to be honest. If --enable-kvm works for the user and we're not intending to removal it, I don't see why they should care about using something else instead. The other thing might have a more flexible syntax, but if they don't need those extra features it really doesn't matter. IOW, I think it is sufficient to just document all the options that exist, and when documenting them simply make a note inline that a particular option is merely syntax suger for an alternative option. 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 :|