[gentoo-commits] proj/emacs-tools:emacs-common commit in: /

["Ulrich Müller" <ulm@gentoo.org>]

commit:     0801b39bb55a53d63803577850c11ee931248ec2
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Mar  7 20:26:56 2025 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Mar  7 20:26:56 2025 +0000
URL:        https://gitweb.gentoo.org/proj/emacs-tools.git/commit/?id=0801b39b

Add README files

* README.gentoo.in: New file, from DOC_CONTENTS of the ebuild.
* README.daemon: New file, copied from emacs-daemon and updated.
* Makefile (DISTFILES): Add them.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ChangeLog        |  4 ++++
 Makefile         |  7 +++---
 README.daemon    | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.gentoo.in | 16 +++++++++++++
 4 files changed, 97 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 53d2f73..9bd5053 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2025-03-07  Ulrich Müller  <ulm@gentoo.org>
 
+	* README.gentoo.in: New file, from DOC_CONTENTS of the ebuild.
+	* README.daemon: New file, copied from emacs-daemon and updated.
+	* Makefile (DISTFILES): Add them.
+
 	* emacs.initd: New file. Merged version of the user initd file
 	attached to bug 950671 and emacs.rc from the emacs-daemon package.
 	Thanks to Anna (navi) Figueiredo Gomes.

diff --git a/Makefile b/Makefile
index 9a4fbac..af7986f 100644
--- a/Makefile
+++ b/Makefile
@@ -14,9 +14,10 @@ ICONFILES = sink.png \
 	emacs25_16.png emacs25_24.png emacs25_32.png emacs25_48.png \
 	emacs25_128.png emacs25.svg
 GSCHEMAFILES = org.gnu.emacs.defaults.gschema.xml
-DISTFILES = site-start.el site-gentoo.el subdirs.el.in emacs.initd \
-	$(DESKTOPFILES) $(addprefix icons/,COPYRIGHT.icons $(ICONFILES)) \
-	$(GSCHEMAFILES)
+DISTFILES = README.gentoo.in README.daemon \
+	site-start.el site-gentoo.el subdirs.el.in emacs.initd \
+	$(DESKTOPFILES) $(GSCHEMAFILES) \
+	$(addprefix icons/,COPYRIGHT.icons $(ICONFILES)) \
 
 
 .PHONY: all dist clean $(DESKTOPFILES)

diff --git a/README.daemon b/README.daemon
new file mode 100644
index 0000000..5234023
--- /dev/null
+++ b/README.daemon
@@ -0,0 +1,73 @@
+User guide for the Emacs daemon init script
+===========================================
+
+GNU Emacs version 23 or later supports running as a daemon, to which
+a user can connect through the emacsclient program. This can be done
+either in the current terminal with ``emacsclient -t``, or by creating
+a new graphical client frame (i.e. opening a new X window) with
+``emacsclient -c``.
+
+Every user who wants to connect to an Emacs server must have an own
+instance of the daemonized GNU Emacs.
+
+OpenRC version 0.60 or later supports this via "user services" and
+user init scripts in the ``/etc/user/init.d/`` directory. In order to
+automatically start Emacs as a daemon in your user session, login as
+normal user and execute the command::
+
+   $ rc-update --user add emacs default
+
+This will add the ``/etc/user/init.d/emacs`` init script to the
+default runlevel in ``~/.config/rc/runlevels/``.
+
+To get all benefits of the daemon setup, you should set the ``EDITOR``
+environment variable to ``emacsclient``, so that programs calling an
+external editor will use the existing Emacs process. Also file
+associations in your desktop system should call emacsclient.
+When closing a session or frame, no contents is lost; you may simply
+reconnect to the Emacs server.
+
+Launching the Emacs daemon at system startup
+--------------------------------------------
+
+If you want to launch your user's Emacs daemon at system startup and
+have it persist between login sessions, you must multiplex OpenRC's
+user system service: As the superuser, create a symbolic link (do not
+copy the script, or you will miss eventual updates!) in the
+``/etc/init.d/`` directory::
+
+   # ln -s user /etc/init.d/user.<username>
+
+where <username> is your user's login name. The service can then be
+started manually using::
+
+   # rc-service user.<username> start
+
+or it may be added to the boot sequence (and will run with the user's
+privileges)::
+
+   # rc-update add user.<username> default
+
+See OpenRC's ``user-guide.md`` for a more complete guide how to
+configure user services at the OpenRC side.
+
+Note: Running of an Emacs daemon process for a user was previously
+supported by the app-emacs/emacs-daemon package which launched it as
+a regular OpenRC service (as user services did not yet exist).
+This method still works but may be discontinued in the future.
+
+Authors
+-------
+
+| Ulrich Müller <ulm@gentoo.org>
+| Christian Faulhammer <fauli@gentoo.org>
+
+| Copyright 2008-2025 Gentoo Authors
+| Distributed under the terms of the GNU General Public License v2 or later
+
+
+.. Local Variables:
+.. mode: rst
+.. fill-column: 70
+.. indent-tabs-mode: nil
+.. End:

diff --git a/README.gentoo.in b/README.gentoo.in
new file mode 100644
index 0000000..da7266d
--- /dev/null
+++ b/README.gentoo.in
@@ -0,0 +1,16 @@
+All site initialisation for Gentoo-installed packages is added to
+@SITELISP@/site-gentoo.el.
+
+In order for this site initialisation to be loaded for all users
+automatically, a default site startup file /etc/emacs/site-start.el
+is installed. You are responsible for maintenance of this file.
+
+Alternatively, individual users can add the following command:
+
+   (require 'site-gentoo)
+
+to their ~/.emacs initialisation files, or, for greater flexibility,
+users may load single package-specific initialisation files from the
+@SITELISP@/site-gentoo.d/ directory.
+
+See README.daemon for documentation of the Emacs daemon init script.