[avr-gcc-list] avr-gcc 'documentation'

[David McNab]

Hi,

I've already embarrassed myself on this list with my early naive
questions, as I battle to migrate from PIC to AVR, and I guess I'm going
to embarrass myself again.

What I want to ask is - what's the current thinking within the avr-gcc
community with respect to documentation, and the task of making avr-gcc
approachable to newcomers? Is good newbie-friendly documentation seen as
a valued goal within the community?

Before I start, I do have to express my deepest appreciation for the
marvellous job at code level that has gone into avr-gcc and avr-libc,
and for the time and effort donated by its umpteen developers. It is
absolutely wonderful to have the much-cherished gcc toolchain available
and working so brilliantly for AVR.

But - I've been having a hard time with learning avr-gcc, largely due to
the way the documentation (or lack of it) is organised.

To give some examples:
 - avr-as pseudo-ops - there seems to be no thorough list of these. For
   example, I had to look through list archives to learn how to declare
   a buffer in SRAM via the '.skip' pseudo-op
 - a good part of the C API is well documented via doxygen, but there is
   no consolidated global index of everything. Such an index would prove
   a huge boost
 - there's no definitive list of assembler macros
 - I can count the code examples on my left hand. There really need to
   be several dozen examples shipped in /doc/examples in the avr-libc
   distribution, ranging from the simplest to the more complex

To give an example of great microcontroller compiler doco, consider the
PIC CCS C compiler manual:
http://www.ccsinfo.com/downloads/ccs_c_manual.pdf
That, together with the extensive examples, flatten the learning curve
to a mild uphill stroll. If the CCS compiler was free/opensource, or if
there was a really decent free/opensource C compiler for PIC (sdcc is
not that good), I'd probably be staying with PIC.

I'm sure I'll be ok with avr-gcc and avr-libc once I've got a good grasp
of things. But it does seem that:

 avr-gcc doco = avr-libc site docs
              + avr-gcc list archives
              + avr-gcc and avr-libc source code

I've seen this situation often - developers can often feel that writing
doco that caters to newbies is beneath them. But this can repel a lot of
people, which might be a big part of why PIC, PICAXE and BASIC STAMP,
with their excellent doco, continue to enjoy huge market share despite
their vastly inferior and often much more expensive products.

Cheers
David