cyr_dbtool: document flags

[robn]

Not complete, as I don't quite understand what -t and -T are supposed to achieve (something about transactions). Also, I haven't actually tested that -c and -M even work (-n does, which is what I wanted). ALSO, -c sounds kinda destructive enough that it should perhaps be an explicit convert action and maybe shouldn't be neatly documented at all, but anyway, here we are!

[elliefm]

Looks good, couple of suggestions if that's okay?

[robn]

Looks good, couple of suggestions if that's okay?

Of course! :D

[robn]

So how do you suggest I proceed here?

Sounds like:

• we want to remove -c
• -M might not be clear or useful enough if you have to know how your database is setup ahead of time
• -n could conceivably be replaced by a create action
• no one knows what -t and -T are

I wanted to avoid a large change to cyr_dbtool because I was just passing through on my way to something else, and the if/else action tree offended me and if I get started on cleanup I'll want to do something about it. But maybe you will tell me this is a good opportunity to pay down some debt, especially since I only pop up in this repo every couple of years 😅

[elliefm]

I think we might have vague plans to consolidate ctl_cyrusdb, cvt_cyrusdb, and cyr_dbtool into a single tool with a coherent interface someday, and I'm fine with taking an "if it ain't broke" approach and leaving them mostly alone until we can do it right, once.

For now, I think it's fine to just leave -c out of the cyr_dbtool usage message, and pretend it doesn't exist, just like the man page does.

The man page says that -T is for holding a transaction while doing whatever we're doing ("most especially for 'show'"), and it seems like that used to be the default behaviour but now you need to ask for it with -T. Looks like -t is a legacy option for "don't hold a transaction", which is obsolete now that it's the default behaviour, we just continue to accept-and-ignore it so we don't break people's scripts I guess.

I have no idea why one would choose to hold a transaction or not. It might be fine to just add something like "-T use a transaction to do the action". I tend to think of usage messages as brief reminders of the functionality you already understand (or can learn about elsewhere), so I don't think we need a detailed explanation of any of this here.

It would help if the "elsewhere" were more informative, but that's a different rabbit hole!