program.avr: make help text more clear about supported file extensions

[collinmay]

Also makes the error message more clear when output format is not specified and auto-detection fails.

As a user, I tried reading to a file without an extension and found the error message unhelpful for solving the problem at hand. It now clarifies that it's trying to deduce format using extension, and tells you which extensions are valid.

I'm personally not a huge fan of autodetecting this kind of thing, so I also added command line arguments that you can use to force the format if you don't want it to be automatic.

[whitequark]

I'm not sure I like having two separate, interacting ways to set the file format; what about improving the help text for the options and the error message but leaving the rest?

(It's amusing that I get this PR only a few hours after setting up a testbench for AVR programming. Timely?)

[collinmay]

Hmm I think I would agree that was confusing if both the file extension and command-line specified format somehow factored together into some final decision, but it's more that the command line option, if present, completely overrides the autodetection result and I think that's pretty intuitive.

If you didn't want to have both manual choice and autodetect though, I personally would lean towards the manual choice since command line applications usually don't really care about what (if any) file extensions you use, which makes it surprising when they do. objcopy uses options to specify output format, and I would never claim that objcopy is ideal command-line interface design, but it is familiar to a lot of people in this space and unsurprising in this regard.

If you still want to keep the autodetect instead though, I'll look at what I can add to the help text to make it more clear. Help text improvements can still make it less surprising, and that's all I'm really here at the end of the day.

[whitequark]

The reason I feel that autodetect based on file extension is worth it is that unlike objcopy (which is mostly invoked from scripts), the glasgow CLI is meant to be used mostly manually, and when you use a CLI heavily, unnecessary option combinations add up.

In other words, I agree that there is a tradeoff here, and under different circumstances I'd have chosen your suggestion myself; I only feel that in this particular case the tradeoff tilts the other way. What do you think?

[collinmay]

Yeah, that makes sense, and for scripting use-cases you can just use Python anyways. I'm convinced, will revise

[whitequark]

unnecessary option combinations add up.

To clear up what I said a bit: I think the amount of options can add cognitive load. Consider for example man ls. While this particular command is under no real risk, I also try to be consistent in my applications of UI principles. (I really should write these down...)

[collinmay]

Yep, heard. Help text now prints as:

usage: glasgow run program-avr-spi read [-h] [-f] [-l] [-c] [-p FILE.bin] [-e FILE.bin]

options:
  -h, --help            show this help message and exit
  -f, --fuses           display fuse bytes
  -l, --lock-bits       display lock bits
  -c, --calibration     display calibration bytes
  -p FILE.bin, --program FILE.bin
                        write program memory contents to FILE.bin
  -e FILE.bin, --eeprom FILE.bin
                        write EEPROM contents to FILE.bin

File output format is determined by extension. The following extensions are recognized:
  .bin          raw binary
  .hex          raw hex
  .ihex, .ihx   intel hex

I changed the metavars to include file extension as an additional hint that an extension is required.

[whitequark]

Thank you. I like this a lot more, but I'd like to suggest a few changes so that it fits in a bit better with the existing CLI, if you don't mind. (I'll get to this a bit later, perhaps today.)

[collinmay]

Sure. And at this point I feel like you understand what I'm trying to address here so if you find it easier to just make the text changes yourself rather than going through me, I won't be offended.

[whitequark]

I'll do that then. I still think it is valuable to communicate and discuss my intent, since it's a collaborative project.

[whitequark]

Please take a look at #624.