* use-package documentation
@ 2022-12-30 4:03 Richard Stallman
2022-12-30 9:01 ` Eli Zaretskii
` (2 more replies)
0 siblings, 3 replies; 15+ messages in thread
From: Richard Stallman @ 2022-12-30 4:03 UTC (permalink / raw)
To: emacs-devel
[[[ 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)
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: use-package documentation
2022-12-30 4:03 use-package documentation Richard Stallman
@ 2022-12-30 9:01 ` Eli Zaretskii
2022-12-31 11:28 ` Stefan Kangas
2023-01-01 3:04 ` Richard Stallman
2022-12-30 9:02 ` Philip Kaludercic
2023-01-06 6:03 ` David Masterson
2 siblings, 2 replies; 15+ messages in thread
From: Eli Zaretskii @ 2022-12-30 9:01 UTC (permalink / raw)
To: rms; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2022-12-30 9:01 ` Eli Zaretskii
@ 2022-12-31 11:28 ` Stefan Kangas
2023-01-01 8:39 ` Eli Zaretskii
2023-01-01 3:04 ` Richard Stallman
1 sibling, 1 reply; 15+ messages in thread
From: Stefan Kangas @ 2022-12-31 11:28 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: rms, emacs-devel
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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2022-12-31 11:28 ` Stefan Kangas
@ 2023-01-01 8:39 ` Eli Zaretskii
0 siblings, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2023-01-01 8:39 UTC (permalink / raw)
To: Stefan Kangas; +Cc: rms, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2022-12-30 9:01 ` Eli Zaretskii
2022-12-31 11:28 ` Stefan Kangas
@ 2023-01-01 3:04 ` Richard Stallman
2023-01-01 6:46 ` Eli Zaretskii
1 sibling, 1 reply; 15+ messages in thread
From: Richard Stallman @ 2023-01-01 3:04 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: emacs-devel
[[[ 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)
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-01 3:04 ` Richard Stallman
@ 2023-01-01 6:46 ` Eli Zaretskii
2023-01-04 19:23 ` John Wiegley
0 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2023-01-01 6:46 UTC (permalink / raw)
To: rms; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-01 6:46 ` Eli Zaretskii
@ 2023-01-04 19:23 ` John Wiegley
2023-01-05 10:36 ` Stefan Kangas
2023-01-06 4:37 ` Richard Stallman
0 siblings, 2 replies; 15+ messages in thread
From: John Wiegley @ 2023-01-04 19:23 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: rms, emacs-devel
>>>>> "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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-04 19:23 ` John Wiegley
@ 2023-01-05 10:36 ` Stefan Kangas
2023-01-05 11:19 ` Eli Zaretskii
2023-01-06 4:37 ` Richard Stallman
1 sibling, 1 reply; 15+ messages in thread
From: Stefan Kangas @ 2023-01-05 10:36 UTC (permalink / raw)
To: John Wiegley, Eli Zaretskii; +Cc: rms, emacs-devel
"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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-05 10:36 ` Stefan Kangas
@ 2023-01-05 11:19 ` Eli Zaretskii
0 siblings, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2023-01-05 11:19 UTC (permalink / raw)
To: Stefan Kangas; +Cc: johnw, rms, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-04 19:23 ` John Wiegley
2023-01-05 10:36 ` Stefan Kangas
@ 2023-01-06 4:37 ` Richard Stallman
2023-01-06 7:13 ` Eli Zaretskii
1 sibling, 1 reply; 15+ messages in thread
From: Richard Stallman @ 2023-01-06 4:37 UTC (permalink / raw)
To: John Wiegley; +Cc: eliz, emacs-devel
[[[ 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)
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-06 4:37 ` Richard Stallman
@ 2023-01-06 7:13 ` Eli Zaretskii
0 siblings, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2023-01-06 7:13 UTC (permalink / raw)
To: rms; +Cc: johnw, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2022-12-30 4:03 use-package documentation Richard Stallman
2022-12-30 9:01 ` Eli Zaretskii
@ 2022-12-30 9:02 ` Philip Kaludercic
2023-01-06 6:03 ` David Masterson
2 siblings, 0 replies; 15+ messages in thread
From: Philip Kaludercic @ 2022-12-30 9:02 UTC (permalink / raw)
To: Richard Stallman; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2022-12-30 4:03 use-package documentation Richard Stallman
2022-12-30 9:01 ` Eli Zaretskii
2022-12-30 9:02 ` Philip Kaludercic
@ 2023-01-06 6:03 ` David Masterson
2023-01-06 7:06 ` Ihor Radchenko
2023-01-06 7:43 ` Eli Zaretskii
2 siblings, 2 replies; 15+ messages in thread
From: David Masterson @ 2023-01-06 6:03 UTC (permalink / raw)
To: Richard Stallman; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-06 6:03 ` David Masterson
@ 2023-01-06 7:06 ` Ihor Radchenko
2023-01-06 7:43 ` Eli Zaretskii
1 sibling, 0 replies; 15+ messages in thread
From: Ihor Radchenko @ 2023-01-06 7:06 UTC (permalink / raw)
To: David Masterson; +Cc: Richard Stallman, emacs-devel
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>
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: use-package documentation
2023-01-06 6:03 ` David Masterson
2023-01-06 7:06 ` Ihor Radchenko
@ 2023-01-06 7:43 ` Eli Zaretskii
1 sibling, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2023-01-06 7:43 UTC (permalink / raw)
To: David Masterson; +Cc: rms, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2023-01-06 7:43 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-12-30 4:03 use-package documentation Richard Stallman
2022-12-30 9:01 ` Eli Zaretskii
2022-12-31 11:28 ` Stefan Kangas
2023-01-01 8:39 ` Eli Zaretskii
2023-01-01 3:04 ` Richard Stallman
2023-01-01 6:46 ` Eli Zaretskii
2023-01-04 19:23 ` John Wiegley
2023-01-05 10:36 ` Stefan Kangas
2023-01-05 11:19 ` Eli Zaretskii
2023-01-06 4:37 ` Richard Stallman
2023-01-06 7:13 ` Eli Zaretskii
2022-12-30 9:02 ` Philip Kaludercic
2023-01-06 6:03 ` David Masterson
2023-01-06 7:06 ` Ihor Radchenko
2023-01-06 7:43 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).