Re: "Emacs Lisp Packages" chapter in the Emacs manual

[Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>]

[-- Attachment #1: Type: text/plain, Size: 2820 bytes --]

> On May 10, 2020, at 1:47, Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> wrote:
> 
>> On May 10, 2020, at 0:19, Stefan Kangas <stefankangas@gmail.com> wrote:
>> 
>> Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> writes:
>> 
>>> --- a/doc/emacs/package.texi
>>> +++ b/doc/emacs/package.texi
>>> @@ -13,6 +13,9 @@ Packages
>>> separate Emacs Lisp program, sometimes including other components such
>>> as an Info manual.
>>> 
>>> +  Emacs Lisp programs that are not available through this facility can
>>> +still be loaded by installing them in the Emacs Lisp @dfn{load path}.  @xref{Lisp Libraries}.
>>> +
>>>>  @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
>>> with a list of all packages.  You can install or uninstall packages
>>> via this buffer.  @xref{Package Menu}.
>> 
>> It's a useful addition, I think, but it seems a bit backwards to add it
>> before even introducing `list-packages'.
>> 
>> I would suggest to move it further down.  It could be the second to last
>> paragraph, for example.
> 
> I'm not the most qualified person to discuss location, but if people think "install", it seems nice to tell them up front that there are 2 ways to do that. 
> 
> In fact, I first thought of something like this:
> 
> ============
> The traditional way to install Emacs Lisp code is to install it in the Emacs Lisp @dfn{load path}.  @xref{Lisp Libraries}.
> 
> Now, Emacs includes a facility that lets you easily download and install
> @dfn{packages} that implement additional features.
> ...
> ============


I think I have a better proposal:

1) add a pointer to the Lisp Librairies section of the manual in package.texi

48 Emacs Lisp Packages
**********************

The traditional way to install Emacs Lisp code is to install it in the
Emacs Lisp "load path".  *Note Lisp Libraries::.

   Now, Emacs includes a facility that lets you easily download and
install "packages" that implement additional features.  Each package is
a separate Emacs Lisp program, sometimes including other components such
as an Info manual.


2) add a reference to "require" in the Features section of the manual in building.texi

   To automatically load code that you have installed in the load path,
you can use `require' in your init file.  *Note Features:
(elisp)Features. For example, here's how to automatically load the
features provided by file `feature.el' installed in your load path:

     (require 'feature)


Is there a better way to give easy access to this information ? In case the proposal above is accepted, I'm attaching the corresponding patch.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune



[-- Attachment #2: package.texi.200510.diff --]
[-- Type: application/octet-stream, Size: 1742 bytes --]

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 77a0e807c2..93ff85c600 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1558,11 +1558,18 @@ Lisp Libraries
 @code{help-enable-autoload} to @code{nil}.
 
 @vindex help-enable-completion-autoload
-Automatic loading also occurs when completing names for
+  Automatic loading also occurs when completing names for
 @code{describe-variable} and @code{describe-function}, based on the
 prefix being completed.  To disable this feature, change the variable
 @code{help-enable-completion-autoload} to @code{nil}.
 
+@findex require
+  To automatically load code that you have installed in the load path, you can use @code{require} in your init file.  @xref{Features,,, elisp, the Emacs Lisp Reference Manual}. For example, here's how to automatically load the features provided by file @file{feature.el} installed in your load path:
+
+@example
+(require 'feature)
+@end example
+
 @node Lisp Eval
 @section Evaluating Emacs Lisp Expressions
 @cindex Emacs Lisp mode
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index db3cf317ff..8a342cc0f3 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -7,8 +7,9 @@ Packages
 @cindex Package
 @cindex Emacs Lisp package archive
 @cindex Package archive
+The traditional way to install Emacs Lisp code is to install it in the Emacs Lisp @dfn{load path}.  @xref{Lisp Libraries}.
 
-Emacs includes a facility that lets you easily download and install
+  Now, Emacs includes a facility that lets you easily download and install
 @dfn{packages} that implement additional features.  Each package is a
 separate Emacs Lisp program, sometimes including other components such
 as an Info manual.