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

[Eric Wong <e@80x24.org>]

Š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.