git: 1ba292a796 - main - [phb][Uses]: Add missing Uses=emacs

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=1ba292a79606194abee212dddc03afc018de5883

commit 1ba292a79606194abee212dddc03afc018de5883
Author:     Fernando Apesteguía <[email protected]>
AuthorDate: 2025-02-23 17:30:28 +0000
Commit:     Fernando Apesteguía <[email protected]>
CommitDate: 2025-02-23 17:34:19 +0000

    [phb][Uses]: Add missing Uses=emacs
    
    Reviewers:              jrm@
    Differential Revision:  https://reviews.freebsd.org/D48989
---
 .../en/books/porters-handbook/uses/_index.adoc     | 64 +++++++++++++++++++++-
 1 file changed, 62 insertions(+), 2 deletions(-)

diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index 5360653b1a..759deefc87 100644
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -588,7 +588,6 @@ When the `stage` argument is supplied, binaries under `STAGEDIR` are operated on
 ====
 [.programlisting]
 ....
-USES=           elfctl
 ELF_FEATURES=	featurelist:path/to/file1 \
 		featurelist:path/to/file2
 ....
@@ -597,7 +596,68 @@ ELF_FEATURES=	featurelist:path/to/file1 \
 
 The format of `featurelist` is described in man:elfctl[1].
 
-[[uses-erlang]]
+[[uses-emacs]]
+== `emacs`
+
+Possible arguments: (none) (default), `build`, `run`, `noflavors`
+
+Provides support for ports requiring Emacs.
+The `build` argument creates a build dependency on Emacs.
+The `run` argument creates a run dependency on Emacs.
+If both the `build` and `run` arguments are absent, create build and run
+dependencies on Emacs.
+The `noflavors` argument prevents flavors, and is implied if there is no run dependency on Emacs.
+
+The default Emacs flavor for ports with `USES=emacs` can be defined in [.filename]#make.conf#.
+For example, for the `nox` flavor, use `DEFAULT_VERSIONS+= emacs=nox`.
+The valid flavors are: `full`, `canna`, `nox`, `wayland`, `devel_full`, `devel_nox`.
+
+Variables, which can be set by ports:
+
+`EMACS_FLAVORS_EXCLUDE`::
+Do NOT build these Emacs flavors.
+If `EMACS_FLAVORS_EXCLUDE` is not defined and:
+
+* there is a run dependency on Emacs
+* the noflavors argument is not specified
+
++
+then all valid Emacs flavors are assumed.
+
+`EMACS_NO_DEPENDS`::
+Do NOT add build or run dependencies on Emacs.
+This will prevent flavors, and no byte code files will be generated as part of
+the package.
+
+Variables, which can be read by ports:
+
+`EMACS_CMD`::
+Emacs command with full path (e.g. [.filename]#/usr/local/bin/emacs-30.1#)
+
+`EMACS_FLAVOR`::
+Used for dependencies (e.g. `BUILD_DEPENDS= dash.el${EMACS_PKGNAMESUFFIX}>0:devel/dash@${EMACS_FLAVOR}`)
+
+`EMACS_LIBDIR`::
+Emacs Library directory without `${PREFIX}` (e.g. [.filename]#share/emacs#)
+
+`EMACS_LIBDIR_WITH_VER`::
+Library directory without `${PREFIX}` including version (e.g.  [.filename]#share/emacs/30.1#)
+
+`EMACS_MAJOR_VER`::
+Emacs major version (e.g. 30)
+
+`EMACS_PKGNAMESUFFIX`::
+`PKGNAMESUFFIX` to distinguish Emacs flavors
+
+`EMACS_SITE_LISPDIR`::
+Emacs site-lisp directory without `${PREFIX}` (e.g.  [.filename]#share/emacs/site-lisp#)
+
+`EMACS_VER`::
+Emacs version (e.g. 30.1)
+
+`EMACS_VERSION_SITE_LISPDIR`::
+Include version (e.g. [.filename]#share/emacs/30.1/site-lisp#)
+
 == `erlang`
 
 Possible arguments: (none), `enc`, `rebar`, `rebar3`