[PATCH 1/3] doc: fix some typos and grammar

[PATCH 1/3] doc: fix some typos and grammar

[Štěpán Němec]

---
 Documentation/RelNotes/v1.9.0.eml        | 2 +-
 Documentation/RelNotes/v2.0.0.wip        | 6 +++---
 Documentation/lei-config.pod             | 8 ++++----
 Documentation/lei-daemon-kill.pod        | 2 +-
 Documentation/lei-inspect.pod            | 4 ++--
 Documentation/lei-lcat.pod               | 2 +-
 Documentation/lei-ls-mail-source.pod     | 2 +-
 Documentation/lei-ls-search.pod          | 2 +-
 Documentation/lei-mail-sync-overview.pod | 2 +-
 Documentation/lei-q.pod                  | 4 ++--
 Documentation/lei-security.pod           | 8 ++++----
 Documentation/lei-store-format.pod       | 2 +-
 Documentation/lei-up.pod                 | 4 ++--
 TODO                                     | 2 +-
 install/README                           | 2 +-
 lib/PublicInbox/XapHelperCxx.pm          | 2 +-
 16 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/Documentation/RelNotes/v1.9.0.eml b/Documentation/RelNotes/v1.9.0.eml
index 2d83cbfec66b..08e16a669a11 100644
--- a/Documentation/RelNotes/v1.9.0.eml
+++ b/Documentation/RelNotes/v1.9.0.eml
@@ -46,7 +46,7 @@
   * patchid: prefix search support added to WWW and lei for
     "git patch-id --stable" support
 
-  * text inside base-85 binary patches are no longer indexed
+  * text inside base-85 binary patches is no longer indexed
     to avoid false positives
 
   * for lei users, "lei reindex" now exists and is required
diff --git a/Documentation/RelNotes/v2.0.0.wip b/Documentation/RelNotes/v2.0.0.wip
index 40c87169ccd9..859d858bd1e1 100644
--- a/Documentation/RelNotes/v2.0.0.wip
+++ b/Documentation/RelNotes/v2.0.0.wip
@@ -57,11 +57,11 @@
 
   * compatibility with SQLite <3.8.3 on CentOS 7.x
 
