So far, we've got this, by agreement of the Council:

* There will be a default src_install in EAPI 3
* It will have a DOCS variable, or something along those lines.

I'd like to suggest the following too:

* If DOCS is explicitly specified, it is an error if anything in it
  doesn't exist.
* If DOCS isn't explicitly specified, it isn't an error if anything in
  its default, if it has one, doesn't exist.

We don't have an implementation yet. So I'll start off with this:

    default_src_install() {
        emake -j1 DESTDIR="${D}" install

        local d
        if ! declare -p DOCS >/dev/null 2>&1 ; then
            for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \
	            THANKS BUGS FAQ CREDITS CHANGELOG ; do
                [[ -s "${d}" ]] && dodoc "${d}"
            done
        elif declare -p DOCS | grep -q '^declare -a ' ; then
            for d in "${DOCS[@]}" ; do
                dodoc "${d}"
            done
        else
            dodoc ${DOCS}
        fi
    }

I got the default list by some horrid shell voodoo. Alternatively,
there's the following, which is a lot more comprehensive:

    default_src_install() {
        emake -j1 DESTDIR="${D}" install
        emagicdocs
    }

    emagicdocs() {
        done_docs=
        old_set=$(shopt | grep 'nocaseglob[[:space:]]*on')
        shopt -s nocaseglob
        for d in '' "${DEFAULT_SRC_INSTALL_EXTRA_SUBDIRS[@]}" ; do
            if [[ -n ${d} ]]; then
                [[ -d ${d} ]] || die "${d} is not a dir"
                pushd "${d}" > /dev/null || die "Failed to enter ${d}"
                local docdesttree="${DOCDESTTREE}"
                docinto "${d}"
            fi
            for f in README Change{,s,Log} AUTHORS NEWS TODO ABOUT THANKS {KNOWN_,}BUGS SUBMITTING \
                HACKING FAQ CREDITS PKG-INFO HISTORY PACKAGING MAINTAINER{,S} CONTRIBUT{E,OR,ORS} RELEASE \
                ANNOUNCE PORTING NOTES PROBLEMS NOTICE "${DEFAULT_SRC_INSTALL_EXTRA_DOCS[@]}"; do
                for p in "${DEFAULT_SRC_INSTALL_EXTRA_PREFIXES[@]}" '' ; do
                    for doc in "${p}"*([[:digit:]])"${f}"{,+([._-])*} ; do
                        if [[ -s "${doc}" ]] ; then
                            for e in "${DEFAULT_SRC_INSTALL_EXCLUDE[@]}" ; do
                                [[ ${doc} == ${e} ]] && continue 2
                            done
                            done_docs="${done_docs} ${d%/}${d:+/}${doc}"
                            dodoc "${doc}"
                        fi
                    done
                done
            done
            if [[ -n ${d} ]]; then
                docinto "${docdesttree}"
                popd > /dev/null || die "Failed to leave ${d}"
            fi
        done
        if [[ -n "${done_docs}" ]] ; then
            echo "Installed docs ${done_docs# }"
        else
            echo "Didn't find any docs to install"
        fi
        [[ -n ${old_set} ]] || shopt -u nocaseglob
    }

-- 
Ciaran McCreesh