Re: [PATCH (RFC) 2/2] INSTALL: try to be less confusing about optional modules

["Štěpán Němec" <stepnem@smrk.net>]

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