user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
* [PATCH 0/3] doc: lei updates around lei-q
@ 2021-04-28  4:51 Eric Wong
  2021-04-28  4:51 ` [PATCH 1/3] doc: lei: use /tmp for search results pathnames Eric Wong
                   ` (2 more replies)
  0 siblings, 3 replies; 6+ messages in thread
From: Eric Wong @ 2021-04-28  4:51 UTC (permalink / raw)
  To: meta

1/3 is probably a game changer and will help anybody supporting
this project sleep easier at night :)

Eric Wong (3):
  doc: lei: use /tmp for search results pathnames
  doc: lei q: split =item aliases onto separate lines
  doc: lei q: split --output and --format, note "text"

 Documentation/lei-overview.pod |  4 +-
 Documentation/lei-q.pod        | 88 +++++++++++++++++++++++-----------
 2 files changed, 63 insertions(+), 29 deletions(-)


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH 1/3] doc: lei: use /tmp for search results pathnames
  2021-04-28  4:51 [PATCH 0/3] doc: lei updates around lei-q Eric Wong
@ 2021-04-28  4:51 ` Eric Wong
  2021-04-28  4:51 ` [PATCH 2/3] doc: lei q: split =item aliases onto separate lines Eric Wong
  2021-04-28  4:51 ` [PATCH 3/3] doc: lei q: split --output and --format, note "text" Eric Wong
  2 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-04-28  4:51 UTC (permalink / raw)
  To: meta

This drives the point home about results being volatile
and discardable.
---
 Documentation/lei-overview.pod | 4 ++--
 Documentation/lei-q.pod        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/lei-overview.pod b/Documentation/lei-overview.pod
index 70dbf2b5..6b5fa721 100644
--- a/Documentation/lei-overview.pod
+++ b/Documentation/lei-overview.pod
@@ -82,7 +82,7 @@ Search for messages whose subject includes "lei" and "skeleton".
 Do the same, but also report unmatched messages that are in the same
 thread as a matched message.
 
-=item $ lei q -t -o mdir --mua=mutt s:lei s:skeleton
+=item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
 
 Write results to a Maildir at "mdir".  Mutt will be invoked
 to open mfolder (C<mutt -f %f>) while results are being fetched
@@ -92,7 +92,7 @@ and written.
 
 Search for all flagged messages that also have a "next" label.
 
-=item $ lei p2q HEAD | lei q --stdin -tt -o mdir
+=item $ lei p2q HEAD | lei q --stdin -tt -o /tmp/mdir
 
 Search for messages that have post-image git blob IDs that match those
 of the current repository's HEAD commit, writing them to the Maildir
diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index a84fc440..b938746a 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -31,9 +31,9 @@ Read search terms from stdin.
 Warning: this clobbers and overwrites the output destination unless
 L</-a, --augment> is specified.
 
-Destination for results (e.g., C<path/to/Maildir>,
+Destination for results (e.g., C</tmp/results-Maildir>,
 C<imaps://user@mail.example.com/INBOX.test>, or
-C<mboxcl2:path/to/mbox>).  The prefix may be a supported protocol:
+C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
 C<imap://> or C<imaps://>.  URLs requiring
 authentication must use L<netrc(5)> and/or L<git-credential(1)> to
 fill in the username and password.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH 2/3] doc: lei q: split =item aliases onto separate lines
  2021-04-28  4:51 [PATCH 0/3] doc: lei updates around lei-q Eric Wong
  2021-04-28  4:51 ` [PATCH 1/3] doc: lei: use /tmp for search results pathnames Eric Wong
