see commit before, this time for real:

Remove some unused parts (commented out and similar)
Documentation of functions (both by Ulrich Müller and Christian Faulhammer)
New function elisp_make_autoload_file() (by Ulrich Müller)
Taken from Emacs Overlay

2 files changed, 333 insertions, 92 deletions

diff --git a/eclass/elisp-common.eclass b/eclass/elisp-common.eclass
index 25b371f4bf1e..a7cfed3d0e42 100644
--- a/eclass/elisp-common.eclass
+++ b/eclass/elisp-common.eclass
@@ -1,13 +1,113 @@
-# Copyright 1999-2004 Gentoo Foundation
+# Copyright 1999-2007 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/elisp-common.eclass,v 1.14 2005/09/17 01:02:40 ciaranm Exp $
+# $Header: /var/cvsroot/gentoo-x86/eclass/elisp-common.eclass,v 1.15 2007/04/16 15:35:56 opfer Exp $
 #
-# Copyright 2002-2003 Matthew Kennedy <mkennedy@gentoo.org>
+# Copyright 2007 Christian Faulhammer <opfer@gentoo.org>
+# Copyright 2002-2007 Matthew Kennedy <mkennedy@gentoo.org>
 # Copyright 2003 Jeremy Maitin-Shepard <jbms@attbi.com>
+# Copyright 2007 Ulrich Mueller <ulm@gentoo.org>
 #
-# This is not an eclass, but it does provide emacs-related
-# installation utilities.
-
+# This is not a real eclass, but it does provide Emacs-related installation
+# utilities.
+#
+# USAGE:
+#
+# Usually you want to use this eclass for (optional) GNU Emacs support of
+# your package.  This is NOT for XEmacs!
+#  Many of the steps here are sometimes done by the build system of your
+# package (especially compilation), so this is mainly for standalone elisp
+# files you gathered from somewhere else.
+#  When relying on the emacs USE flag, you need to add
+#
+#		emacs? ( virtual/emacs )
+#
+# to your DEPEND/RDEPEND line and use the functions provided here to bring
+# the files to the correct locations.
+#
+# src_compile() usage:
+# --------------------
+#
+# An elisp file is compiled by the elisp-compile() function defined here and
+# simply takes the source files as arguments.  In the case of interdependent
+# elisp files, you can use the elisp-comp() function which makes sure all
+# files are loadable.
+#
+#		elisp-compile *.el || die "elisp-compile failed!"
+# or
+#		elisp-comp *.el || die "elisp-comp failed!"
+#
+#  Function elisp-make-autoload-file() can be used to generate a file with
+# autoload definitions for the lisp functions.  It takes the output file name
+# (default: "${PN}-autoloads.el") and a list of directories (default: working
+# directory) as its arguments.  Use of this function requires that the elisp
+# source files contain magic ";;;###autoload" comments. See the Emacs Lisp
+# Reference Manual (node "Autoload") for a detailed explanation.
+#
+# src_install() usage:
+# --------------------
+#
+# The resulting compiled files (.elc) should be put in a subdirectory of
+# /usr/share/emacs/site-lisp/ which is named after the first argument
+# of elisp-install().  The following parameters are the files to be put in
+# that directory.  Usually the subdirectory should be ${PN}, you can choose
+# something else, but remember to tell elisp-site-file-install() (see below)
+# the change, as it defaults to ${PN}.
+#
+#		elisp-install ${PN} *.elc *.el || die "elisp-install failed!"
+#
+#  To let the Emacs support be activated by Emacs on startup, you need
+# to provide a site file (shipped in ${FILESDIR}) which contains the startup
+# code (have a look in the documentation of your software).  Normally this
+# would look like this:
+#
+#	;;; csv-mode site-lisp configuration
+#
+#	(add-to-list 'load-path "@SITELISP@")
+#	(add-to-list 'auto-mode-alist '("\\.csv\\'" . csv-mode))
+#	(autoload 'csv-mode "csv-mode" "Major mode for editing csv files." t)
+#
+#  If your Emacs support files are installed in a subdirectory of
+# /usr/share/emacs/site-lisp/ (which is recommended if more than one file is
+# installed), you need to extend Emacs' load-path as shown in the first
+# non-comment.  The elisp-site-file-install() function of this eclass will
+# replace "@SITELISP@" by the actual path.
+#  The next line tells Emacs to load the mode opening a file ending with
+# ".csv" and load functions depending on the context and needed features.
+# Be careful though.  Commands as "load-library" or "require" bloat the
+# editor as they are loaded on every startup.  When having a lot of Emacs
+# support files, users may be annoyed by the start-up time.  Also avoid
+# keybindings as they might interfere with the user's settings.  Give a hint
+# in pkg_postinst(), which should be enough.
+#  The naming scheme for this site file is "[0-9][0-9]*-gentoo.el", where the
+# two digits at the beginning define the loading order.  So if you depend on
+# another Emacs package, your site file's number must be higher!
+#  Best practice is to define a SITEFILE variable in the global scope of your
+# ebuild (right after DEPEND e.g.):
+#
+#		SITEFILE=50${PN}-gentoo.el
+#
+#  Which is then installed by
+#
+#		elisp-site-file-install "${FILESDIR}/${SITEFILE}"
+#
+# in src_install().  If your subdirectory is not named ${PN}, give the
+# differing name as second argument.
+#
+# pkg_postinst() / pkg_postrm() usage:
+# ------------------------------------
+#
+# After that you need to recreate the start-up file of Emacs after emerging
+# and unmerging by using
+#
+#		pkg_postinst() {
+#			elisp-site-regen
+#		}
+#		pkg_postrm() {
+#			elisp-site-regen
+#		}
+#
+#  As always: Feel free to contact Emacs team through emacs@gentoo.org if you
+# have problems, suggestions or questions.
 
 SITELISP=/usr/share/emacs/site-lisp
 
