"Emacs Lisp Packages" chapter in the Emacs manual

"Emacs Lisp Packages" chapter in the Emacs manual

[Jean-Christophe Helary]

I guess I've been using package.el too much and was not able to remember how to install code not found in ?elpa repositories (help-fns+.el, for one).

So I checked the manual for "install" and found that the section about "Emacs Lisp Packages" did not give information about installing code that was not in the repositories handled by package.el

I seemed to remember that there was something about that in the Elisp Introduction. So here again, I searched for "install", found "Install a function definition" that linked to "Installing code permanently" that lead to "Loading files", where I got enough hints to go back the emacs manual.

So I go back to the Emacs manual, search for "load" and find, under "Compiling and Testing Code" the "Libraries of Lisp Code for Emacs" section where the information I'm looking for is written.


Would it be acceptable to have a shortcut to that section in the "Package" chapter ? Something like:

===============================
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index db3cf317ff..21ebeb829b 100644
--- 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}.
===============================


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

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

[Stefan Kangas]

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.

Best regards,
Stefan Kangas

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

[Jean-Christophe Helary]

> 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.
...
============



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

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

[Jean-Christophe Helary]

[-- 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.

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

[Stefan Monnier]

> 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)

While it can be useful to `require` a file from `.emacs` in particular
cases, it's *usually* a bad idea which will just slow down your startup.
So I don't think we should promote this.

Most packages installed "the old way" have a little blurb in their `;;;
Commentary:` section (or `INSTALL` file or somewhere) which shows what to
add to your `.emacs`.


        Stefan

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

[Jean-Christophe Helary]

> On May 10, 2020, at 23:17, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> 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)
> 
> While it can be useful to `require` a file from `.emacs` in particular
> cases, it's *usually* a bad idea which will just slow down your startup.
> So I don't think we should promote this.
> 
> Most packages installed "the old way" have a little blurb in their `;;;
> Commentary:` section (or `INSTALL` file or somewhere) which shows what to
> add to your `.emacs`.

Thank you Stefan. I guess the first part is good enough then ?


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

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

[Stefan Monnier]

> Thank you Stefan. I guess the first part is good enough then ?

I don't have an opion on the "good enough part", but it sounds like
a good change, yes.


        Stefan

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

[Jean-Christophe Helary]

I'm actually surprised that nothing from the pre-package area was left in the manual. I suppose there was something before package to indicate how to install external code, wasn't there ?

Actually I'm checking the 21 manual here:

https://ftp.gnu.org/old-gnu/Manuals/emacs/html_chapter/emacs_toc.html#SEC_Contents

And I'm not finding much. Am I missing something ?

> On May 11, 2020, at 1:49, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> Thank you Stefan. I guess the first part is good enough then ?
> 
> I don't have an opion on the "good enough part", but it sounds like
> a good change, yes.
> 
> 
>        Stefan
> 

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

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

[Drew Adams]

> I'm actually surprised that nothing from the pre-package area was left
> in the manual. I suppose there was something before package to indicate
> how to install external code, wasn't there ?
> 
> Actually I'm checking the 21 manual here...
> And I'm not finding much. Am I missing something ?

Yes, there was more mention of `require' in the Elisp
manual before package.el was added.  Search for "(require".

Currently, there is still `i require', which takes
you to node `Named Features', where `require' is
covered.

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

[Jean-Christophe Helary]

> On May 11, 2020, at 4:28, Drew Adams <drew.adams@oracle.com> wrote:
> 
>> I'm actually surprised that nothing from the pre-package area was left
>> in the manual. I suppose there was something before package to indicate
>> how to install external code, wasn't there ?
>> 
>> Actually I'm checking the 21 manual here...
>> And I'm not finding much. Am I missing something ?
> 
> Yes, there was more mention of `require' in the Elisp
> manual before package.el was added.  Search for "(require".

Ok, I'll check again. Thank you.

> Currently, there is still `i require', which takes
> you to node `Named Features', where `require' is
> covered.

Indeed, and in my patch I refer to this section.

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

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

[Stefan Monnier]

> And I'm not finding much. Am I missing something ?