@ 2021-04-28  4:51 ` Eric Wong
  2021-04-29  1:39   ` Kyle Meyer
  2021-04-28  4:51 ` [PATCH 3/3] doc: lei q: split --output and --format, note "text" Eric Wong
  2 siblings, 1 reply; 6+ messages in thread
From: Eric Wong @ 2021-04-28  4:51 UTC (permalink / raw)
  To: meta

It makes L</--augment> look nicer without resorting to
L<--augment|/-a, --augment> and similarly verbose nastiness.

Having each option as a separate =item (with a blank line in
between each =item) seems to be the preferred style used within
Perl core documentation (I used perlrun.pod as an example),
so we'll follow Perl core style, here.

This needs to be done for other manpages, at some point...
---
 Documentation/lei-q.pod | 58 +++++++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 14 deletions(-)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index b938746a..2b9936b8 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -26,10 +26,14 @@ TODO: mention curl options?
 
 Read search terms from stdin.
 
-=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
+=item --output=MFOLDER
+
+=item -o MFOLDER
+
+=item --mfolder=MFOLDER
 
 Warning: this clobbers and overwrites the output destination unless
-L</-a, --augment> is specified.
+L</--augment> is specified.
 
 Destination for results (e.g., C</tmp/results-Maildir>,
 C<imaps://user@mail.example.com/INBOX.test>, or
@@ -50,7 +54,9 @@ TODO: Provide description of formats?
 
 Default: C<-> (stdout)
 
-=item -f FORMAT, --format=FORMAT
+=item --format=FORMAT
+
+=item -f FORMAT
 
 Format of results.  This option exists as a convenient way to specify
 the format for the default stdout destination.  Using a C<format:>
@@ -81,7 +87,9 @@ This option may be given multiple times.
 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
 doesn't point to stdout, nothing otherwise.
 
-=item -a, --augment
+=item --augment
+
+=item -a
 
 Augment output destination instead of clobbering it.
 
@@ -90,7 +98,9 @@ Augment output destination instead of clobbering it.
 Do not importing keywords before writing to an existing output
 destination.
 
-=item -t, --threads
+=item --threads
+
+=item -t
 
 Return all messages in the same thread as the actual match(es).
 
@@ -102,7 +112,9 @@ of the same thread.
 TODO: Warning: this flag may become persistent and saved in
 lei/store unless an MUA unflags it!  (Behavior undecided)
 
-=item -d STRATEGY, --dedupe=STRATEGY
+=item --dedupe=STRATEGY
+
+=item -d STRATEGY
 
 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 C<none>.
@@ -126,7 +138,9 @@ Limit operations to those requiring network access.
 
 Don't include results from externals.
 
-=item -I LOCATION, --include=LOCATION
+=item --include=LOCATION
+
+=item -I LOCATION
 
 Include specified external in search.  This option may be given
 multiple times.
@@ -141,7 +155,9 @@ multiple times.
 Use only the specified external for search.  This option may be given
 multiple times, in which case the search uses only the specified set.
 
-=item -g, --globoff
+=item --globoff
+
+=item -g
 
 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 option applies to C<--include>, C<--exclude>, and C<--only>.
@@ -158,7 +174,11 @@ C<none>.
 
 Default: fcntl,dotlock
 
-=item -NUMBER, -n NUMBER, --limit=NUMBER
+=item --limit=NUMBER
+
+=item -NUMBER
+
+=item -n NUMBER
 
 Limit the number of matches.
 
@@ -170,26 +190,36 @@ Shift start of search results.
 
 Default: 0
 
-=item -r, --reverse
+=item --reverse
+
+=item -r
 
 Reverse the results.  Note that this applies before C<--limit>.
 
-=item -s KEY, --sort=KEY
+=item --sort=KEY
+
+=item -s KEY
 
 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 and C<docid>.
 
 Default: C<received>
 
-=item -v, --verbose
+=item --verbose
+
+=item -v
 
 Provide more feedback on stderr.
 
-=item -q, --quiet
+=item --quiet
+
+=item -q
 
 Suppress feedback messages.
 
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
 
 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 

^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH 3/3] doc: lei q: split --output and --format, note "text"
  2021-04-28  4:51 [PATCH 0/3] doc: lei updates around lei-q Eric Wong
  2021-04-28  4:51 ` [PATCH 1/3] doc: lei: use /tmp for search results pathnames Eric Wong
  2021-04-28  4:51 ` [PATCH 2/3] doc: lei q: split =item aliases onto separate lines Eric Wong
@ 2021-04-28  4:51 ` Eric Wong
  2 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-04-28  4:51 UTC (permalink / raw)
  To: meta

I guess --format makes sense for stdout, after all;
and I'm enjoying "-f text" quite a bit, so far.
---
 Documentation/lei-q.pod | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 2b9936b8..bf7a5f70 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -42,15 +42,11 @@ C<imap://> or C<imaps://>.  URLs requiring
 authentication must use L<netrc(5)> and/or L<git-credential(1)> to
 fill in the username and password.
 
-The prefix can instead specify the format of the output: C<maildir>,
-C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>, C<json>, C<jsonl>, or
-C<concatjson>.  When a format isn't specified, it's chosen based on
-the destination.  C<json> is used for the default destination
-(stdout), and C<maildir> is used for an existing directory or
-non-existing path.
+A prefix can specify the format of the output: C<maildir>,
+C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
+mail formats, see L<lei-mail-formats(5)>.
 
