This comes from the following gentoo-dev thread:
http://www.gossamer-threads.com/lists/gentoo/dev/264888

Its usage will lead to the installation of a CONFIGURATION file
under /usr/share/doc/${PF} and show of elog messages with its content
first time package is installed, relying in doc file for future
installations or people simply going there to review configuration tips.

I also attach acpid ebuild as example.

Currently I have doubts about how to handle formatting, it is now using
"fmt" as kernel-2.eclass to format it and, then, you can set:
CONFIGURATION_INSTRUCTIONS="
        You may wish to read the Gentoo Linux Power Management Guide,
        which can be found online at:
        http://www.gentoo.org/doc/en/power-management-guide.xml"

and it will be properly formatted at the end. The problem is that I find
no way to force a jump to a new line (for example if somebody want to
show a command to run in a new line).

Other option would be to simply add quotes to:
echo ${CONFIGURATION_INSTRUCTIONS}

and drop "fmt" usage.

It will respect formatting specified in ebuild, but this needs to be
taken into account as, for example, acpid ebuild used as example should
be changed to use:
CONFIGURATION_INSTRUCTIONS="You may wish to read the Gentoo Linux Power
Management Guide,
        which can be found online at:
        http://www.gentoo.org/doc/en/power-management-guide.xml"

or people will get an empty line at the top of the messages.

Maybe an option to toggle fmt/formatting usage could be used, but I am
unsure about how to handle it at eclass level in a "short" way (I could
add some "ifs" running either variant (with quotes or without them and
fmt usage), but not sure if a shorter way could be used)