bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Drew Adams]

Apparently (at least from searching package.el and (emacs) `Packages'
and its subnodes), nowhere do we tell users the effect of using the
package system on `load-path'.  (Variable `load-path' is mentioned in a
couple of doc strings, but only for "internal-only" functions.)

There is this comment in the Commentary of `package.el':

;; At activation time we will set up the load-path and the info path,
;; and we will load the package's autoloads.  If a package's
;; dependencies are not available, we will not activate that package.

I think it is important (helpful) to explicitly make the connection for
users between `load-path' and the package system.  Please consider
making it clear.  Even just a statement such as the one in that comment
would help.

Here is one demonstration of the confusion that might be avoided if such
information were made more readily available:

http://lists.gnu.org/archive/html/help-gnu-emacs/2015-10/msg00331.html

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-10-06
Bzr revision: a4a98a1b2568793ead43e824ecf227768759df12
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Apparently (at least from searching package.el and (emacs) `Packages'
> and its subnodes), nowhere do we tell users the effect of using the
> package system on `load-path'.  (Variable `load-path' is mentioned in a
> couple of doc strings, but only for "internal-only" functions.)
>
> There is this comment in the Commentary of `package.el':
>
> ;; At activation time we will set up the load-path and the info path,
> ;; and we will load the package's autoloads.  If a package's
> ;; dependencies are not available, we will not activate that package.
>
> I think it is important (helpful) to explicitly make the connection for
> users between `load-path' and the package system.  Please consider
> making it clear.  Even just a statement such as the one in that comment
> would help.

Do you have a suggestion as to where in the manual we should mention the
load-path impact?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Drew Adams]

> > Apparently (at least from searching package.el and (emacs) `Packages'
> > and its subnodes), nowhere do we tell users the effect of using the
> > package system on `load-path'.  (Variable `load-path' is mentioned in a
> > couple of doc strings, but only for "internal-only" functions.)
> >
> > There is this comment in the Commentary of `package.el':
> >
> > ;; At activation time we will set up the load-path and the info path,
> > ;; and we will load the package's autoloads.  If a package's
> > ;; dependencies are not available, we will not activate that package.
> >
> > I think it is important (helpful) to explicitly make the connection for
> > users between `load-path' and the package system.  Please consider
> > making it clear.  Even just a statement such as the one in that comment
> > would help.
> 
> Do you have a suggestion as to where in the manual we should mention the
> load-path impact?

I'm no expert on package.el or its doc, but I think it should 
be mentioned somewhere where we introduce using the package
system.  We should mention what using the package system has
as effects.  We no doubt explain what it does wrt downloading
to certain locations (which you control), automatically
byte-compiling, etc.  The relation with `load-path' should,
I expect, be mentioned in the same general area of the doc.

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Noam Postavsky]

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

> Do you have a suggestion as to where in the manual we should mention the
> load-path impact?

How about in Package Installation? (see attached patch)

[-- Attachment #2: v1-0001-Document-more-details-of-package-activation.patch --]
[-- Type: text/x-patch, Size: 1573 bytes --]

From c2c144a315d276b97e20ed66785f5060eaed8406 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Mon, 27 Jun 2016 00:26:16 -0400
Subject: [PATCH v1] Document more details of package activation

* doc/emacs/package.texi (Package Installation): Explain that package
activation adds to load-path (Bug #21704).
---
 doc/emacs/package.texi | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 3c09983..f80cae6 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -238,10 +238,12 @@ Package Installation
 
   Once a package is downloaded and installed, it is @dfn{loaded} into
 the current Emacs session.  Loading a package is not quite the same as
-loading a Lisp library (@pxref{Lisp Libraries}); its effect varies
-from package to package.  Most packages just make some new commands
-available, while others have more wide-ranging effects on the Emacs
-session.  For such information, consult the package's help buffer.
+loading a Lisp library (@pxref{Lisp Libraries}); loading a package
+adds its directory to @var{load-path} and loads its autoloads.  The
+effect of a package's autoloads varies from package to package.  Most
+packages just make some new commands available, while others have more
+wide-ranging effects on the Emacs session.  For such information,
+consult the package's help buffer.
 
   By default, Emacs also automatically loads all installed packages in
 subsequent Emacs sessions.  This happens at startup, after processing
-- 
2.8.0

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Drew Adams]

> > Do you have a suggestion as to where in the manual we should mention the
> > load-path impact?
> 
> How about in Package Installation? (see attached patch)

The location might be OK, but I don't see how that text responds to the
bug report.  I don't see how it "tell[s] users the effect of using the
package system on `load-path'."  It doesn't "mention what using the
package system has as effects [on `load-path']."  It doesn't even
mention variable `load-path'.  Does it have no effect on `load-path'?
Does it alter `load-path' (how)?

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Noam Postavsky]

On Mon, Jun 27, 2016 at 1:40 AM, Drew Adams <drew.adams@oracle.com> wrote:
>> > Do you have a suggestion as to where in the manual we should mention the
>> > load-path impact?
>>
>> How about in Package Installation? (see attached patch)
>
> It doesn't even
> mention variable `load-path'.

Huh? Did you read the wrong patch? (I've double checked that I posted
the right one)

+loading a Lisp library (@pxref{Lisp Libraries}); loading a package
+adds its directory to @var{load-path} and loads its autoloads.  The
                       ^^^^^^^^^^^^^^^
+effect of a package's autoloads varies from package to package.  Most

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Drew Adams]

> Huh? Did you read the wrong patch? (I've double checked that I posted
> the right one)

My bad; sorry.  Yes, I read it, but clearly I didn't read it very well!
Yes, that seems to do the job.  Thx.

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Mon, 27 Jun 2016 00:45:07 -0400
> Cc: Lars Ingebrigtsen <larsi@gnus.org>
> 
> > Do you have a suggestion as to where in the manual we should mention the
> > load-path impact?
> 
> How about in Package Installation? (see attached patch)

Thanks.  One comment:

> +loading a Lisp library (@pxref{Lisp Libraries}); loading a package
> +adds its directory to @var{load-path} and loads its autoloads.  The

Please use @code{load-path}, not @var.  The latter is for things like
function arguments, which stand for some particular value, whereas
load-path is a literal symbol.

bug#21704: 25.0.50; Package (package.el) doc should mention effects on `load-path'

[Noam Postavsky]

Version: 25.1

On Mon, Jun 27, 2016 at 11:37 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> Please use @code{load-path}, not @var.

Done.