On Mon, 24 Aug 2026 at 12:40, Daniel P. Berrangé <[email protected]> wrote: > On Mon, Aug 24, 2026 at 11:58:52AM +0100, Peter Maydell wrote: > > Mostly I mention it because otherwise I think the typical user is > > going to do what I did, i.e. replace "-mon" with "-object monitor-hmp" > > and then immediately get a different error from QEMU. The warning > > being more precise could save them a step. > > I was thinking that the user would do 'man qemu' where we have > docs for "-object", for each object type including "monitor-hmp/qmp", > which are shown taking an ID parameter.
But they only have to look at the docs because the warning message we just printed doesn't give them enough information. FWIW, I did try the docs: putting "monitor-hmp" into the online HTML search produces as the top hit the "Deprecated features" subsection, which also doesn't give enough information (and doesn't hyperlink to anywhere else that gives more information[*]), and then a lot of other irrelevant hits because the search seems to be word based so it shows you everything with either "monitor" or "HMP". At this point I gave up and started looking around in the git history. [*] partly this is because hyperlinks into the qemu-options.hx docs are awkward. We have syntax so you can say "SRST(something)" to get a linkable label at the top of a section, but nothing more precisely targeted than that. (I think that ultimately we should consider splitting out "build manpages" and "build HTML docs" into completely separate sphinx doc source trees and sphinx-doc runs (with build time fiddling for where they share content), because sphinx really really doesn't want "different docs formats are different content" and it shows up in various places including this "it's hard to define a label in content that's shared between manpages and HTML" one.) > > There's an argument that the deprecation warning could look at the > > option the user actually provided and emit the exact right new > > option to use instead. But I don't think that's something we've > > ever done before for deprecations. > > Essentially we have three distinct places with info - the deprecation > message at runtime, the deprecated.rst docs, and the qemu.1 manual > page. It is a trade off between how much effort we want to put into > each area. One of these is the one that by definition every user who needs to update their command lines will see, though. > For humans I anticipated they'd be mostly using -monitor / -qmp > convenience options, with -mon mostly used by machines which are > already familiar with -object usage already. Mmm. I'm not quite sure why my scripts use -mon + -chardev rather than '-monitor tcp:...'. thanks -- PMM
