user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
* [PATCH 0/4] doc: some clarifications and warnings
@ 2021-03-29  8:04 Eric Wong
  2021-03-29  8:04 ` [PATCH 1/4] doc: lei q: drop NNTP from --output description Eric Wong
                   ` (4 more replies)
  0 siblings, 5 replies; 6+ messages in thread
From: Eric Wong @ 2021-03-29  8:04 UTC (permalink / raw)
  To: meta

Eric Wong (4):
  doc: lei q: drop NNTP from --output description
  doc: lei q: add warning for --output clobbering
  doc: lei q: clarify default output as stdout
  doc: lei: update description, add warnings

 Documentation/lei-q.pod |  7 +++++--
 Documentation/lei.pod   | 12 +++++++-----
 2 files changed, 12 insertions(+), 7 deletions(-)

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

* [PATCH 1/4] doc: lei q: drop NNTP from --output description
  2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
@ 2021-03-29  8:04 ` Eric Wong
  2021-03-29  8:04 ` [PATCH 2/4] doc: lei q: add warning for --output clobbering Eric Wong
                   ` (3 subsequent siblings)
  4 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-03-29  8:04 UTC (permalink / raw)
  To: meta

We only support NNTP as inputs for convert, import, and
mark|tag.  I'm not sure if supporting NNTP output is worth
it, nor do we have a good way to test it.
---
 Documentation/lei-q.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 787c51bf..8668533a 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -31,7 +31,7 @@ Read search terms from stdin.
 Destination for results (e.g., C<path/to/Maildir>,
 C<imaps://user@mail.example.com/INBOX.test>, or
 C<mboxcl2:path/to/mbox>).  The prefix may be a supported protocol:
-C<imap://>, C<imaps://>, C<nntp://>, or C<nntps://>.  URLs requiring
+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/4] doc: lei q: add warning for --output clobbering
  2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
  2021-03-29  8:04 ` [PATCH 1/4] doc: lei q: drop NNTP from --output description Eric Wong
@ 2021-03-29  8:04 ` Eric Wong
  2021-03-29  8:04 ` [PATCH 3/4] doc: lei q: clarify default output as stdout Eric Wong
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-03-29  8:04 UTC (permalink / raw)
  To: meta

The behavior matching mairix still frightens me a bit when it
comes to supporting new users.  On the other hand, I've rarely
ever used --augment with mairix, so I still think the current
(dangerous) behavior makes sense in the context of search results.
---
 Documentation/lei-q.pod | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 8668533a..8d5053cd 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -28,6 +28,9 @@ Read search terms from stdin.
 
 =item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
 
+Warning: this clobbers and overwrites the output destination unless
+L</-a, --augment> is specified.
+
 Destination for results (e.g., C<path/to/Maildir>,
 C<imaps://user@mail.example.com/INBOX.test>, or
 C<mboxcl2:path/to/mbox>).  The prefix may be a supported protocol:

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

* [PATCH 3/4] doc: lei q: clarify default output as stdout
  2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
  2021-03-29  8:04 ` [PATCH 1/4] doc: lei q: drop NNTP from --output description Eric Wong
  2021-03-29  8:04 ` [PATCH 2/4] doc: lei q: add warning for --output clobbering Eric Wong
