No ext_urls

[public-inbox.git] / Documentation / lei-p2q.pod

diff --git a/Documentation/lei-p2q.pod b/Documentation/lei-p2q.pod
index cc342bd52bdbcef796a199bca939692f20c75d6c..4bc5d25f8ef00b9ba2591604f06f06c1ce77c44f 100644 (file)
--- a/Documentation/lei-p2q.pod
+++ b/Documentation/lei-p2q.pod
@@ -16,14 +16,16 @@ inbox.
 
 The patch can be provided on stdin or as a file.  Alternatively, when
 an argument is given that does not point to an existing file, it is
-taken as a reference to a commit in the current repository, and
+taken as a reference to a commit in the current git repository, and
 L<git-format-patch(1)> is used to generate the patch.
 
 =head1 OPTIONS
 
 =over
 
-=item -w PREFIX[,PREFIX], --want=PREFIX[,PREFIX]
+=item -w PREFIX[,PREFIX]
+
+=item --want=PREFIX[,PREFIX]
 
 Search prefixes to use.  C<dfpost> (post-image git blob ID) and C<dfn>
 (file names from the diff) are the most useful.  Other available
@@ -46,7 +48,8 @@ Default: C<dfpost7>
 
 =item --stdin
 
-Read patch from stdin.
+Read message from stdin.  This is implicit if no arguments are given
+and stdin is a pipe or regular file.
 
 =item --debug
 
@@ -54,26 +57,45 @@ Dump output that shows the information collected for every prefix.
 This information can be useful for seeing how a patch is processed,
 but the format should not be considered stable.
 
-=item -q, --quiet
+=item --uri
+
+URI escape output for interacting with HTTP(S) public-inbox instances.
+
+=item -q
+
+=item --quiet
 
 Suppress feedback messages.
 
 =back
 
+=head1 EXAMPLES
+
+  # to search for all threads which touch a given thread:
+  lei p2q $COMMIT_OID | lei q -t -o /tmp/results
+
+  # to view results on a remote HTTP(S) public-inbox instance
+  $BROWSER https://example.com/pub-inbox/?q=$(lei p2q --uri $COMMIT_OID)
+
+  # to view unapplied patches for a given $FILE from the past year:
+  echo \( rt:last.year.. AND dfn:$FILE \) AND NOT \( \
+       $(git log -p --pretty=mboxrd --since=last.year $FILE |
+               lei p2q -F mboxrd )
+       \) | lei q -o /tmp/unapplied
+
 =head1 CONTACT
 
 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 
-The mail archives are hosted at L<https://public-inbox.org/meta/>
-and L<http://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+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>
 
-
 =head1 SEE ALSO
 
-L<lei-add-external(1)>
+L<lei-q(1)>