@@ -15,39 +115,49 @@ elisp-compile() {
 	/usr/bin/emacs --batch -f batch-byte-compile --no-site-file --no-init-file $*
 }
 
+elisp-make-autoload-file () {
+	local f="${1-${PN}-autoloads.el}"
+	shift
+	echo >"${f}"
+	emacs --batch -q --no-site-file \
+		--eval "(setq make-backup-files nil)" \
+		--eval "(setq generated-autoload-file (expand-file-name \"${f}\"))" \
+		-f batch-update-autoloads "${@-.}"
+}
+
 elisp-install() {
 	local subdir=$1
-	dodir ${SITELISP}/${subdir}
-	insinto ${SITELISP}/${subdir}
+	dodir "${SITELISP}/${subdir}"
+	insinto "${SITELISP}/${subdir}"
 	shift
 	doins $@
 }
 
 elisp-site-file-install() {
 	local sitefile=$1 my_pn=${2:-${PN}}
-	pushd ${S}
-	cp ${sitefile} ${T}
-	sed -i "s:@SITELISP@:${SITELISP}/${my_pn}:g" ${T}/$(basename ${sitefile})
+	pushd "${S}"
+	cp ${sitefile} "${T}"
+	sed -i "s:@SITELISP@:${SITELISP}/${my_pn}:g" "${T}/$(basename ${sitefile})"
 	insinto ${SITELISP}
-	doins ${T}/$(basename ${sitefile}) || die "failed to install site file"
+	doins "${T}/$(basename ${sitefile})" || die "failed to install site file"
 	popd
 }
 
 elisp-site-regen() {
 	einfo "Regenerating ${SITELISP}/site-gentoo.el ..."
 	einfo ""
-	cat <<EOF >${SITELISP}/site-gentoo.el
+	cat <<EOF >${ROOT}${SITELISP}/site-gentoo.el
 ;;; DO NOT EDIT THIS FILE -- IT IS GENERATED AUTOMATICALLY BY PORTAGE
 ;;; -----------------------------------------------------------------
 
 EOF
-	ls ${SITELISP}/[0-9][0-9]*-gentoo.el |sort -n | \
+	ls ${ROOT}${SITELISP}/[0-9][0-9]*-gentoo.el | sort -n | \
 	while read sf
 	do
 		einfo "	 Adding $(basename $sf) ..."
 		# Great for debugging, too noisy and slow for users though
-#		echo "(message \"Loading $sf ...\")" >>${SITELISP}/site-start.el
-		cat $sf >>${SITELISP}/site-gentoo.el
+#		echo "(message \"Loading $sf ...\")" >>${ROOT}${SITELISP}/site-start.el
+		cat $sf >>${ROOT}${SITELISP}/site-gentoo.el
 	done
 	while read line; do einfo "${line}"; done <<EOF
 
@@ -75,26 +185,6 @@ EOF
 elisp-comp() {
 # Copyright 1995 Free Software Foundation, Inc.
 # François Pinard <pinard@iro.umontreal.ca>, 1995.
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2, or (at your option)
-# any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-# As a special exception to the GNU General Public License, if you
-# distribute this file as part of a program that contains a
-# configuration script generated by Autoconf, you may include it under
-# the same distribution terms that you use for the rest of that program.
-
 # This script byte-compiles all `.el' files which are part of its
 # arguments, using GNU Emacs, and put the resulting `.elc' files into
 # the current directory, so disregarding the original directories used
@@ -105,31 +195,24 @@ elisp-comp() {
 # they require or load-library one another.
 
 	if test $# = 0; then
-		echo 1>&2 "No files given to $0"
 		exit 1
 	else
-		if test -z "$EMACS" || test "$EMACS" = "t"; then
+		if test -z "${EMACS}" || test "${EMACS}" = "t"; then
 		# Value of "t" means we are running in a shell under Emacs.
 		# Just assume Emacs is called "emacs".
 			EMACS=emacs
 		fi
 
 		tempdir=elc.$$
-		mkdir $tempdir
-		cp $* $tempdir
-		cd $tempdir
+		mkdir ${tempdir}
+		cp $* ${tempdir}
+		cd ${tempdir}
 
 		echo "(add-to-list 'load-path \"../\")" > script
-		$EMACS -batch -q --no-site-file --no-init-file -l script -f batch-byte-compile *.el
+		${EMACS} -batch -q --no-site-file --no-init-file -l script -f batch-byte-compile *.el
 		mv *.elc ..
 
 		cd ..
-		rm -fr $tempdir
+		rm -fr ${tempdir}
 	fi
 }
-
-# Local Variables: ***
-# mode: shell-script ***
-# tab-width: 4 ***
-# indent-tabs-mode: t ***
-# End: ***
diff --git a/eclass/elisp.eclass b/eclass/elisp.eclass
index ab2df25f58a3..d460f3d06e4b 100644
--- a/eclass/elisp.eclass
+++ b/eclass/elisp.eclass
@@ -1,60 +1,218 @@
-# Copyright 1999-2004 Gentoo Foundation
+# Copyright 1999-2007 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/elisp.eclass,v 1.16 2007/04/16 15:33:58 opfer Exp $
+# $Header: /var/cvsroot/gentoo-x86/eclass/elisp.eclass,v 1.17 2007/04/16 15:35:56 opfer Exp $
 #
-# Copyright 2002-2003 Matthew Kennedy <mkennedy@gentoo.org>
+# Copyright 2007 Christian Faulhammer <opfer@gentoo.org>
+# Copyright 2002-2007 Matthew Kennedy <mkennedy@gentoo.org>
 # Copyright 2003 Jeremy Maitin-Shepard <jbms@attbi.com>
+# Copyright 2007 Ulrich Mueller <ulm@gentoo.org>
 #
-# This eclass sets the site-lisp directory for emacs-related packages.
-
-inherit elisp-common
-
-# SRC_URI should be set to wherever the primary app-emacs/ maintainer
-# keeps the local elisp mirror, since most app-emacs packages are
-# upstream as a single .el file.
-
-# Note: This is no longer necessary.
-
-SRC_URI="http://cvs.gentoo.org/~mkennedy/app-emacs/${P}.el.bz2"
-if [ "${SIMPLE_ELISP}" = 't' ]; then
-	S="${WORKDIR}/"
-#else
-#	Use default value
-#	S="${WORKDIR}/${P}"
-fi
+# This is not a real eclass, but it does provide Emacs-related installation
+# utilities.
+#
+# USAGE:
+#
+# Usually you want to use this eclass for (optional) GNU Emacs support of
+# your package.  This is NOT for XEmacs!
+#  Many of the steps here are sometimes done by the build system of your
+# package (especially compilation), so this is mainly for standalone elisp
+# files you gathered from somewhere else.
+#  When relying on the emacs USE flag, you need to add
+#
+#		emacs? ( virtual/emacs )
+#
+# to your DEPEND/RDEPEND line and use the functions provided here to bring
+# the files to the correct locations.
+#
+# src_compile() usage:
+# --------------------
+#
+# An elisp file is compiled by the elisp-compile() function defined here and
+# simply takes the source files as arguments.  In the case of interdependent
+# elisp files, you can use the elisp-comp() function which makes sure all
+# files are loadable.
+#
+#		elisp-compile *.el || die "elisp-compile failed!"
+# or
+#		elisp-comp *.el || die "elisp-comp failed!"
+#
+#  Function elisp-make-autoload-file() can be used to generate a file with
+# autoload definitions for the lisp functions.  It takes the output file name
+# (default: "${PN}-autoloads.el") and a list of directories (default: working
+# directory) as its arguments.  Use of this function requires that the elisp
+# source files contain magic ";;;###autoload" comments. See the Emacs Lisp
+# Reference Manual (node "Autoload") for a detailed explanation.
+#
+# src_install() usage:
+# --------------------
+#
+# The resulting compiled files (.elc) should be put in a subdirectory of
+# /usr/share/emacs/site-lisp/ which is named after the first argument
+# of elisp-install().  The following parameters are the files to be put in
+# that directory.  Usually the subdirectory should be ${PN}, you can choose
+# something else, but remember to tell elisp-site-file-install() (see below)
+# the change, as it defaults to ${PN}.
+#
+#		elisp-install ${PN} *.elc *.el || die "elisp-install failed!"
+#
+#  To let the Emacs support be activated by Emacs on startup, you need
+# to provide a site file (shipped in ${FILESDIR}) which contains the startup
+# code (have a look in the documentation of your software).  Normally this
+# would look like this:
+#
+#	;;; csv-mode site-lisp configuration
+#
+#	(add-to-list 'load-path "@SITELISP@")
+#	(add-to-list 'auto-mode-alist '("\\.csv\\'" . csv-mode))
+#	(autoload 'csv-mode "csv-mode" "Major mode for editing csv files." t)
+#
+#  If your Emacs support files are installed in a subdirectory of
+# /usr/share/emacs/site-lisp/ (which is recommended if more than one file is
+# installed), you need to extend Emacs' load-path as shown in the first
+# non-comment.  The elisp-site-file-install() function of this eclass will
+# replace "@SITELISP@" by the actual path.
+#  The next line tells Emacs to load the mode opening a file ending with
+# ".csv" and load functions depending on the context and needed features.
+# Be careful though.  Commands as "load-library" or "require" bloat the
+# editor as they are loaded on every startup.  When having a lot of Emacs
+# support files, users may be annoyed by the start-up time.  Also avoid
+# keybindings as they might interfere with the user's settings.  Give a hint
+# in pkg_postinst(), which should be enough.
+#  The naming scheme for this site file is "[0-9][0-9]*-gentoo.el", where the
+# two digits at the beginning define the loading order.  So if you depend on
+# another Emacs package, your site file's number must be higher!
+#  Best practice is to define a SITEFILE variable in the global scope of your
+# ebuild (right after DEPEND e.g.):
+#
+#		SITEFILE=50${PN}-gentoo.el
+#
+#  Which is then installed by
+#
+#		elisp-site-file-install "${FILESDIR}/${SITEFILE}"
+#
+# in src_install().  If your subdirectory is not named ${PN}, give the
+# differing name as second argument.
+#
+# pkg_postinst() / pkg_postrm() usage:
+# ------------------------------------
+#
+# After that you need to recreate the start-up file of Emacs after emerging
+# and unmerging by using
+#
+#		pkg_postinst() {
+#			elisp-site-regen
+#		}
+#		pkg_postrm() {
+#			elisp-site-regen
+#		}
+#
+#  As always: Feel free to contact Emacs team through emacs@gentoo.org if you
+# have problems, suggestions or questions.
 
-DEPEND="virtual/emacs"
-IUSE=""
+SITELISP=/usr/share/emacs/site-lisp
 
-elisp_src_unpack() {
-	unpack ${A}
-	if [ "${SIMPLE_ELISP}" = 't' ]
-		then
-		cd ${S} && mv ${P}.el ${PN}.el
-	fi
+elisp-compile() {
+	/usr/bin/emacs --batch -f batch-byte-compile --no-site-file --no-init-file $*
 }
 
-elisp_src_compile() {
-	elisp-compile *.el || die
+elisp-make-autoload-file () {
+	local f="${1-${PN}-autoloads.el}"
+	shift
+	echo >"${f}"
+	emacs --batch -q --no-site-file \
+		--eval "(setq make-backup-files nil)" \
+		--eval "(setq generated-autoload-file (expand-file-name \"${f}\"))" \
+		-f batch-update-autoloads "${@-.}"
 }
 
-elisp_src_install() {
-	elisp-install ${PN} *.el *.elc
-	elisp-site-file-install ${FILESDIR}/${SITEFILE}
+elisp-install() {
+	local subdir=$1
+	dodir "${SITELISP}/${subdir}"
+	insinto "${SITELISP}/${subdir}"
+	shift
+	doins $@
 }
 
-elisp_pkg_postinst() {
-	elisp-site-regen
+elisp-site-file-install() {
+	local sitefile=$1 my_pn=${2:-${PN}}
+	pushd "${S}"
+	cp ${sitefile} "${T}"
+	sed -i "s:@SITELISP@:${SITELISP}/${my_pn}:g" "${T}/$(basename ${sitefile})"
+	insinto ${SITELISP}
+	doins "${T}/$(basename ${sitefile})" || die "failed to install site file"
+	popd
 }
 
-elisp_pkg_postrm() {
-	elisp-site-regen
+elisp-site-regen() {
+	einfo "Regenerating ${SITELISP}/site-gentoo.el ..."
+	einfo ""
+	cat <<EOF >${ROOT}${SITELISP}/site-gentoo.el
+;;; DO NOT EDIT THIS FILE -- IT IS GENERATED AUTOMATICALLY BY PORTAGE
+;;; -----------------------------------------------------------------
+
+EOF
+	ls ${ROOT}${SITELISP}/[0-9][0-9]*-gentoo.el | sort -n | \
+	while read sf
+	do
+		einfo "	 Adding $(basename $sf) ..."
+		# Great for debugging, too noisy and slow for users though
+#		echo "(message \"Loading $sf ...\")" >>${ROOT}${SITELISP}/site-start.el
+		cat $sf >>${ROOT}${SITELISP}/site-gentoo.el
+	done
+	while read line; do einfo "${line}"; done <<EOF
+
+All site initialization for Gentoo-installed packages is now added to
+/usr/share/emacs/site-lisp/site-gentoo.el; site-start.el is no longer
+managed by Gentoo. You are responsible for all maintenance of
+site-start.el if there is such a file.
+
+In order for this site initialization to be loaded for all users
+automatically, as was done previously, you can add a line like this:
+
+	(load "/usr/share/emacs/site-lisp/site-gentoo")
+
+to /usr/share/emacs/site-lisp/site-start.el.  Alternatively, that line
+can be added by individual users to their initialization files, or for
+greater flexibility, users can select which of the package-specific
+initialization files in /usr/share/emacs/site-lisp to load.
+EOF
+	echo
 }
 
-EXPORT_FUNCTIONS src_unpack src_compile src_install pkg_postinst pkg_postrm
+# The following Emacs Lisp compilation routine is taken from GNU
+# autotools.
+
+elisp-comp() {
+# Copyright 1995 Free Software Foundation, Inc.
+# François Pinard <pinard@iro.umontreal.ca>, 1995.
+# This script byte-compiles all `.el' files which are part of its
+# arguments, using GNU Emacs, and put the resulting `.elc' files into
+# the current directory, so disregarding the original directories used
+# in `.el' arguments.
+#
+# This script manages in such a way that all Emacs LISP files to
+# be compiled are made visible between themselves, in the event
+# they require or load-library one another.
+
+	if test $# = 0; then
+		exit 1
+	else
+		if test -z "${EMACS}" || test "${EMACS}" = "t"; then
+		# Value of "t" means we are running in a shell under Emacs.
+		# Just assume Emacs is called "emacs".
+			EMACS=emacs
+		fi
+
+		tempdir=elc.$$
+		mkdir ${tempdir}
+		cp $* ${tempdir}
+		cd ${tempdir}
+
+		echo "(add-to-list 'load-path \"../\")" > script
+		${EMACS} -batch -q --no-site-file --no-init-file -l script -f batch-byte-compile *.el
+		mv *.elc ..
 
-# Local Variables: ***
-# mode: shell-script ***
-# tab-width: 4 ***
-# indent-tabs-mode: t ***
-# End: ***
+		cd ..
+		rm -fr ${tempdir}
+	fi
+}