@ 2021-03-29  8:04 ` Eric Wong
  2021-03-29  8:04 ` [PATCH 4/4] doc: lei: update description, add warnings Eric Wong
  2021-03-29 21:13 ` [PATCH 0/4] doc: some clarifications and warnings Kyle Meyer
  4 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-03-29  8:04 UTC (permalink / raw)
  To: meta

Seeing a plain "-" may be confusing, especially when we also
support it for --stdin.  Use the C<> POD directive to denote it
as code, too.
---
 Documentation/lei-q.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/lei-q.pod b/Documentation/lei-q.pod
index 8d5053cd..a84fc440 100644
--- a/Documentation/lei-q.pod
+++ b/Documentation/lei-q.pod
@@ -48,7 +48,7 @@ non-existing path.
 =for comment
 TODO: Provide description of formats?
 
-Default: -
+Default: C<-> (stdout)
 
 =item -f FORMAT, --format=FORMAT
 

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

* [PATCH 4/4] doc: lei: update description, add warnings
  2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
                   ` (2 preceding siblings ...)
  2021-03-29  8:04 ` [PATCH 3/4] doc: lei q: clarify default output as stdout Eric Wong
@ 2021-03-29  8:04 ` Eric Wong
  2021-03-29 21:13 ` [PATCH 0/4] doc: some clarifications and warnings Kyle Meyer
  4 siblings, 0 replies; 6+ messages in thread
From: Eric Wong @ 2021-03-29  8:04 UTC (permalink / raw)
  To: meta

Describing the design details and architecture doesn't seem
appropriate for a section 1 manpage.

We'll also add a warning about it being in the early stages.
---
 Documentation/lei.pod | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/lei.pod b/Documentation/lei.pod
index 6c8cfc3d..248e5931 100644
--- a/Documentation/lei.pod
+++ b/Documentation/lei.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-lei - local email interface for public-inbox
+lei - local email interface
 
 =head1 SYNOPSIS
 
@@ -8,15 +8,17 @@ lei [OPTIONS] COMMAND
 
 =head1 DESCRIPTION
 
-Unlike the C10K-oriented L<public-inbox-daemon(8)>, lei is designed
-exclusively to handle trusted local clients with read/write access to
-the file system, using as many system resources as the local user has
-access to.  lei supports a local, writable store built on top of
+lei is a command-line tool for importing and searching email,
+regardless of whether it is from a personal mailbox or a public-inbox.
+lei supports a local, writable store built on top of
 L<public-inbox-v2-format(5)> and L<public-inbox-extindex(1)>.
 L<lei-q(1)> provides an interface for querying messages across the lei
 store and read-only local and remote "externals" (inboxes and external
 indices).
 
+Warning: lei is still in its early stages and may destroy mail.
+Be sure to have backups of destinations lei writes to.
+
 Available in public-inbox 1.7.0+.
 
 =head1 OPTIONS

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

* Re: [PATCH 0/4] doc: some clarifications and warnings
  2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
                   ` (3 preceding siblings ...)
  2021-03-29  8:04 ` [PATCH 4/4] doc: lei: update description, add warnings Eric Wong
@ 2021-03-29 21:13 ` Kyle Meyer
  4 siblings, 0 replies; 6+ messages in thread
From: Kyle Meyer @ 2021-03-29 21:13 UTC (permalink / raw)
  To: Eric Wong; +Cc: meta

Eric Wong writes:

>   doc: lei q: drop NNTP from --output description

Oops :/

>   doc: lei q: add warning for --output clobbering
>   doc: lei q: clarify default output as stdout
>   doc: lei: update description, add warnings

Thanks for the fixes/improvements.

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

end of thread, other threads:[~2021-03-29 21:13 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-29  8:04 [PATCH 0/4] doc: some clarifications and warnings Eric Wong
2021-03-29  8:04 ` [PATCH 1/4] doc: lei q: drop NNTP from --output description Eric Wong
2021-03-29  8:04 ` [PATCH 2/4] doc: lei q: add warning for --output clobbering Eric Wong
2021-03-29  8:04 ` [PATCH 3/4] doc: lei q: clarify default output as stdout Eric Wong
2021-03-29  8:04 ` [PATCH 4/4] doc: lei: update description, add warnings Eric Wong
2021-03-29 21:13 ` [PATCH 0/4] doc: some clarifications and warnings Kyle Meyer

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://ou63pmih66umazou.onion/inbox.comp.mail.public-inbox.meta
	nntp://czquwvybam4bgbro.onion/inbox.comp.mail.public-inbox.meta
	nntp://hjrcffqmbrq6wope.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