I think every package said how to do it.  E.g.

    put this file somewhere and then add the following to your .emacs:

        (add-to-list 'load-path "/where/I/put/your/package")
        (autoload 'your-package-mode "your-package")
        ...

A quick `grep -C3 '^;\+ *(autoload' **/*.el` shows that many of Emacs's
own files still come with such instructions.


        Stefan

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

[Jean-Christophe Helary]

> On May 11, 2020, at 4:35, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> And I'm not finding much. Am I missing something ?
> 
> I think every package said how to do it.  E.g.

Indeed. But people who write their own elisp files would need to have this information  somewhere in the manual don't you agree ?

I'll check what Drew mentioned earlier, ie references in the manual before package.el was provided and will try to rewrite the thing.

Thank you.

> 
>    put this file somewhere and then add the following to your .emacs:
> 
>        (add-to-list 'load-path "/where/I/put/your/package")
>        (autoload 'your-package-mode "your-package")
>        ...
> 
> A quick `grep -C3 '^;\+ *(autoload' **/*.el` shows that many of Emacs's
> own files still come with such instructions.


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

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

[Drew Adams]

> I'll check what Drew mentioned earlier, ie references in the manual
> before package.el was provided and will try to rewrite the thing.

I didn't find a lot, but there is more mention of "(require ".
I was surprised that I didn't find something like what you're
proposing.

There's a good explanation of this idiom,
at least, in `Named Features' (still there):

 (provide 'my-feature)  ; Ignored by byte compiler,
                        ;   evaluated by 'load'.
 (require 'my-feature)  ; Evaluated by byte compiler.

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

[Stefan Monnier]

>  (provide 'my-feature)  ; Ignored by byte compiler,
>                         ;   evaluated by 'load'.
>  (require 'my-feature)  ; Evaluated by byte compiler.

Yes, it used to be popular.  But it is the telltale sign of a recursive
dependency between packages, which is something better avoided (just
like `advice` is better avoided: we *do* want to support it because it's
really handy when you really need it, but don't abuse it).

So please don't go there unless you have to.


        Stefan

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

[Drew Adams]

> >  (provide 'my-feature)  ; Ignored by byte compiler,
> >                         ;   evaluated by 'load'.
> >  (require 'my-feature)  ; Evaluated by byte compiler.
> 
> Yes, it used to be popular.  But it is the telltale sign of a recursive
> dependency between packages, which is something better avoided (just
> like `advice` is better avoided: we *do* want to support it because
> it's really handy when you really need it, but don't abuse it).
> 
> So please don't go there unless you have to.

Not sure what you're suggesting.  Are you saying
that text should be removed from the manual?

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

[Stefan Monnier]

> Not sure what you're suggesting.  Are you saying
> that text should be removed from the manual?

Maybe, yes.  Or at least it should clarify that this practice is discouraged.


        Stefan

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

[Jean-Christophe Helary]

Drew, Stephan,

Please, let me go back to where this thread started and clarify what needs to be done before the conversation goes into a different direction.

I want to add the minimum set of information to allow emacs users to

1) permanently "install" code that they wrote
2) install code that other people wrote where instructions are not clear

Basically, that seems to mean:

1) Since people will search for "install" in the manual and the most relevant section is Packages we need to add a line and a link to the section about loading files and having them in the load path.

I did that already.

2) Now, it seems that there is no consensus about what to put in the init file to have that file load automatically when emacs starts, which is what a user would like to do. If 'require is not recommended then what is, considering that the phrasing would be "you *can*" and not "you *must*" and that a link to the most relevant section can be added that describes all the possibilities. I think we just need to add the most "benign" command that gets the job done.


When I'm done with that, I'll let you explore what needs to be written for package developers ;)

Thank you for your understanding.

Jean-Christophe 



> On May 11, 2020, at 13:40, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> Not sure what you're suggesting.  Are you saying
>> that text should be removed from the manual?
> 
> Maybe, yes.  Or at least it should clarify that this practice is discouraged.
> 
> 
>        Stefan
> 
> 

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

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

[Stefan Monnier]

> 1) Since people will search for "install" in the manual and the most
> relevant section is Packages we need to add a line and a link to the section
> about loading files and having them in the load path.
>
> I did that already.

Good.

> 2) Now, it seems that there is no consensus about what to put in the init
> file to have that file load automatically when emacs starts, which is what
> a user would like to do.

[ The first step is of course to make sure the file is found from
  `load-path`.  ]

If the file is needed simply because the user decided to split their
`.emacs` file into several separate files, then `load` (or `require`) is
probably fine.  That is the case where the file is a configuration
file, i.e. loading it changes Emacs's behavior.

If OTOH that other file is a package/library which provides a particular
feature (in which case, loading the file *should not* change Emacs's
behavior), then usually what should be done is add a few `autoload`s to
load the file on-demand.


        Stefan

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

[Drew Adams]

> > 2) Now, it seems that there is no consensus about what to put in the
> init
> > file to have that file load automatically when emacs starts, which is
> what
> > a user would like to do.
> 
> [ The first step is of course to make sure the file is found from
>   `load-path`.  ]
> 
> If the file is needed simply because the user decided to split their
> `.emacs` file into several separate files, then `load` (or `require`)
> is probably fine.  That is the case where the file is a configuration
> file, i.e. loading it changes Emacs's behavior.
> 
> If OTOH that other file is a package/library which provides a
> particular feature (in which case, loading the file *should not*
> change Emacs's behavior), then usually what should be done is add
> a few `autoload`s to load the file on-demand.

+1

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

[Jean-Christophe Helary]

> On May 12, 2020, at 0:09, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> 1) Since people will search for "install" in the manual and the most
>> relevant section is Packages we need to add a line and a link to the section
>> about loading files and having them in the load path.
>> 
>> I did that already.
> 
> Good.
> 
>> 2) Now, it seems that there is no consensus about what to put in the init
>> file to have that file load automatically when emacs starts, which is what
>> a user would like to do.
> 
> [ The first step is of course to make sure the file is found from
>  `load-path`.  ]

Like ask the user to manually do M-x load-library and see the result ?

This is somehow suggested in "Libraries of Lisp Code for Emacs" which I intend to refer to so I'm not sure there is a need to put too much emphasis here.

> If the file is needed simply because the user decided to split their
> `.emacs` file into several separate files, then `load` (or `require`) is
> probably fine.  That is the case where the file is a configuration
> file, i.e. loading it changes Emacs's behavior.
> 
> If OTOH that other file is a package/library which provides a particular
> feature (in which case, loading the file *should not* change Emacs's
> behavior), then usually what should be done is add a few `autoload`s to
> load the file on-demand.

Well, actually all this started because I wanted to install Drew's help-fns+.el and it happens that Drew uses "require".

So, in case I want to add a similar feature set, would 'require be too much ? Would (autoload 'help-fns+) be sufficient ?

When I have the information about this, I think I can make a satisfactory patch to the manual :)

Keep in mind that this addition is for users who know a minimal subset of emacs lisp (enough to play with their init file), not for authors.


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

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

[Stefan Monnier]

>> [ The first step is of course to make sure the file is found from
>>  `load-path`.  ]
>
> Like ask the user to manually do M-x load-library and see the result ?

Traditionally it was done either by telling the user to

    put this file somewhere in your `load-path`

or to

    (add-to-list 'load-path "/where/ever/you/put/that/file/")

> Well, actually all this started because I wanted to install Drew's
> help-fns+.el and it happens that Drew uses "require".

Then follow Drew's suggestion, since that's how he designed his library.

> So, in case I want to add a similar feature set, would 'require be too much ?

I know nothing about help-fns+ so I can't answer that.
But nowadays libraries should be designed for the case where they're
installed by a tool like package.el and in such a case, the user should
almost never need to `require` the package.

> Would (autoload 'help-fns+) be sufficient ?

`autoload` takes 2 args, the first being a function name and the second
the file in which that function is to be found.

> Keep in mind that this addition is for users who know a minimal subset of
> Emacs lisp (enough to play with their init file), not for authors.

Those users should *never* need to do that: either they install via
something like package.el or they follow steps in the package's
installation instructions.


        Stefan

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

[Jean-Christophe Helary]

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



> On May 12, 2020, at 12:21, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>> [ The first step is of course to make sure the file is found from
>>> `load-path`.  ]
>> 
>> Like ask the user to manually do M-x load-library and see the result ?
> 
> Traditionally it was done either by telling the user to
> 
>    put this file somewhere in your `load-path`
> 
> or to
> 
>    (add-to-list 'load-path "/where/ever/you/put/that/file/")

Excellent :)

>> Well, actually all this started because I wanted to install Drew's
>> help-fns+.el and it happens that Drew uses "require".
> 
> Then follow Drew's suggestion, since that's how he designed his library.
> 
>> So, in case I want to add a similar feature set, would 'require be too much ?
> 
> I know nothing about help-fns+ so I can't answer that.
> But nowadays libraries should be designed for the case where they're
> installed by a tool like package.el and in such a case, the user should
> almost never need to `require` the package.
> 
>> Would (autoload 'help-fns+) be sufficient ?
> 
> `autoload` takes 2 args, the first being a function name and the second
> the file in which that function is to be found.
> 
>> Keep in mind that this addition is for users who know a minimal subset of
>> Emacs lisp (enough to play with their init file), not for authors.
> 
> Those users should *never* need to do that: either they install via
> something like package.el

Which is already covered in the manual, so there is no need to consider that case.

> or they follow steps in the package's installation instructions.

Ok, I guess that's the information I was looking for :)

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



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

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 77a0e807c2..79cedb59a5 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1558,7 +1558,7 @@ 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}.
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index db3cf317ff..aa7c7e35bb 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -7,8 +7,12 @@ Packages
 @cindex Package
 @cindex Emacs Lisp package archive
 @cindex Package archive
+The traditional way to install Emacs Lisp code is to either install it
+in the Emacs Lisp @dfn{load path} or to add the path to the code to
+the load path list.  @xref{Lisp Libraries}. Then, the user should
+follow the instructions given by the code author.
 
-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.

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

[Drew Adams]

I don't quite understand this part of your diff:

+The traditional way to install Emacs Lisp code is to either install it
+in the Emacs Lisp @dfn{load path} or to add the path to the code to
+the load path list.

What does it mean to "install" code in `load-path'?
And how does that differ from adding the directory or
file of the code to `load-path' (IOW, why the "or")?

I think all that's involved in the "traditional"
approach, to make a library loadable by `require' or
`load-library' or autoloading, is to add the
directory for the library to `load-path'.

Does that "install" the library?  Dunno what that
word really means in this context.  What it does is
make it possible for `require' and `load-library' to
locate and load the library; that's all (AFAIK).

Keep in mind that loading a library/file need not be
something done systematically (e.g. by `require' in
a file that gets loaded), or something done only by
autoloading.  `load-library' is a command, to let
you load a library interactively.

Is there some clear definition of "installing" a
package in the doc?  Probably, but I haven't checked.

(I don't think of "installing" as applying to a
library that you just load, but maybe I should.  Is
"installing" a library, without using the package
system, defined anywhere in the doc?)

[BTW, for GNU Emacs, "path" means something different.
What you mean here is presumably the absolute file
name (of the directory or the file itself).]

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

[Jean-Christophe Helary]

> On May 13, 2020, at 0:46, Drew Adams <drew.adams@oracle.com> wrote:
> 
> I don't quite understand this part of your diff:
> 
> +The traditional way to install Emacs Lisp code is to either install it
> +in the Emacs Lisp @dfn{load path} or to add the path to the code to
> +the load path list.
> 
> What does it mean to "install" code in `load-path'?
> And how does that differ from adding the directory or
> file of the code to `load-path' (IOW, why the "or")?

I'm just using the wording that's found in other parts of the manual. Not trying to be fancy here :)

Emacs manual:
"If an Emacs Lisp file is installed in the Emacs Lisp load path (defined below), you can load it by typing M-x load-library, instead of using M-x load-file."

My understanding is that "install in the load path" means put the file in a path that Emacs already knows vs "add the path to load path" means make Emacs know about that new path.

> Keep in mind that loading a library/file need not be
> something done systematically (e.g. by `require' in
> a file that gets loaded), or something done only by
> autoloading.  `load-library' is a command, to let
> you load a library interactively.

Thank you. Reading the manual did not help much here. But that's ok for now. I'm not interested in knowing all the subtelties of loading files.

> Is there some clear definition of "installing" a
> package in the doc?  Probably, but I haven't checked.

Not that I can tell.

> (I don't think of "installing" as applying to a
> library that you just load, but maybe I should.

The Elisp Introduction seems to use "install" more as "be able to use the library" hence "load".

> Is "installing" a library, without using the package
> system, defined anywhere in the doc?)

Not that I can tell. That's the reason why I'm adding this line to the manual. To make that explicit.

> [BTW, for GNU Emacs, "path" means something different.
> What you mean here is presumably the absolute file
> name (of the directory or the file itself).]

I'm pretty sure I don't know the difference.


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

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

[Drew Adams]

> > I don't quite understand this part of your diff:
> >
> > +The traditional way to install Emacs Lisp code is to either install it
> > +in the Emacs Lisp @dfn{load path} or to add the path to the code to
> > +the load path list.
> >
> > What does it mean to "install" code in `load-path'?
> > And how does that differ from adding the directory or
> > file of the code to `load-path' (IOW, why the "or")?
> 
> I'm just using the wording that's found in other parts of the manual.
> Not trying to be fancy here :)
> 
> Emacs manual:
> "If an Emacs Lisp file is installed in the Emacs Lisp load path
> (defined below), you can load it by typing M-x load-library, instead of
> using M-x load-file."

OK, so my question is for whomever wrote that, I guess.

> My understanding is that "install in the load path" means put the file
> in a path that Emacs already knows vs "add the path to load path" means
> make Emacs know about that new path.

Maybe.  Not for me to say.  But if that's it then I
think your text doesn't really say that, I think.
I don't see anything in your text that suggests a
path that Emacs already knows.

> > Keep in mind that loading a library/file need not be
> > something done systematically (e.g. by `require' in
> > a file that gets loaded), or something done only by
> > autoloading.  `load-library' is a command, to let
> > you load a library interactively.
> 
> Thank you. Reading the manual did not help much here. But that's ok for
> now. I'm not interested in knowing all the subtelties of loading files.
> 
> > Is there some clear definition of "installing" a
> > package in the doc?  Probably, but I haven't checked.
> 
> Not that I can tell.

I didn't see one either.  But I see that the manual
has more or less that same text you cited at least
as far back as Emacs 20.  So my bad.  (I don't think
of that as really "installing", but that's me.)

> > [BTW, for GNU Emacs, "path" means something different.
> > What you mean here is presumably the absolute file
> > name (of the directory or the file itself).]
> 
> I'm pretty sure I don't know the difference.

For Emacs (and GNU, I think), a "path" is the kind of
thing you have as the value of your environment
variable PATH: a list of directories.

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

[Jean-Christophe Helary]

> On May 13, 2020, at 11:05, Drew Adams <drew.adams@oracle.com> wrote:
> 
>>> I don't quite understand this part of your diff:
>>> 
>>> +The traditional way to install Emacs Lisp code is to either install it
>>> +in the Emacs Lisp @dfn{load path} or to add the path to the code to
>>> +the load path list.
>>> 
>>> What does it mean to "install" code in `load-path'?
>>> And how does that differ from adding the directory or
>>> file of the code to `load-path' (IOW, why the "or")?
>> 
>> I'm just using the wording that's found in other parts of the manual.
>> Not trying to be fancy here :)
>> 
>> Emacs manual:
>> "If an Emacs Lisp file is installed in the Emacs Lisp load path
>> (defined below), you can load it by typing M-x load-library, instead of
>> using M-x load-file."
> 
> OK, so my question is for whomever wrote that, I guess.

:)

>> My understanding is that "install in the load path" means put the file
>> in a path that Emacs already knows vs "add the path to load path" means
>> make Emacs know about that new path.
> 
> Maybe.  Not for me to say.  But if that's it then I
> think your text doesn't really say that, I think.
> I don't see anything in your text that suggests a
> path that Emacs already knows.

+The traditional way to install Emacs Lisp code is to either install it
+in the Emacs Lisp @dfn{load path}

*** or to add the path to the code to
+the load path list.***

 @xref{Lisp Libraries}. Then, the user should
+follow the instructions given by the code author.

Isn't the *** part *** covering that ?

>>> [BTW, for GNU Emacs, "path" means something different.
>>> What you mean here is presumably the absolute file
>>> name (of the directory or the file itself).]
>> 
>> I'm pretty sure I don't know the difference.
> 
> For Emacs (and GNU, I think), a "path" is the kind of
> thing you have as the value of your environment
> variable PATH: a list of directories.

Ok, so that was close enough to my understanding. Thank you.


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

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

[Drew Adams]

> +The traditional way to install Emacs Lisp code is to either install it
> +in the Emacs Lisp @dfn{load path}
> 
> *** or to add the path to the code to
> +the load path list.***
> 
>  @xref{Lisp Libraries}. Then, the user should
> +follow the instructions given by the code author.
> 
> Isn't the *** part *** covering that ?

Maybe.  I guess so, if "the Emacs Lisp load path"
means the basic, predefined list of directories
to search, to which the value of var `load-path'
gets appended.  That wasn't clear to me from the
description.

I guess never mind what I said.

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

[Stefan Monnier]

>> +The traditional way to install Emacs Lisp code is to either install it
[...]
> "If an Emacs Lisp file is installed in the Emacs Lisp load path (defined

Nitpick: one says "file" the other "code".
I think "file" is right.


        Stefan

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

[Jean-Christophe Helary]

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

> On May 13, 2020, at 11:46, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>> +The traditional way to install Emacs Lisp code is to either install it
> [...]
>> "If an Emacs Lisp file is installed in the Emacs Lisp load path (defined
> 
> Nitpick: one says "file" the other "code".
> I think "file" is right.

Thank you.


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

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 77a0e807c2..79cedb59a5 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1558,7 +1558,7 @@ 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}.
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index db3cf317ff..aa7c7e35bb 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -7,8 +7,12 @@ Packages
 @cindex Package
 @cindex Emacs Lisp package archive
 @cindex Package archive
+The traditional way to install an Emacs Lisp file is to either install
+it in the Emacs Lisp @dfn{load path} or to add the path to the file to
+the load path list.  @xref{Lisp Libraries}. Then, the user should
+follow the instructions given by the code author.
 
-Emacs includes a facility that lets you easily download and install
+  Emacs now 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.

[-- Attachment #3: Type: text/plain, Size: 122 bytes --]


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

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Wed, 13 May 2020 12:02:15 +0900
> Cc: Drew Adams <drew.adams@oracle.com>, Emacs developers <emacs-devel@gnu.org>
> > On May 13, 2020, at 11:46, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> > 
> >>> +The traditional way to install Emacs Lisp code is to either install it
> > [...]
> >> "If an Emacs Lisp file is installed in the Emacs Lisp load path (defined
> > 
> > Nitpick: one says "file" the other "code".
> > I think "file" is right.
> 
> Thank you.

Thanks, I installed a more detailed description of these matters along
the lines you suggested.

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

[Jean-Christophe Helary]

> On May 16, 2020, at 19:23, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Wed, 13 May 2020 12:02:15 +0900
>> Cc: Drew Adams <drew.adams@oracle.com>, Emacs developers <emacs-devel@gnu.org>
>>> On May 13, 2020, at 11:46, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>> 
>>>>> +The traditional way to install Emacs Lisp code is to either install it
>>> [...]
>>>> "If an Emacs Lisp file is installed in the Emacs Lisp load path (defined
>>> 
>>> Nitpick: one says "file" the other "code".
>>> I think "file" is right.
>> 
>> Thank you.
> 
> Thanks, I installed a more detailed description of these matters along
> the lines you suggested.

I just checked out master and I'm not seeing it. Did you install it somewhere else ?


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

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
> Date: Sat, 16 May 2020 21:39:54 +0900
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>  drew.adams@oracle.com,
>  emacs-devel@gnu.org
> 
> > Thanks, I installed a more detailed description of these matters along
> > the lines you suggested.
> 
> I just checked out master and I'm not seeing it. Did you install it somewhere else ?

Look on the emacs-27 branch.  Documentation fixes are always installed
on the release branch.

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

[Jean-Christophe Helary]

> On May 16, 2020, at 23:38, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org>
>> Date: Sat, 16 May 2020 21:39:54 +0900
>> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,
>> drew.adams@oracle.com,
>> emacs-devel@gnu.org
>> 
>>> Thanks, I installed a more detailed description of these matters along
>>> the lines you suggested.
>> 
>> I just checked out master and I'm not seeing it. Did you install it somewhere else ?
> 
> Look on the emacs-27 branch.  Documentation fixes are always installed
> on the release branch.

Excellent ! Thank you very much.

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

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

[Drew Adams]

> > If the file is needed simply because the user decided to split their
> > `.emacs` file into several separate files, then `load` (or `require`)
> > is probably fine.  That is the case where the file is a configuration
> > file, i.e. loading it changes Emacs's behavior.
> >
> > If OTOH that other file is a package/library which provides a
> > particular feature (in which case, loading the file *should not*
> > change Emacs's behavior), then usually what should be done is add a
> > few autoload`s to load the file on-demand.
> 
> Well, actually all this started because I wanted to install
> Drew's help-fns+.el and it happens that Drew uses "require".

Here's a half-hearted excuse/explanation.

Loading help-fns+.el is a user (or other-library) choice.
And yes, loading it does change behavior - that's the aim.
It's not a normal library, in that sense.  Conventionally,
loading a library should not change behavior.  Mea culpa.

No, the changes are not optional (e.g., the different
behavior is not provided by a minor mode).  It's meant to,
in effect, _replace_ some of what help-fns.el does, without
replacing all of its code.  Think patch, if you like.
After loading it, you have, in a way, patched some of
help-fns.el.

Two of the `require's are soft requires: no error if not
found.  Again, a user choice: if those libraries are not
present in `load-path' then nothing happens.  They're not
really required.

Two of the `require's are hard: help-fns.el, wid-edit.el.

Yes, this way of doing things doesn't perfectly respect
the coding guidelines.  But hopefully the Commentary makes
clear that the library changes some behavior.  For example,
it points out `describe-*' commands that it redefines.

> So, in case I want to add a similar feature set, would
> 'require be too much ? Would (autoload 'help-fns+) be
> sufficient ?
> 
> When I have the information about this, I think I can
> make a satisfactory patch to the manual :)
> 
> Keep in mind that this addition is for users who know
> a minimal subset of emacs lisp (enough to play with
> their init file), not for authors.

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

[Drew Adams]

In my opinion (just one user), a user's notion of
"installing" is one thing.  Loading a Lisp file
is another thing.  There's some overlap, but the
Elisp, and even the Emacs, manual should at least
present _loading_ Lisp code (byte-compiled or not).

And in that context, `require', `provide', and
"features" are important constructs to document.
There's no wall between Elisp programmers and
Emacs users.  Many users are lispers, and many who
are not could be, to everyone's advantage.

I don't think the Emacs doc should tell users not
to use `require'.  It can certainly tell them how
convenient it may be to use the package system.
But package installing is not exactly the same
thing as loading Lisp files, and yes, each can be
useful for Emacs users - at least some users.

Just one opinion.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > And in that context, `require', `provide', and
  > "features" are important constructs to document.

I agree.  A package facility does not obsolete those functions.
Please don't remove them from the Lisp manuals.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Stefan Monnier]

>>> And I'm not finding much. Am I missing something ?
>> I think every package said how to do it.  E.g.
> Indeed. But people who write their own elisp files would need to have this
> information  somewhere in the manual don't you agree ?

Not sure what "this information" you're thinking of.

The code needed will vary from package to package, so maybe we could put
in the manual something like "look at the doc of your Elisp package, it
will surely say what to do".  But otherwise it's going to take a lot
more work to explain the different possible situations, and when to
use what.

OTOH, some of that info might be useful for package *authors* so they
design their package properly, with their `;;;###autoload` cookies where
they belong.


        Stefan