binutils-doc 2.15-5: glitches in ld.info

[Edward Welbourne]

I have version 2.15-5 of the binutils-doc package as shipped with
Debian/sarge.  I was reading up on Linker Scripts in the ld info pages
and noticed what I suppose to be some errors; if they are not then, at
least, I would encourage review of the relevant passages, as they
managed to confuse me !  Details below, each starting "(ld.info)"
followed by the section title.

        Eddy.

(ld.info) Output Section Keywords, under CONSTRUCTORS, 2nd para: <q>

     The symbol `__CTOR_LIST__' marks the start of the global
     constructors, and the symbol `__DTOR_LIST' marks the end.  The
     first word in the list is the number of entries, followed by the
     address of each constructor or destructor, followed by a zero
     word.  The compiler must arrange ...

</q> Contrasting this with the example following the next paragraph, I
suspect:
 * where the above says __DTOR_LIST it's missing a __ at the end: it
   should say __DTOR_LIST__
 * the constructor list's end is actually marked by a zero word; the
   word *after* that is at address __DTOR_LIST__
 * presumably the __DTOR_LIST__ marks the start of the global
   destructor list and is expected to follow the zero word that marked
   the end of the constructor list that started at __CTOR_LIST__

I infer that the two sentences above need re-written; someone familiar
with the subject matter can probably improve, if only by being more
terse, but how about: <suggest>

     The constructor information comprises two lists, one of
     constructors for global data and one of destructors for global
     data: the first word of each list is the number of entries; it is
     followed by the address of each constructor or destructor; the
     last entry is followed by a zero word.  The symbol
     `__CTOR_LIST__' marks the start of the global constructors and
     the symbol `__DTOR_LIST__' marks the start of the global
     destructors; this is immediately after the zero word which ends
     the constructor list.  The compiler must arrange ...

</suggest>

(ld.info) Overlay Description, <q>

   For each section within the `OVERLAY', the linker automatically
   defines two symbols.  The symbol `__load_start_SECNAME' is defined
   as the starting load address of the section.  The symbol
   `__load_stop_SECNAME' is defined as the final load address of the
   section.

</q> and the final illustration of how to do the OVERLAY without using
syntactic sugar fits with this description - the symbols are addresses
of the start and end of the overlay; but, in the example's "C code to
copy" an overlay into the overlay area, <q>

       extern char __load_start_text1, __load_stop_text1;
       memcpy ((char *) 0x1000, &__load_start_text1,
               &__load_stop_text1 - &__load_start_text1);

</q> the two symbols are treated as though they are single named bytes
at the start and end of the memory region, so that the address of each
of these bytes is the start or end address of the overlay - the other
text led me to expect <suggest>

       extern char *__load_start_text1, *__load_stop_text1;
       memcpy ((char *) 0x1000, __load_start_text1,
               __load_stop_text1 - __load_start_text1);

</suggest> as the example code !  Either some further clarification is
needed, or the example code needs changed ...