* Re: [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules
2024-03-16 22:37 14% ` Štěpán Němec
@ 2024-03-18 8:29 9% ` Eric Wong
0 siblings, 0 replies; 4+ results
From: Eric Wong @ 2024-03-18 8:29 UTC (permalink / raw)
To: Štěpán Němec; +Cc: meta
Štěpán Němec <stepnem@smrk.net> wrote:
> On Sat, 16 Mar 2024 21:27:56 +0000
> Eric Wong wrote:
>
> > Štěpán Němec <stepnem@smrk.net> wrote:
> >> The difference between the "numerous optional modules"
> >> section (containing only two modules) and the "everything
> >> else optional" section was unclear (to me, at least).
> >> Just put both under a single heading.
> >
> > <snip>
> >
> >> +++ b/INSTALL
> >> @@ -58,7 +58,8 @@ Where "deb" indicates package names for Debian-derived distributions,
> >> "pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
> >> distributions (only known to work on Fedora).
> >>
> >> -Numerous optional modules are likely to be useful as well:
> >> +Numerous optional modules might be useful as well, depending
> >> +on your use case and preferences:
> >>
> >
> > OK, I like the first change.
> >
> >> - DBD::SQLite deb: libdbd-sqlite3-perl
> >> pkg: p5-DBD-SQLite
> >> @@ -71,8 +72,6 @@ Numerous optional modules are likely to be useful as well:
> >> rpm: perl-Search-Xapian
> >> (required for lei; HTTP and IMAP search)
> >>
> >> -Every effort has been to make everything else optional:
> >> -
> >
> > I consider DBD::SQLite and Xapian significantly more important
> > than the rest, so I favor keeping the above line.
>
> The main issue I see with that (as mentioned in my commit
> message) is that you first say numerous optional modules are
> useful, list only two modules after that, then say
> everything else is optional. "else"? So, all modules are
> optional, but some are more optional than others? :-P
>
> I'd say a single heading and keeping further details to the
> parentheticals pertaining to specific modules is both
> clearer and easier to maintain, but whatever version you
> choose, I as reader see the following issues with the old
> text (and at least some of those issues would remain if you
> kept my first hunk and not the second, as you suggest):
>
> - the difference between the two sections is unclear
> - it doesn't make sense to first single out two modules as
> optional, and then continue with "make everything else
> optional"
> - two are not "numerous"
> - "Every effort has been to make everything else optional"
> sounds weird to me. Is "made" missing after "been"?
Yes, my brain was interpolating "made" in without realizing it
wasn't in the text :x
> Or maybe "We've tried to make everything else optional" or
> "Everything else is supposed to be optional"?
> - Perhaps "optional" isn't really the right word for the
> general description to begin with, given that some modules
> are required in some cases (indicated by parentheticals)?
Yeah, probably "optional" is the wrong word.
> A different attempt based on your feedback:
OK, pushed as commit 7de64dc25f8348f902f2815d520ecce3d0e90ca8
Thanks.
^ permalink raw reply [relevance 9%]
* Re: [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules
2024-03-16 21:27 9% ` Eric Wong
@ 2024-03-16 22:37 14% ` Štěpán Němec
2024-03-18 8:29 9% ` Eric Wong
0 siblings, 1 reply; 4+ results
From: Štěpán Němec @ 2024-03-16 22:37 UTC (permalink / raw)
To: Eric Wong; +Cc: meta
On Sat, 16 Mar 2024 21:27:56 +0000
Eric Wong wrote:
> Štěpán Němec <stepnem@smrk.net> wrote:
>> The difference between the "numerous optional modules"
>> section (containing only two modules) and the "everything
>> else optional" section was unclear (to me, at least).
>> Just put both under a single heading.
>
> <snip>
>
>> +++ b/INSTALL
>> @@ -58,7 +58,8 @@ Where "deb" indicates package names for Debian-derived distributions,
>> "pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
>> distributions (only known to work on Fedora).
>>
>> -Numerous optional modules are likely to be useful as well:
>> +Numerous optional modules might be useful as well, depending
>> +on your use case and preferences:
>>
>
> OK, I like the first change.
>
>> - DBD::SQLite deb: libdbd-sqlite3-perl
>> pkg: p5-DBD-SQLite
>> @@ -71,8 +72,6 @@ Numerous optional modules are likely to be useful as well:
>> rpm: perl-Search-Xapian
>> (required for lei; HTTP and IMAP search)
>>
>> -Every effort has been to make everything else optional:
>> -
>
> I consider DBD::SQLite and Xapian significantly more important
> than the rest, so I favor keeping the above line.
The main issue I see with that (as mentioned in my commit
message) is that you first say numerous optional modules are
useful, list only two modules after that, then say
everything else is optional. "else"? So, all modules are
optional, but some are more optional than others? :-P
I'd say a single heading and keeping further details to the
parentheticals pertaining to specific modules is both
clearer and easier to maintain, but whatever version you
choose, I as reader see the following issues with the old
text (and at least some of those issues would remain if you
kept my first hunk and not the second, as you suggest):
- the difference between the two sections is unclear
- it doesn't make sense to first single out two modules as
optional, and then continue with "make everything else
optional"
- two are not "numerous"
- "Every effort has been to make everything else optional"
sounds weird to me. Is "made" missing after "been"?
Or maybe "We've tried to make everything else optional" or
"Everything else is supposed to be optional"?
- Perhaps "optional" isn't really the right word for the
general description to begin with, given that some modules
are required in some cases (indicated by parentheticals)?
A different attempt based on your feedback:
-- >8 --
Subject: [PATCH] INSTALL: try to be less confusing about optional modules
---
INSTALL | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/INSTALL b/INSTALL
index c04831c2fb5b..3c5890b43517 100644
--- a/INSTALL
+++ b/INSTALL
@@ -58,7 +58,7 @@ Where "deb" indicates package names for Debian-derived distributions,
"pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
distributions (only known to work on Fedora).
-Numerous optional modules are likely to be useful as well:
+Most users will likely also want the following:
- DBD::SQLite deb: libdbd-sqlite3-perl
pkg: p5-DBD-SQLite
@@ -71,7 +71,8 @@ Numerous optional modules are likely to be useful as well:
rpm: perl-Search-Xapian
(required for lei; HTTP and IMAP search)
-Every effort has been to make everything else optional:
+Other modules might be useful as well, depending on your use case and
+preferences:
- Plack deb: libplack-perl
pkg: p5-Plack
base-commit: 5e8068b28aa01befa9c6fa7368db956148816189
prerequisite-patch-id: fc68213abff90eb709806fcae4dad389f2e59959
--
2.44.0
Thanks,
Štěpán
^ permalink raw reply related [relevance 14%]
* Re: [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules
2024-03-15 14:30 9% ` [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules Štěpán Němec
@ 2024-03-16 21:27 9% ` Eric Wong
2024-03-16 22:37 14% ` Štěpán Němec
0 siblings, 1 reply; 4+ results
From: Eric Wong @ 2024-03-16 21:27 UTC (permalink / raw)
To: Štěpán Němec; +Cc: meta
Štěpán Němec <stepnem@smrk.net> wrote:
> The difference between the "numerous optional modules"
> section (containing only two modules) and the "everything
> else optional" section was unclear (to me, at least).
> Just put both under a single heading.
<snip>
> +++ b/INSTALL
> @@ -58,7 +58,8 @@ Where "deb" indicates package names for Debian-derived distributions,
> "pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
> distributions (only known to work on Fedora).
>
> -Numerous optional modules are likely to be useful as well:
> +Numerous optional modules might be useful as well, depending
> +on your use case and preferences:
>
OK, I like the first change.
> - DBD::SQLite deb: libdbd-sqlite3-perl
> pkg: p5-DBD-SQLite
> @@ -71,8 +72,6 @@ Numerous optional modules are likely to be useful as well:
> rpm: perl-Search-Xapian
> (required for lei; HTTP and IMAP search)
>
> -Every effort has been to make everything else optional:
> -
I consider DBD::SQLite and Xapian significantly more important
than the rest, so I favor keeping the above line.
> - Plack deb: libplack-perl
> pkg: p5-Plack
> rpm: perl-Plack, perl-Plack-Test,
^ permalink raw reply [relevance 9%]
* [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules
@ 2024-03-15 14:30 9% ` Štěpán Němec
2024-03-16 21:27 9% ` Eric Wong
0 siblings, 1 reply; 4+ results
From: Štěpán Němec @ 2024-03-15 14:30 UTC (permalink / raw)
To: meta
The difference between the "numerous optional modules"
section (containing only two modules) and the "everything
else optional" section was unclear (to me, at least).
Just put both under a single heading.
---
INSTALL | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/INSTALL b/INSTALL
index c04831c2fb5b..9672ba8cf6fa 100644
--- a/INSTALL
+++ b/INSTALL
@@ -58,7 +58,8 @@ Where "deb" indicates package names for Debian-derived distributions,
"pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based
distributions (only known to work on Fedora).
-Numerous optional modules are likely to be useful as well:
+Numerous optional modules might be useful as well, depending
+on your use case and preferences:
- DBD::SQLite deb: libdbd-sqlite3-perl
pkg: p5-DBD-SQLite
@@ -71,8 +72,6 @@ Numerous optional modules are likely to be useful as well:
rpm: perl-Search-Xapian
(required for lei; HTTP and IMAP search)
-Every effort has been to make everything else optional:
-
- Plack deb: libplack-perl
pkg: p5-Plack
rpm: perl-Plack, perl-Plack-Test,
--
2.44.0
^ permalink raw reply related [relevance 9%]
Results 1-4 of 4 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2024-03-15 14:30 [PATCH 1/2] Fix some typos and language nits in docs and comments Štěpán Němec
2024-03-15 14:30 9% ` [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules Štěpán Němec
2024-03-16 21:27 9% ` Eric Wong
2024-03-16 22:37 14% ` Štěpán Němec
2024-03-18 8:29 9% ` Eric Wong
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.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).