[PATCH 1/2] Fix some typos and language nits in docs and comments

[PATCH 1/2] Fix some typos and language nits in docs and comments

[Štěpán Němec]

---
 Documentation/RelNotes/v2.0.0.wip     | 10 +++++-----
 Documentation/public-inbox-config.pod |  2 +-
 INSTALL                               |  2 +-
 examples/public-inbox-netd@.service   |  2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/RelNotes/v2.0.0.wip b/Documentation/RelNotes/v2.0.0.wip
index 53ef5fe5c7a1..4d872fd721db 100644
--- a/Documentation/RelNotes/v2.0.0.wip
+++ b/Documentation/RelNotes/v2.0.0.wip
@@ -43,8 +43,8 @@
 New users + hackers:
 
   The install/ directory includes tools to automate installation and
-  removal of dependencies for stripped down or full setups.  See
-  install/README for more details
+  removal of dependencies for stripped-down or full setups.  See
+  install/README for more details.
 
 treewide
 
@@ -52,7 +52,7 @@
 
   * standardize on `#' prefix for stderr diagnostics (previously `I:')
 
-  * SHA-256 coderepos are fully-supported (but not inboxes, yet)
+  * SHA-256 coderepos are fully supported (but not inboxes, yet)
 
   * jemalloc (tested as an LD_PRELOAD) is recommended to reduce fragmentation
     in long-running daemon processes serving unpredictable traffic
@@ -174,8 +174,8 @@
 
   * `public-inbox-cindex --join' prefers using Xapian's C++ API
     directly to avoid Perl method dispatch overhead to get usable
-    performance assocating ~300 inboxes with over 1K coderepos
-    (and vice-versa).  Users needing this performance will need
+    performance associating ~300 inboxes with over 1K coderepos
+    (and vice versa).  Users requiring such performance will need
     a C++ compiler, pkg-config, and the Xapian development files
     (see INSTALL).
 
diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
index d3f5d04b0644..b4a1d94dec00 100644
--- a/Documentation/public-inbox-config.pod
+++ b/Documentation/public-inbox-config.pod
@@ -390,7 +390,7 @@ Default: C<404>
 =item publicinbox.nameIsUrl
 
 Treat the name of the public inbox as its unqualified URL when
-using C<publicInbox.wwwListing=all>.  This is, every
+using C<publicInbox.wwwListing=all>.  That is, every
 C<[publicinbox "foo"]> section implicitly sets C<publicinbox.foo.url=foo>.
 
 This is a convenient alternative to specifying
diff --git a/INSTALL b/INSTALL
index b1d7fd1b68e9..c04831c2fb5b 100644
--- a/INSTALL
+++ b/INSTALL
@@ -6,7 +6,7 @@ lei as a command-line tool.  Any HTTP, IMAP, NNTP, or POP3 client can
 access public-inbox servers, as can git-{clone,fetch} on the HTTP(S)
 endpoint.
 
-Since our marketing sucks, ease-of-installation is an important goal
+Since our marketing sucks, ease of installation is an important goal
 for this project and we only depend on distro-provided packages.
 
 As of 2024, public-inbox is packaged by several OS distributions,
diff --git a/examples/public-inbox-netd@.service b/examples/public-inbox-netd@.service
index 2330bd5952fe..83d2e995c0f6 100644
--- a/examples/public-inbox-netd@.service
+++ b/examples/public-inbox-netd@.service
@@ -13,7 +13,7 @@ After = public-inbox-netd.socket
 
 [Service]
 # An LD_PRELOAD for libjemalloc can be added here.  It currently seems
-# more resistant to fragmentation to glibc in long-lived daemons.
+# more resistant to fragmentation in long-lived daemons than glibc.
 Environment = PI_CONFIG=/home/pi/.public-inbox/config \
 PATH=/usr/local/bin:/usr/bin:/bin \
 TZ=UTC \

base-commit: 5e8068b28aa01befa9c6fa7368db956148816189
-- 
2.44.0

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

[Štěpán Němec]

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

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

[Eric Wong]

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

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

[Štěpán Němec]

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

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

[Eric Wong]

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

Re: [PATCH 1/2] Fix some typos and language nits in docs and comments

[Eric Wong]

thanks, pushed