-  * fix `lei q -tt' on locally-indexed messages (still broken for remotes:
+  * fix `lei q -tt' on locally indexed messages (still broken for remotes:
     https://public-inbox.org/meta/20230226170931.M947721@dcvr/ )
 
   * `lei import' now sets labels+keywords consistently on all
-     already-imported messages
+     already imported messages
 
 solver (used by lei (rediff|blob), and PublicInbox::WWW)
 
@@ -101,7 +101,7 @@
 
 Search improvements (lei and PublicInbox::WWW)
 
-  * quoted text inside base-85 binary patches are no longer indexed
+  * quoted text inside base-85 binary patches is no longer indexed
 
 Thanks to all the bug reporters and users who made this release
 possible.
diff --git a/Documentation/lei-config.pod b/Documentation/lei-config.pod
index 23a60c8a6b7c..699f45cbf690 100644
--- a/Documentation/lei-config.pod
+++ b/Documentation/lei-config.pod
@@ -64,8 +64,8 @@ L<https://rt.cpan.org/Ticket/Display.html?id=129967>
 
 Enable debugging output of underlying IMAP and NNTP libraries,
 currently L<Mail::IMAPClient> and L<Net::NNTP>, respectively.
-If using L<imap.proxy> or L<nntp.proxy> point to a SOCKS proxy,
-debugging output for L<IO::Socket::Socks> will be enabled, as
+If L<imap.proxy> or L<nntp.proxy> points to a SOCKS proxy,
+debugging output for L<IO::Socket::Socks> will be enabled as
 well.
 
 Disabling L<imap.compress> may be required for readability.
@@ -104,7 +104,7 @@ C<frag>, C<func>, and C<context>.
 =head1 OPTIONS
 
 Most L<git-config(1)> command-line switches are accepted by C<lei config>
-as-is.  The most-frequently-used options are expected to be:
+as is.  The most frequently used options are expected to be:
 
 =over 4
 
@@ -112,7 +112,7 @@ as-is.  The most-frequently-used options are expected to be:
 
 =item --edit
 
-Opens an editor to edit the lei config file
+Open an editor to edit the lei config file.
 
 =item -l
 
diff --git a/Documentation/lei-daemon-kill.pod b/Documentation/lei-daemon-kill.pod
index 48c237b8d3a6..97a81e23f973 100644
--- a/Documentation/lei-daemon-kill.pod
+++ b/Documentation/lei-daemon-kill.pod
@@ -31,7 +31,7 @@ remain running after a short while after this takes effect.
 =back
 
 =for comment
-SIGQUIT and SIGINT currently do what SIGTERM do, may change...
+SIGQUIT and SIGINT currently do what SIGTERM does, may change...
 
 =head1 CONTACT
 
diff --git a/Documentation/lei-inspect.pod b/Documentation/lei-inspect.pod
index 19dd8ab5edef..82b9651adeb5 100644
--- a/Documentation/lei-inspect.pod
+++ b/Documentation/lei-inspect.pod
@@ -26,7 +26,7 @@ An inboxdir, extindex topdir, or Xapian shard
 
 =item --pretty
 
-Pretty print output.  If stdout is opened to a tty, C<--pretty> is
+Pretty-print output.  If stdout is opened to a tty, C<--pretty> is
 enabled by default.
 
 =item -
@@ -47,7 +47,7 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 
diff --git a/Documentation/lei-lcat.pod b/Documentation/lei-lcat.pod
index e80738626b51..530b755ebfb2 100644
--- a/Documentation/lei-lcat.pod
+++ b/Documentation/lei-lcat.pod
@@ -31,7 +31,7 @@ C<-f text> when writing to stdout.
 
 Most commonly C<text> (the default) or C<reply> to
 display the message(s) in a format suitable for trimming
-and sending as a email reply.
+and sending as an email reply.
 
 =item --stdin
 
diff --git a/Documentation/lei-ls-mail-source.pod b/Documentation/lei-ls-mail-source.pod
index 59d14afe6880..0e4859236e56 100644
--- a/Documentation/lei-ls-mail-source.pod
+++ b/Documentation/lei-ls-mail-source.pod
@@ -28,7 +28,7 @@ Format output as JSON and include more information.
 
 =item --pretty
 
-Pretty print JSON output.  If stdout is opened to a tty, C<--pretty>
+Pretty-print JSON output.  If stdout is opened to a tty, C<--pretty>
 is enabled by default.
 
 =item --ascii
diff --git a/Documentation/lei-ls-search.pod b/Documentation/lei-ls-search.pod
index 0fe4b7595134..367f4ad6d3d3 100644
--- a/Documentation/lei-ls-search.pod
+++ b/Documentation/lei-ls-search.pod
@@ -26,7 +26,7 @@ C<jsonl>, or C<concatjson>.
 
 =item --pretty
 
-Pretty print C<json> or C<concatjson> output.  If stdout is opened to
+Pretty-print C<json> or C<concatjson> output.  If stdout is opened to
 a tty and used as the C<--output> destination, C<--pretty> is enabled
 by default.
 
diff --git a/Documentation/lei-mail-sync-overview.pod b/Documentation/lei-mail-sync-overview.pod
index e30674bbdff4..7ae7e8872350 100644
--- a/Documentation/lei-mail-sync-overview.pod
+++ b/Documentation/lei-mail-sync-overview.pod
@@ -20,7 +20,7 @@ Future work will be done to improve it and add IMAP IDLE support.
   # dump "inbox" labeled files from the past week to a Maildir
   lei q L:inbox rt:last.week.. -o /tmp/results
 
-  # open /tmp/results in your favorite mail agent.  If inotify or kevent
+  # Open /tmp/results in your favorite mail agent.  If inotify or kevent
   # works, keyword changes (e.g. marking messages as `seen') are
   # synchronized automatically.
 
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index c0254ba0bb1a..5f5338490b07 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -80,7 +80,7 @@ Disable color (for C<-f reply> and C<-f text>).
 
 =item --pretty
 
