[mythtv-users] Total system upgrade: Am I screwed?

[f-myth-users at media.mit.edu]

    > Date: Sun, 29 Nov 2009 13:22:56 -0500
    > From: "Michael T. Dean" <mtdean at thirdcontact.com>

    > On 11/29/2009 09:50 AM, Richard Shaw wrote:
    > > Here's the error:
    > >
    > > ERROR: Invalid database information file, stopped at
    > > bin/mythconverg_restore.pl line 686.
    > >
    > > I used --partial_restore just to get the recordings and schedule info
    > > but got the same error trying without that option as well. I'm
    > > specifiying the full name of the backup file using tab completion so I
    > > know I'm not mistyping it...

    > But you're not specifying the command-line option that tells the script 
    > you're specifying a filename.

    >  - What you're doing:

    > ./mythconverg_restore.pl file.sql.gz

    > (which will never work) or

I'd argue that's a usability bug right there.

Having never actually looked at mythconverg_restore.pl until right
this second, and having just made a pass through the very long output
of the --help option [I'm looking at the source to the version in
trunk], I can completely see why (a) he missed it in reading all of
that, and (b) why "[options|database_information_file]" completely
confused him.

The misleading error message obviously didn't help, either.

I understand why you have --directory and --filename options, but the
vast, vast majority of Unix command-line tools typically expect a pile
of (optional :) options, optionally or mandatorily followed by a filename.
Some of them are pretty screwed up vis a vis this informal standard (dd
and find spring immediately to mind, and _The Unix-Haters Handbook_ has
some other great examples), but that's the typical behavior.

I would opine that a nice way to fix this would be to recognize the
situation where no options are present but it looks like a filename
is (either because it has slashes in it, or because a slashless string
seems to match a filename in the current working directory), and then
just run with that, perhaps printing out a message saying something
like "I'm guessing you meant --directory blah --filename biff").

If that's too dangerous, perhaps it could at least print out a guess,
like "Did you mean to say $0 --directory blah --filename biff?",
though that's not as friendly because -my- immediate reaction would
be, "Yes, you stupid program, and why are you making me type all this
in twice when you obviously figured it out the first time?"

(It's -especially- weird that the program -requires- you to break up a
pathname into separate --directory and --filename args; virtually all
other Unix programs expect a single pathname, and requiring this both
surprises the user and makes it harder to call from a script, which
must separate the pieces first.  I know why you did it, but it's
surprising.)

Remember, this is a program that should be very rarely used.  Forcing
the user to have a steep learning curve, read a whole pile of options
that are probably irrelevant to him, and then barfing on the obvious
way to call it seems unfriendly---it's not as if the typical user
should be running this often enough to remember how.

    > For future reference, if you tell people what command you ran, they can 
    > help you figure out what you did wrong

Very true.

    > 					     (even if they don't know the 
    > script inside-out)...  The possibility exists--though I'm sure it's a 
    > tiny possibility--that the problem lies not with the backup or with the 
    > restore script...

Yes.  Like maybe it's a usability bug and not the user's fault.

(I know that sounds inflammatory, but honest to god, that's not my
intention here.  I'm just trying to point out that there are usually
other options -besides- "the user is stupid and it's all his fault.")

    > Also, there /is/ a mythconverg_restore.pl --help so you can help 
    > yourself.  Though it has a lot of info, the quick start is generally 
    > enough.

...but it's buried -waaaay- far down a giant block of text, and it
-still- doesn't actually have as examples the most common way you
might want to be calling this script.  [Certainly, my quick skim
of that section still didn't give me any info about calling it.]

    > 	       I'll change it to do the quick start info for --help and have 
    > an extended help with everything.

One suggestion for the very top of the help might be something like

  HERE ARE THE MOST LIKELY THINGS YOU'LL WANT TO DO:

    $0 
    $0 --directory /biff/boom
    $0 --directory /biff/boom --filename bar

and (especially if you don't intend to make the script DTRT if only a
pathname is specified and nothing else)

    Please note that $0 /some/path/to/file will -not- work.  You must
    specify --directory and/or --filename options if you intend to choose
    which backup to restore from.

    > I'll also put an error message in there that tells people to fix their 
    > command line when they specify an invalid database information file.

I'm sure that's a good idea.

[I'd be willing to make patches for all of the suggestions above,
if that matters, though I won't be able to get to it in the next
few days, and I'm sure it'd be about a 10-minute job for you.]