|
From: | Eric Blake |
Subject: | Re: [Qemu-devel] [PATCH v2] qemu-doc: Rework the network options chapter to make "-net" less prominent |
Date: | Mon, 12 Mar 2018 07:18:08 -0500 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.6.0 |
On 03/12/2018 04:07 AM, Paolo Bonzini wrote:
On 12/03/2018 08:27, Thomas Huth wrote:"-net" is clearly a legacy option. Yet we still use it in almost all examples in the qemu documentation, and many other spots in the network chapter. We should make it less prominent that users are not lured into using it so often anymore. So instead of starting the network chapter with "-net nic" and documenting "-net <backend>" below "-netdev <backend>" everywhere, all the "-net" related documentation is now moved to the end of the chapter. The new "--nic" option is moved to the beginning of the chapter instead, with a new example that should demonstrate how "--nic" can be used to shortcut "--device" with "--netdev". The examples in this chapter are changed to use the "--device" and "--netdev" options or "--nic" instead of "-net nic -net <backend>". While we're at it, also remove a legacy remark about very old Linux distributions. Also remove the "[...]" from the examples in this chapter since we are not using this ellipsis in any other examples in our docu- mentation. Signed-off-by: Thomas Huth <address@hidden> --- v2: - Fixed the bad "--device=e1000" exampleFrankly I think this is the proof that double-dash option names are a bad idea. The reason to do that was to make qemu-img and qemu command lines more similar in the documentation, but the truth is they are not similar and shouldn't be made similar. The equal sign is one example, where qemu-img supports "--format=raw" but QEMU doesn't support "--device=e1000", but it's not the only one.
Our hand-rolled parser sucks. We should fix it to be more like getopt, at which point --device=e1000 would work.
qemu-img supports things such as "-fraw", qemu doesn't---for example "-m1024" doesn't work).
Our hand-rolled parser sucks. We should fix it to be more like getopt, at which point -m1024 would work.
qemu-img can combine single-letter options (e.g. "qemu-img convert -pc") but qemu cannot---e.g. "-sm" doesn't combine "-s" and "-m".
That's a legitimate difference between getopt_long() and getopt_long_only() - but to some extent, even getopt_long_only() can bundle unambiguous short options correctly. Again, fixing our hand-rolled parser to use getopt_long_only() might make this better.
No need to drop them in QEMU, since it's more or less just a convenience for people that are used to double-dash long options, but using them in the documentation is confusing.
For -object vs. --object (which IS used identically between qemu-img and qemu proper), we really do want to favor a common spelling (which perhaps means we need to first fix our hand-rolled parser to not suck so much - possibly by rewriting it to use getopt_long_only()). For options like -nic vs. --nic, which have no (current) counterpart in qemu-img, it's a harder sell (as you continue to argue), but Dan's original suggestion to prefer double-dash in the documentation was because consistency helps (and if that means improving our parser to behave more consistently, that's a good thing).
-- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
[Prev in Thread] | Current Thread | [Next in Thread] |