use-package documentation

use-package documentation

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

Should the documentation of use-package be merged into the Emacs Lisp
Reference Manual?

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

Re: use-package documentation

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Thu, 29 Dec 2022 23:03:43 -0500
> 
> Should the documentation of use-package be merged into the Emacs Lisp
> Reference Manual?

It is a relatively large manual (2K lines of Texinfo), so adding it is
somewhat problematic.  It is also half-way between user-level and
Lisp-level, so which manual should mention it is not clear.

I think we should perhaps mention it in both manuals, and leave it as
a separate manual.

Re: use-package documentation

[Philip Kaludercic]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
> Should the documentation of use-package be merged into the Emacs Lisp
> Reference Manual?

I don't think so, since use-package is not an arbitrary macro to be used
when programming Emacs Lisp.

Re: use-package documentation

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I think we should perhaps mention it in both manuals, and leave it as
> a separate manual.

Agreed.

However, while I think it makes sense to mention it in the emacs
manual, I don't currently see where it would fit in the elisp manual.
Perhaps it'd be enough to mention it in the emacs manual.

Re: use-package documentation

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

  > It is a relatively large manual (2K lines of Texinfo), so adding it is
  > somewhat problematic.  It is also half-way between user-level and
  > Lisp-level, so which manual should mention it is not clear.

People expect the Emacs Lisp Reference Manual to tell all about Emacs
Lisp except for things that are somewhat obscure.  People have said
that use-package is much more convenient than `require' for the .emacs
file.  If that is so, we can expect it to become widely used if we
make the community aware of it.

This argues that at least the most important/most widely used features
of `use-package' should be described in the Emacs Lisp Reference
Manual.  The rest of the could be left in a separate manual.

Where in the Emacs Lisp Reference Manual should those aspects of
`use-package' go?  Perhaps in the node, The Init File.  Or in a new
node, added just after that one, to contain "useful things to use in
your init file".

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

Re: use-package documentation

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: emacs-devel@gnu.org
> Date: Sat, 31 Dec 2022 22:04:23 -0500
> 
>   > It is a relatively large manual (2K lines of Texinfo), so adding it is
>   > somewhat problematic.  It is also half-way between user-level and
>   > Lisp-level, so which manual should mention it is not clear.
> 
> People expect the Emacs Lisp Reference Manual to tell all about Emacs
> Lisp except for things that are somewhat obscure.  People have said
> that use-package is much more convenient than `require' for the .emacs
> file.  If that is so, we can expect it to become widely used if we
> make the community aware of it.
> 
> This argues that at least the most important/most widely used features
> of `use-package' should be described in the Emacs Lisp Reference
> Manual.  The rest of the could be left in a separate manual.

That is already a lot, AFAICT.  use-package's features are generally
present only if they are very useful.

And I don't really understand the urge to have it in the ELisp manual:
a cross-reference to another manual is as easy to follow as a
cross-reference to another node within the same manual.  In many cases
the reader will not even be aware he or she is reading a different
manual.  So what problem do we want to solve by placing the
use-package stuff in the ELisp manual?

> Where in the Emacs Lisp Reference Manual should those aspects of
> `use-package' go?  Perhaps in the node, The Init File.  Or in a new
> node, added just after that one, to contain "useful things to use in
> your init file".

If it's just a short mention, probably in The Init File.  But I also
wanted to mention it in the Emacs User manual, where we describe some
simple customizations, and give a couple of examples there.

Re: use-package documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 31 Dec 2022 12:28:57 +0100
> Cc: rms@gnu.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I think we should perhaps mention it in both manuals, and leave it as
> > a separate manual.
> 
> Agreed.
> 
> However, while I think it makes sense to mention it in the emacs
> manual, I don't currently see where it would fit in the elisp manual.
> Perhaps it'd be enough to mention it in the emacs manual.

I think I found good places in both manuals, please take a look at the
emacs-29 branch.

Re: use-package documentation

[John Wiegley]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:

EZ> And I don't really understand the urge to have it in the ELisp manual: a
EZ> cross-reference to another manual is as easy to follow as a
EZ> cross-reference to another node within the same manual. In many cases the
EZ> reader will not even be aware he or she is reading a different manual. So
EZ> what problem do we want to solve by placing the use-package stuff in the
EZ> ELisp manual?

To me it would feel strange to have it in the Elisp manual, since it's not
targeted at Emacs Lisp developers, but rather users. It seems to me that it
should be in a separate manual that is linked to from the Emacs user manual.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: use-package documentation

