[avr-gcc-list] Documentation on avrdude

[Juergen Harms]

Today I finally got my hardware (STK500) - and immediately had a hard
time coming to grips with avrdude on my Linux platform: the
documentation might be clearer.

The example in avr-libc-user-manual-1.4.5/using_avrprog.html calls
avrdude with:

    avrdude -p 2313 -e -m flash -i main.hex

That is not very helpful - to make avrdude program my flash memory,
I ended up with

    avrdude -p m16 -c stk500v2 -P /dev/ttyS0 -U flash:w:main.hex


Issues (forgetting the different type of processor):

1. the -m option does not exist any more.

2. the info on the -U option is difficult to read in the man-page if
   you use konqueror for reading man-pages (but no problem if one
   uses man): the first part of the -U line simply does not get shown,
   the line starts with :opt:filename (I guess a bug in konqueror or
   a flaw in the troff code of the avrdude man-page - very weird,
   but painful when you desperately search for what might have
   replaced the -m option).

3. for a newby it is not evident which programmer-ID to use (I went
   back to the avrdude.conf file to get names, but also the flavour
   of STK500 to select was not quite evident).

4. the serial port to use is also not immediately evident (and the
   STK500 user guide only says 115200 baud, does not say that the
   default N1 is OK).

I hope that helps other newcomer to get a more rapid start than I did.

Suggestions for the next update of the documentation:

- check whether the -U man-page problem can be corrected in the source
  of the avrdude man-page.

- drop the remaining reference to the -m option in the avrdude man-page.

- correct and augment the documentation on calling avrdude in the
  "Using avrdude" document of the AVR-libc documentation:

    o reflect that -m does not exist any more

    o add some words on the -P option, maybe give a list of ports used
      on the main platforms,

    o add some words on the -c option and provide a commented list
      on programmer IDs of the major programmers.

- might be a good idea to mention that stty 115200 is all you need to
  set up your com port on Linux if you use the STK500.

Continuing the recent discussion on documentation, I would like to
volonteer giving a hand improving the documentation - but it will take
quite some time until I am experienced enough to do a clean job - hence
the form of "suggestions".