-Pretty print C<json> or C<concatjson> output.  If stdout is opened to
+Pretty-print C<json> or C<concatjson> output.  If stdout is opened to
 a tty and used as the C<--output> destination, C<--pretty> is enabled
 by default.
 
@@ -218,7 +218,7 @@ Default: fcntl,dotlock
 
 =item -n NUMBER
 
-Fuzzy limit the number of matches per-local external and lei/store.
+Fuzzy-limit the number of matches per local external and lei/store.
 Messages added by the L<--threads> switch do not count towards this
 limit, and there is no limit on remote externals.
 
diff --git a/Documentation/lei-security.pod b/Documentation/lei-security.pod
index 104bfb48a26c..e54cae90f0c0 100644
--- a/Documentation/lei-security.pod
+++ b/Documentation/lei-security.pod
@@ -4,7 +4,7 @@ lei - security information
 
 =head1 SYNOPSIS
 
-L<lei(1)> is intended for use with both publicly-archived
+L<lei(1)> is intended for use with both publicly archived
 and "private" mail in personal mailboxes.  This document is
 intended to give an overview of security implications and
 lower^Wmanage user expectations.
@@ -66,7 +66,7 @@ other users on the local system.
 
 =head1 CORE DUMPS
 
-In case any process crashes, a core dumps may contain passwords or
+In case any process crashes, a core dump may contain passwords or
 contents of sensitive messages.  Please report these so they can be
 fixed (see L</CONTACT>).
 
@@ -74,7 +74,7 @@ fixed (see L</CONTACT>).
 
 lei currently uses the L<curl(1)> and L<git(1)> executables in
 C<$PATH> for HTTP and HTTPS network access.  Interactive
-authentication for HTTP and HTTPS is not-yet-supported since all
+authentication for HTTP and HTTPS is not yet supported since all
 currently supported HTTP/HTTPS sources are L<PublicInbox::WWW>
 instances.
 
@@ -83,7 +83,7 @@ L<Net::NNTP> (standard library) is used for NNTP and NNTPS.
 
 L<Mail::IMAPClient> and L<Net::NNTP> will use L<IO::Socket::SSL>
 for TLS if available.  In turn, L<IO::Socket::SSL> uses the
-widely-installed OpenSSL library.
+widely installed OpenSSL library.
 
 STARTTLS will be attempted if advertised by the server
 unless IMAPS or NNTPS are used.  C<-c imap.starttls=0>
diff --git a/Documentation/lei-store-format.pod b/Documentation/lei-store-format.pod
index 625c60f436a8..d4bb42d5fa67 100644
--- a/Documentation/lei-store-format.pod
+++ b/Documentation/lei-store-format.pod
@@ -67,7 +67,7 @@ the "same" message.
 
 =head2 mail_sync.sqlite3
 
-This SQLite database maintained for bidirectional mapping of
+This SQLite database is maintained for bidirectional mapping of
 git blobs to IMAP UIDs, Maildir file names, and NNTP article numbers.
 
 It is also used for retrieving messages from Maildirs indexed by
diff --git a/Documentation/lei-up.pod b/Documentation/lei-up.pod
index 3b7c6f46fed6..8c426942640f 100644
--- a/Documentation/lei-up.pod
+++ b/Documentation/lei-up.pod
@@ -32,8 +32,8 @@ delays or downtime.
 The time(s) of the last successful queries are the C<lastresult>
 values visible from L<lei-edit-search(1)>.
 
-Date formats understood by L<git-rev-parse(1)> may be used.
-e.g C<1.hour> or C<3.days>
+Date formats understood by L<git-rev-parse(1)> may be used,
+e.g., C<1.hour> or C<3.days>.
 
 Default: 2.days
 