[Stefan Kangas]

"John Wiegley" <johnw@gnu.org> writes:

> To me it would feel strange to have it in the Elisp manual, since it's not
> targeted at Emacs Lisp developers, but rather users. It seems to me that it
> should be in a separate manual that is linked to from the Emacs user manual.

I tend to agree.

Re: use-package documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 5 Jan 2023 02:36:40 -0800
> Cc: rms@gnu.org, emacs-devel@gnu.org
> 
> "John Wiegley" <johnw@gnu.org> writes:
> 
> > To me it would feel strange to have it in the Elisp manual, since it's not
> > targeted at Emacs Lisp developers, but rather users. It seems to me that it
> > should be in a separate manual that is linked to from the Emacs user manual.
> 
> I tend to agree.

This is supposed to have happened already, please take a look at the
two manuals.

Re: use-package documentation

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

  > To me it would feel strange to have it in the Elisp manual, since it's not
  > targeted at Emacs Lisp developers, but rather users.

It is aimed at users who decide to write some Emacs Lisp code,
so I think it does fit in the Emacs Lisp References Manual.
But it would also fit in the Emacs Manual, where it describes
some basic kinds of Lisp that are useful in init files.

However, only a very brief description of use-package would accord
with the Emacs Manual's section on this.  A larger amount could accord
with the context of the Emacs Lisp Reference Manual.

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

Re: use-package documentation

[David Masterson]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
> Should the documentation of use-package be merged into the Emacs Lisp
> Reference Manual?

Question: is it too early to "integrate" use-package documentation in
standard Emacs documents when there are other variants of use-package
(quelpa, straight, etc.) out there that may enhance or replace it?

Personally, I could see use-package (or variant) be the standard tool
for providing a standard structure to an init file and, so, talking
about that structure and how use-package helps facilitate it would
belong in the "Customization" section of the Emacs manual.  This would
be for new users graduating from push button setup (M-x customize) into
the next level of "programming" Emacs to fit the environment they want.
References could point to the Elisp manual to go beyond the basics of
"initialization" (setq, setup functions, etc.) to full programming for
really special customization.

-- 
David Masterson

Re: use-package documentation

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Question: is it too early to "integrate" use-package documentation in
> standard Emacs documents when there are other variants of use-package
> (quelpa, straight, etc.) out there that may enhance or replace it?

quelpa and straight are completely different packages solving completely
different set of problems. They just _integrate_ with use-package.

use-package is for configuration. quelpa and straight are alternatives
to package.el

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: use-package documentation

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, emacs-devel@gnu.org
> Date: Thu, 05 Jan 2023 23:37:58 -0500
> 
> It is aimed at users who decide to write some Emacs Lisp code,
> so I think it does fit in the Emacs Lisp References Manual.
> But it would also fit in the Emacs Manual, where it describes
> some basic kinds of Lisp that are useful in init files.
> 
> However, only a very brief description of use-package would accord
> with the Emacs Manual's section on this.  A larger amount could accord
> with the context of the Emacs Lisp Reference Manual.

That's what I did about a week ago, so I think this issue can be put
to rest.

Re: use-package documentation

[Eli Zaretskii]

> From: David Masterson <dsmasterson@gmail.com>
> Cc: emacs-devel@gnu.org
> Date: Thu, 05 Jan 2023 22:03:57 -0800
> 
> Richard Stallman <rms@gnu.org> writes:
> 
> Question: is it too early to "integrate" use-package documentation in
> standard Emacs documents when there are other variants of use-package
> (quelpa, straight, etc.) out there that may enhance or replace it?
> 
> Personally, I could see use-package (or variant) be the standard tool
> for providing a standard structure to an init file and, so, talking
> about that structure and how use-package helps facilitate it would
> belong in the "Customization" section of the Emacs manual.  This would
> be for new users graduating from push button setup (M-x customize) into
> the next level of "programming" Emacs to fit the environment they want.
> References could point to the Elisp manual to go beyond the basics of
> "initialization" (setq, setup functions, etc.) to full programming for
> really special customization.

This is no longer a theoretical argument: use-package is now shortly
described in both core manuals as I thought it should be, with a
cross-reference to the full manual that came with use-package.  So
please review what's in the manuals now, and if you have concrete
suggestions for changes or improvements, please post such specific
suggestions wrt the existing text in the manuals.