-=for comment
-TODO: Provide description of formats?
+C<maildir> is the default for an existing directory or non-existing path.
 
 Default: C<-> (stdout)
 
@@ -58,9 +54,17 @@ Default: C<-> (stdout)
 
 =item -f FORMAT
 
-Format of results.  This option exists as a convenient way to specify
-the format for the default stdout destination.  Using a C<format:>
-prefix with the C<--output> destination is preferred otherwise.
+Format of results to stdout.  This option exists as a convenient
+way to specify the format for the default stdout destination.
+C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
+as are the various mbox variants described in L</--output>.
+
+When a format isn't specified, it's chosen based on the
+L</--output> destination or prefix.  C<json> is used for the
+default destination (stdout).
+
+Using a C<format:> prefix with the C<--output> destination is
+preferred when not writing to stdout.
 
 =item --pretty
 

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH 2/3] doc: lei q: split =item aliases onto separate lines
  2021-04-28  4:51 ` [PATCH 2/3] doc: lei q: split =item aliases onto separate lines Eric Wong
@ 2021-04-29  1:39   ` Kyle Meyer
  2021-04-29  1:57     ` Eric Wong
  0 siblings, 1 reply; 6+ messages in thread
From: Kyle Meyer @ 2021-04-29  1:39 UTC (permalink / raw)
  To: Eric Wong; +Cc: meta

Eric Wong writes:

> It makes L</--augment> look nicer without resorting to
> L<--augment|/-a, --augment> and similarly verbose nastiness.
>
> Having each option as a separate =item (with a blank line in
> between each =item) seems to be the preferred style used within
> Perl core documentation (I used perlrun.pod as an example),
> so we'll follow Perl core style, here.

Okay, thanks providing a rationale for using separate lines.  I went
with the single line style based on some combination of a subjective
visual preference and looking at other manpages (presumably git's).

> This needs to be done for other manpages, at some point...

I should be able to get to another round of lei doc updates this
weekend.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH 2/3] doc: lei q: split =item aliases onto separate lines
  2021-04-29  1:39   ` Kyle Meyer
@ 2021-04-29  1:57     ` Eric Wong
  0 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-04-29  1:57 UTC (permalink / raw)
  To: Kyle Meyer; +Cc: meta

Kyle Meyer <kyle@kyleam.com> wrote:
> Eric Wong writes:
> 
> > It makes L</--augment> look nicer without resorting to
> > L<--augment|/-a, --augment> and similarly verbose nastiness.
> >
> > Having each option as a separate =item (with a blank line in
> > between each =item) seems to be the preferred style used within
> > Perl core documentation (I used perlrun.pod as an example),
> > so we'll follow Perl core style, here.
> 
> Okay, thanks providing a rationale for using separate lines.  I went
> with the single line style based on some combination of a subjective
> visual preference and looking at other manpages (presumably git's).

Yeah, also the existing public-inbox-* manpages were using
commas or slash; probably because I based them on git manpages :x

> > This needs to be done for other manpages, at some point...
> 
> I should be able to get to another round of lei doc updates this
> weekend.

Thanks in advance.  Also, in response to
https://public-inbox.org/meta/20210227180328.28057-1-kyle@kyleam.com/
w.r.t. lei-convert; I think it's helpful to document
since the WWW interface provides gzipped mboxrd and
IMAP|Maildir are probably the most commonly used.

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-04-29  1:57 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-04-28  4:51 [PATCH 0/3] doc: lei updates around lei-q Eric Wong
2021-04-28  4:51 ` [PATCH 1/3] doc: lei: use /tmp for search results pathnames Eric Wong
2021-04-28  4:51 ` [PATCH 2/3] doc: lei q: split =item aliases onto separate lines Eric Wong
2021-04-29  1:39   ` Kyle Meyer
2021-04-29  1:57     ` Eric Wong
2021-04-28  4:51 ` [PATCH 3/3] doc: lei q: split --output and --format, note "text" Eric Wong

user/dev discussion of public-inbox itself

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/meta
	git clone --mirror http://czquwvybam4bgbro.onion/meta
	git clone --mirror http://hjrcffqmbrq6wope.onion/meta
	git clone --mirror http://ou63pmih66umazou.onion/meta

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 meta meta/ https://public-inbox.org/meta \
		meta@public-inbox.org
	public-inbox-index meta

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.mail.public-inbox.meta
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.mail.public-inbox.meta
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.mail.public-inbox.meta
	nntp://news.gmane.io/gmane.mail.public-inbox.general
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/public-inbox.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git