* bug#60366: [PATCH] Simplify introduction of use-package manual
@ 2022-12-27 21:43 Kévin Le Gouguec
2022-12-30 10:00 ` Kévin Le Gouguec
2022-12-31 9:52 ` Stefan Kangas
0 siblings, 2 replies; 4+ messages in thread
From: Kévin Le Gouguec @ 2022-12-27 21:43 UTC (permalink / raw)
To: 60366
[-- Attachment #1: Type: text/plain, Size: 2022 bytes --]
Tags: patch
Hello Emacs,
A couple of things intrigue me in the current introduction of the
use-package manual:
> This chapter provides instructions and examples for quickly getting
> started with use-package. The first thing you need to do is make sure
> that ‘use-package’ itself is loaded. To do that, put this at the top of
> your init file:
>
> (require 'use-package)
>
> The above makes the ‘use-macro’ available for us in the rest of your
> init file. In this manual, we say that each call to ‘use-macro’ is a
> “declaration”, to highlight the declarative nature of its syntax.
— (info "(use-package) Getting Started")
(a) I don't think use-package defines anything called "use-macro";
guessing this was supposed to read "‘use-package’ macro" instead? I
guess the former could be a shorthand for the latter, but it's not used
anywhere else in the manual.
(b) AFAICT use-package is autoloaded, so there should be no need for the
user to (require 'use-package)?
I've made a patch against emacs-29 to simplify this part of the manual
according to these hypotheses. I hope they are correct; apologies for
the noise if not.
(And even if the hypotheses are correct, I hope the patch is OK: the
second sentence in this tentative new paragraph feels a bit disconnected
from the first to me. Still, I figured it was worth submitting anyway
just to validate those hypotheses before racking more of my brain on
optimal wording)
Thanks.
In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.24, cairo version 1.16.0) of 2022-12-26 built on hirondell
Repository revision: 2ffe1494e16381cfc7fec95a6a0879f268df3e95
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Debian GNU/Linux 11 (bullseye)
Configured using:
'configure --cache-file=/home/peniblec/.cache/emacs/config,src,emacs
--with-cairo --with-gconf --with-sqlite3 --with-xinput2'
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Simplify-introduction-of-use-package-manual.patch --]
[-- Type: text/patch, Size: 1572 bytes --]
From 15b50490cb87b19888dcb95b84a78d05686e7b89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Le=20Gouguec?= <kevin.legouguec@gmail.com>
Date: Tue, 27 Dec 2022 15:40:43 +0100
Subject: [PATCH] Simplify introduction of use-package manual
* doc/misc/use-package.texi (Getting Started): Do not advise requiring
the package, since the macro is autoloaded; also correct the macro's
name.
---
doc/misc/use-package.texi | 16 +++-------------
1 file changed, 3 insertions(+), 13 deletions(-)
diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index c587d23d74b..1d0e38a1eca 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -132,19 +132,9 @@ Getting Started
@cindex quick-start instructions
This chapter provides instructions and examples for quickly getting
-started with use-package. The first thing you need to do is make sure
-that @file{use-package} itself is loaded. To do that, put this at the
-top of your init file:
-
-@lisp
-(require 'use-package)
-@end lisp
-
-@cindex declaration
-The above makes the @code{use-macro} available for us in the rest of
-your init file. In this manual, we say that each call to
-@code{use-macro} is a @dfn{declaration}, to highlight the declarative
-nature of its syntax.
+started with use-package. In this manual, we say that each call to
+the @code{use-package} macro in your init file is a @dfn{declaration},
+to highlight the declarative nature of its syntax.
To unconditionally load a package named @samp{foo}, add the following
declaration to your init file:
--
2.30.2
^ permalink raw reply related [flat|nested] 4+ messages in thread
* bug#60366: [PATCH] Simplify introduction of use-package manual
2022-12-27 21:43 bug#60366: [PATCH] Simplify introduction of use-package manual Kévin Le Gouguec
@ 2022-12-30 10:00 ` Kévin Le Gouguec
2022-12-31 9:52 ` Stefan Kangas
1 sibling, 0 replies; 4+ messages in thread
From: Kévin Le Gouguec @ 2022-12-30 10:00 UTC (permalink / raw)
To: 60366; +Cc: Stefan Kangas
[ CC'ing StefanK, since these specific bits were authored in 2022-12-08
"Add new use-package manual" (98e54f597e1) ]
Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:
> Hello Emacs,
>
> A couple of things intrigue me in the current introduction of the
> use-package manual:
>
>> This chapter provides instructions and examples for quickly getting
>> started with use-package. The first thing you need to do is make sure
>> that ‘use-package’ itself is loaded. To do that, put this at the top of
>> your init file:
>>
>> (require 'use-package)
>>
>> The above makes the ‘use-macro’ available for us in the rest of your
>> init file. In this manual, we say that each call to ‘use-macro’ is a
>> “declaration”, to highlight the declarative nature of its syntax.
> — (info "(use-package) Getting Started")
>
> (a) I don't think use-package defines anything called "use-macro";
> guessing this was supposed to read "‘use-package’ macro" instead? I
> guess the former could be a shorthand for the latter, but it's not used
> anywhere else in the manual.
>
> (b) AFAICT use-package is autoloaded, so there should be no need for the
> user to (require 'use-package)?
>
> I've made a patch against emacs-29 to simplify this part of the manual
> according to these hypotheses. I hope they are correct; apologies for
> the noise if not.
>
> (And even if the hypotheses are correct, I hope the patch is OK: the
> second sentence in this tentative new paragraph feels a bit disconnected
> from the first to me. Still, I figured it was worth submitting anyway
> just to validate those hypotheses before racking more of my brain on
> optimal wording)
>
> Thanks.
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#60366: [PATCH] Simplify introduction of use-package manual
2022-12-27 21:43 bug#60366: [PATCH] Simplify introduction of use-package manual Kévin Le Gouguec
2022-12-30 10:00 ` Kévin Le Gouguec
@ 2022-12-31 9:52 ` Stefan Kangas
2022-12-31 11:42 ` Kévin Le Gouguec
1 sibling, 1 reply; 4+ messages in thread
From: Stefan Kangas @ 2022-12-31 9:52 UTC (permalink / raw)
To: Kévin Le Gouguec; +Cc: 60366-done
Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:
> I've made a patch against emacs-29 to simplify this part of the manual
Thanks for the patch! It looks good to me, so I pushed it to emacs-29
(commit 01acecc79c3).
^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#60366: [PATCH] Simplify introduction of use-package manual
2022-12-31 9:52 ` Stefan Kangas
@ 2022-12-31 11:42 ` Kévin Le Gouguec
0 siblings, 0 replies; 4+ messages in thread
From: Kévin Le Gouguec @ 2022-12-31 11:42 UTC (permalink / raw)
To: Stefan Kangas; +Cc: 60366-done
Stefan Kangas <stefankangas@gmail.com> writes:
> Kévin Le Gouguec <kevin.legouguec@gmail.com> writes:
>
>> I've made a patch against emacs-29 to simplify this part of the manual
>
> Thanks for the patch! It looks good to me, so I pushed it to emacs-29
> (commit 01acecc79c3).
My pleasure 🙏
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2022-12-31 11:42 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-12-27 21:43 bug#60366: [PATCH] Simplify introduction of use-package manual Kévin Le Gouguec
2022-12-30 10:00 ` Kévin Le Gouguec
2022-12-31 9:52 ` Stefan Kangas
2022-12-31 11:42 ` Kévin Le Gouguec
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).