diff --git a/TODO b/TODO
index de628e2e310a..36a7f0cf441a 100644
--- a/TODO
+++ b/TODO
@@ -26,7 +26,7 @@ all need to be considered for everything we introduce.)
   archive locations to avoid SPOF.
 
 * optional Cache::FastMmap support so production deployments won't
-  need Varnish (Varnish doesn't protect NNTP nor IMAP, either)
+  need Varnish (Varnish doesn't protect NNTP or IMAP, either)
 
 * dogfood and take advantage of new kernel APIs (while maintaining
   portability to older Linux, free BSDs and maybe Hurd).
diff --git a/install/README b/install/README
index 981e014b9959..e1b5558e0b87 100644
--- a/install/README
+++ b/install/README
@@ -5,7 +5,7 @@ TL;DR:	sudo ./install/deps.perl all
 
 Files in this directory are designed for:
 
-* users using from git or tarballs (and not the OS package manager)
+* users using git repo or tarballs (and not the OS package manager)
 
 * lazy users who can't be bothered to read all of INSTALL
 
diff --git a/lib/PublicInbox/XapHelperCxx.pm b/lib/PublicInbox/XapHelperCxx.pm
index 90ddd80fd53d..dbb0a9154a36 100644
--- a/lib/PublicInbox/XapHelperCxx.pm
+++ b/lib/PublicInbox/XapHelperCxx.pm
@@ -36,7 +36,7 @@ sub xap_cfg (@) {
 	seek($err, 0, SEEK_SET) or die "seek: $!";
 	$err = do { local $/; <$err> };
 	die <<EOM;
-@$cmd failed: Xapian devlopment files missing? (\$?=$?)
+@$cmd failed: Xapian development files missing? (\$?=$?)
 $err
 EOM
 }
-- 
2.42.0

[PATCH 2/3] doc: lei-q: drop stale TODO comment (fixed in 1f1b1f0e22f7)

[Štěpán Němec]

Fixes: 1f1b1f0e22f7 ("doc: lei-q: document SEARCH TERMS prefixes")
---
I also wonder about CAVEATS from lei-overview.pod:

  IMAP and NNTP client performance is poor on high-latency connections.
  It will hopefully be fixed in 2022.

I think this needs an update (or removal, if the issue was indeed
fixed).

Thanks.

 Documentation/lei-q.pod | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 5f5338490b07..4862ce78b709 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -12,9 +12,6 @@ lei q [OPTIONS] (--stdin|-)
 
 Search for messages across the lei/store and externals.
 
-=for comment
-TODO: Give common prefixes, or at least a description/reference.
-
 =head1 OPTIONS
 
 =for comment
-- 
2.42.0

[PATCH 3/3] search: rectify comment (rt: documented since 738c4a65719e)

[Štěpán Němec]

Fixes: 738c4a65719e ("www: various help text updates")
---
On a related note, there's this comment in LeiXSearch.pm:312:

  # this should really be rt: (received-time), but no stable
  # public-inbox releases support it, yet.
  my $dt = 'dt:'.strftime('%Y%m%d%H%M%S', gmtime($lr)).'..';

So I went all "hey, it's been 3 releases with rt:, let's do this",
and suddenly, `lei up` stopped getting any updates :-]

The problem is that the date syntax handling for d:, dt: and rt: is not
the same (date_parse_prepare in Search.pm), which doesn't seem ideal to
me, either, but maybe that's intentional/necessary?

On a totally unrelated note, this patch is a nice example of how
--diff-algorithm=histogram (which I use by default) sometimes produces
diffs that are both longer and more confusing than with any other
(git-provided) algorithm:

 our $ENQ_ASCENDING = 1;
 our @MAIL_VMAP = (
        [ YYYYMMDD, 'd:'],
-       [ DT, 'dt:' ],
-       # these are undocumented for WWW, but lei and IMAP use them
-       [ BYTES, 'z:' ],
        [ TS, 'rt:' ],
+       # these are undocumented for WWW, but lei and IMAP use them
+       [ DT, 'dt:' ],
+       [ BYTES, 'z:' ],
        [ UID, 'uid:' ]
 );
 our @MAIL_NRP;

 lib/PublicInbox/Search.pm | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/PublicInbox/Search.pm b/lib/PublicInbox/Search.pm
index d7a6f9d7913c..477f77dcffeb 100644
--- a/lib/PublicInbox/Search.pm
+++ b/lib/PublicInbox/Search.pm
@@ -68,10 +68,10 @@ our $ENQ_DESCENDING = 0;
 our $ENQ_ASCENDING = 1;
 our @MAIL_VMAP = (
 	[ YYYYMMDD, 'd:'],
-	[ DT, 'dt:' ],
+	[ TS, 'rt:' ],
 	# these are undocumented for WWW, but lei and IMAP use them
+	[ DT, 'dt:' ],
 	[ BYTES, 'z:' ],
-	[ TS, 'rt:' ],
 	[ UID, 'uid:' ]
 );
 our @MAIL_NRP;
-- 
2.42.0

Re: [PATCH 1/3] doc: fix some typos and grammar

[Eric Wong]

Štěpán Němec <stepnem@smrk.net> wrote:
>  Documentation/RelNotes/v1.9.0.eml        | 2 +-
>  Documentation/RelNotes/v2.0.0.wip        | 6 +++---
>  Documentation/lei-config.pod             | 8 ++++----
>  Documentation/lei-daemon-kill.pod        | 2 +-
>  Documentation/lei-inspect.pod            | 4 ++--
>  Documentation/lei-lcat.pod               | 2 +-
>  Documentation/lei-ls-mail-source.pod     | 2 +-
>  Documentation/lei-ls-search.pod          | 2 +-
>  Documentation/lei-mail-sync-overview.pod | 2 +-
>  Documentation/lei-q.pod                  | 4 ++--
>  Documentation/lei-security.pod           | 8 ++++----
>  Documentation/lei-store-format.pod       | 2 +-
>  Documentation/lei-up.pod                 | 4 ++--

Thanks, changes to those files look fine (but I'm no English
expert, either).  My brain does jumble words often :x

> diff --git a/TODO b/TODO
> index de628e2e310a..36a7f0cf441a 100644
> --- a/TODO
> +++ b/TODO
> @@ -26,7 +26,7 @@ all need to be considered for everything we introduce.)
>    archive locations to avoid SPOF.
>  
>  * optional Cache::FastMmap support so production deployments won't
> -  need Varnish (Varnish doesn't protect NNTP nor IMAP, either)
> +  need Varnish (Varnish doesn't protect NNTP or IMAP, either)

I'm not sure about this change, I seem to remember `nor' being
more suited for negatives.  Any citations or comments from
others reading this?

>  * dogfood and take advantage of new kernel APIs (while maintaining
>    portability to older Linux, free BSDs and maybe Hurd).
> diff --git a/install/README b/install/README
> index 981e014b9959..e1b5558e0b87 100644
> --- a/install/README
> +++ b/install/README
> @@ -5,7 +5,7 @@ TL;DR:	sudo ./install/deps.perl all
>  
>  Files in this directory are designed for:
>  
> -* users using from git or tarballs (and not the OS package manager)
> +* users using git repo or tarballs (and not the OS package manager)

I wonder if:

  * users using our code from git or tarballs (and not the OS package manager)

...is better.  I always feel the need to clarify git the software
vs. our code repo vs. our mirror on public-inbox.org/git   *shrug*

> --- a/lib/PublicInbox/XapHelperCxx.pm
> +++ b/lib/PublicInbox/XapHelperCxx.pm
> @@ -36,7 +36,7 @@ sub xap_cfg (@) {
>  	seek($err, 0, SEEK_SET) or die "seek: $!";
>  	$err = do { local $/; <$err> };
>  	die <<EOM;
> -@$cmd failed: Xapian devlopment files missing? (\$?=$?)
> +@$cmd failed: Xapian development files missing? (\$?=$?)

Yup, I also just noticed that on a different branch I'm been working on.

Re: [PATCH 2/3] doc: lei-q: drop stale TODO comment (fixed in 1f1b1f0e22f7)

[Eric Wong]

Štěpán Němec <stepnem@smrk.net> wrote:
> I also wonder about CAVEATS from lei-overview.pod:
> 
>   IMAP and NNTP client performance is poor on high-latency connections.
>   It will hopefully be fixed in 2022.
> 
> I think this needs an update (or removal, if the issue was indeed
> fixed).

Unfortunately not :<   It's a PITA to deal with some of that stuff
and I'm still using offlineimap (as I've been for ~20 years, now?)
I'll try to take care of it in 2024 at latest...

Re: [PATCH 3/3] search: rectify comment (rt: documented since 738c4a65719e)

[Eric Wong]

Štěpán Němec <stepnem@smrk.net> wrote:
> Fixes: 738c4a65719e ("www: various help text updates")
> ---
> On a related note, there's this comment in LeiXSearch.pm:312:
> 
>   # this should really be rt: (received-time), but no stable
>   # public-inbox releases support it, yet.
>   my $dt = 'dt:'.strftime('%Y%m%d%H%M%S', gmtime($lr)).'..';
> 
> So I went all "hey, it's been 3 releases with rt:, let's do this",
> and suddenly, `lei up` stopped getting any updates :-]

> The problem is that the date syntax handling for d:, dt: and rt: is not
> the same (date_parse_prepare in Search.pm), which doesn't seem ideal to
> me, either, but maybe that's intentional/necessary?

Yeah, probably: "rt:$lr.."; is correct.

It's historical baggage since rt: wasn't really used until we
got IMAP (2020); and we didn't have user-friendly approxidate
parsing until 2021.

d: and dt: had to be at least usable before 2021, so it's more
usable in "raw" form.

It's expensive to reindex so it's not something I'm inclined to
force users into doing, either...

d: was a short-sighted mistake and redundant.  I suppose we
could stop indexing d: at some point (like we do with --skip-docdata)
and translate all (not just most) d: into dt: in the parser.

> On a totally unrelated note, this patch is a nice example of how
> --diff-algorithm=histogram (which I use by default) sometimes produces
> diffs that are both longer and more confusing than with any other
> (git-provided) algorithm:

Heh, I've never touched --diff-algorithm.  But I sometimes pipe
messages to `lei rediff -W' or `lei rediff -U100' to get more
context.

I hope to add support for rediff to the WWW UI once coderepo
integration is improved.

Re: [PATCH 1/3] doc: fix some typos and grammar

[Štěpán Němec]

On Mon, 16 Oct 2023 21:13:20 +0000
Eric Wong wrote:

>> --- a/TODO
>> +++ b/TODO
>> @@ -26,7 +26,7 @@ all need to be considered for everything we introduce.)
>>    archive locations to avoid SPOF.
>>  
>>  * optional Cache::FastMmap support so production deployments won't
>> -  need Varnish (Varnish doesn't protect NNTP nor IMAP, either)
>> +  need Varnish (Varnish doesn't protect NNTP or IMAP, either)
>
> I'm not sure about this change, I seem to remember `nor' being
> more suited for negatives.

I'm about 100% sure about this :-P

> Any citations or comments from others reading this?

I'm sure you will find many explanations in books / guides /
Internet, here's from one of the first DDG hits:

https://grammarhow.com/or-vs-nor/

  1. When making a negative statement that doesn’t contain
  “either” or “neither”, and the second item is a noun,
  adjective, or adverb phrase, you should use “or” instead of
  “nor” to continue the negation.

    He doesn’t like pizza or pasta. 
    He isn’t coming tonight or tomorrow because he is sick.
    He doesn’t speak English clearly or fluently.

If you wanted a version with "nor", that would be "Varnish
protects neither NNTP nor IMAP", but the meaning is slightly
different.

In short, you either use the n-words or the non-n-words (the
two pairs don't mix), and if the verb itself is negated, you
use either/or.

>>  Files in this directory are designed for:
>>  
>> -* users using from git or tarballs (and not the OS package manager)
>> +* users using git repo or tarballs (and not the OS package manager)
>
> I wonder if:
>
>   * users using our code from git or tarballs (and not the OS package manager)
>
> ...is better.  I always feel the need to clarify git the software
> vs. our code repo vs. our mirror on public-inbox.org/git   *shrug*

Yeah, I agree that's better.  Maybe also change "using" to
"running"?  "Users using" is a bit awkward.

Thank you for the date-related explanations, and the rediff tip!

-- 
Štěpán

[PATCH 4/3] install/README: improve wording

[Eric Wong]

Štěpán Němec <stepnem@smrk.net> wrote:
> https://grammarhow.com/or-vs-nor/

Thanks, that's better than the results that were at the top for me.

> >>  Files in this directory are designed for:
> >>  
> >> -* users using from git or tarballs (and not the OS package manager)
> >> +* users using git repo or tarballs (and not the OS package manager)
> >
> > I wonder if:
> >
> >   * users using our code from git or tarballs (and not the OS package manager)
> >
> > ...is better.  I always feel the need to clarify git the software
> > vs. our code repo vs. our mirror on public-inbox.org/git   *shrug*
> 
> Yeah, I agree that's better.  Maybe also change "using" to
> "running"?  "Users using" is a bit awkward.

Agreed.  How about:

----------8<---------
Subject: [PATCH 4/3] install/README: improve wording

Reported-by: Štěpán Němec <stepnem@smrk.net>
---
 install/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/install/README b/install/README
index 981e014b..dd652552 100644
--- a/install/README
+++ b/install/README
@@ -5,7 +5,7 @@ TL;DR:	sudo ./install/deps.perl all
 
 Files in this directory are designed for:
 
-* users using from git or tarballs (and not the OS package manager)
+* users running our code from git or tarballs (and not the OS package manager)
 
 * lazy users who can't be bothered to read all of INSTALL
 

Re: [PATCH 4/3] install/README: improve wording

[Štěpán Němec]

On Tue, 17 Oct 2023 06:43:18 +0000
Eric Wong wrote:

> -* users using from git or tarballs (and not the OS package manager)
> +* users running our code from git or tarballs (and not the OS package manager)

LGTM, but I'd also wrap the line (the text file line length
norm in the repo seems to lie between 60 and 70; this would
be 78).

Thanks,

  Štěpán

Re: [PATCH 4/3] install/README: improve wording

[Eric Wong]

Štěpán Němec <stepnem@smrk.net> wrote:
> On Tue, 17 Oct 2023 06:43:18 +0000
> Eric Wong wrote:
> 
> > -* users using from git or tarballs (and not the OS package manager)
> > +* users running our code from git or tarballs (and not the OS package manager)
> 
> LGTM, but I'd also wrap the line (the text file line length
> norm in the repo seems to lie between 60 and 70; this would
> be 78).

I think it's fine for a standalone lines such as list items to
be up to 80.  While paragraphs get harder to read with more
columns, standalone lines get distracting when wrapped (IMHO).

Re: [PATCH 4/3] install/README: improve wording

[Štěpán Němec]

On Tue, 17 Oct 2023 07:54:28 +0000
Eric Wong wrote:

>> > -* users using from git or tarballs (and not the OS package manager)
>> > +* users running our code from git or tarballs (and not the OS package manager)
>> 
>> LGTM, but I'd also wrap the line (the text file line length
>> norm in the repo seems to lie between 60 and 70; this would
>> be 78).
>
> I think it's fine for a standalone lines such as list items to
> be up to 80.  While paragraphs get harder to read with more
> columns, standalone lines get distracting when wrapped (IMHO).

I'd still at least make a distinction between "true" lists
such as the package listings in INSTALL (which are also
columnized, so the actual "line" is quite short), and what's
closer to just a sentence with a bullet point, like here.
In the given context I don't find

  * users running our code from git or tarballs (and not the
    OS package manager)

distracting, unlike the overlong line, but it's your call of
course.

-- 
Štěpán