unofficial mirror of meta@public-inbox.org
 help / color / mirror / Atom feed
* [PATCH 0/4] various doc updates
@ 2023-02-15  8:01 Eric Wong
  2023-02-15  8:01 ` [PATCH 1/4] doc: WWW + cgi: favor -netd over -httpd Eric Wong
                   ` (3 more replies)
  0 siblings, 4 replies; 5+ messages in thread
From: Eric Wong @ 2023-02-15  8:01 UTC (permalink / raw)
  To: meta

Weird things happen when I start looking at old features as
a guide for implementing new ones.

Eric Wong (4):
  doc: WWW + cgi: favor -netd over -httpd
  doc: flow: update with newer tools, note forkability
  doc: extindex update on configuration and union section
  Makefile.PL: drop update-copyrights rule

 Documentation/flow.ge                   | 13 +++++++++----
 Documentation/flow.txt                  | 18 ++++++++++++------
 Documentation/include.mk                | 15 +++++++++------
 Documentation/public-inbox-extindex.pod | 10 +++++++---
 Documentation/public-inbox.cgi.pod      | 14 ++++++++------
 Makefile.PL                             |  6 ------
 lib/PublicInbox/WWW.pod                 | 16 +++++++++-------
 7 files changed, 54 insertions(+), 38 deletions(-)

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

* [PATCH 1/4] doc: WWW + cgi: favor -netd over -httpd
  2023-02-15  8:01 [PATCH 0/4] various doc updates Eric Wong
@ 2023-02-15  8:01 ` Eric Wong
  2023-02-15  8:01 ` [PATCH 2/4] doc: flow: update with newer tools, note forkability Eric Wong
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2023-02-15  8:01 UTC (permalink / raw)
  To: meta

-netd is strictly more powerful and a gateway drug for
imapd/nntpd/pop3d instances :>
---
 Documentation/public-inbox.cgi.pod | 14 ++++++++------
 lib/PublicInbox/WWW.pod            | 16 +++++++++-------
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/Documentation/public-inbox.cgi.pod b/Documentation/public-inbox.cgi.pod
index 71f8a6f5..0f93fa5a 100644
--- a/Documentation/public-inbox.cgi.pod
+++ b/Documentation/public-inbox.cgi.pod
@@ -4,7 +4,7 @@ public-inbox.cgi - CGI wrapper for PublicInbox::WWW
 
 =head1 SYNOPSIS
 
-You generally want to run public-inbox-httpd, instead
+You generally want to run public-inbox-netd or public-inbox-httpd, instead
 
 =head1 DESCRIPTION
 
@@ -12,9 +12,10 @@ public-inbox.cgi provides a CGI interface wrapper on top of the
 PSGI/Plack L<PublicInbox::WWW> module.  It is only provided for
 compatibility reasons and NOT recommended.
 
-CGI with Perl is slow due to code loading overhead and web servers lack
-the scheduling fairness of L<public-inbox-httpd(1)> for handling git
-clones and streaming large mbox downloads.
+CGI with Perl is slow due to code loading overhead and
+web servers lack the scheduling fairness of L<public-inbox-netd(1)>
+and L<public-inbox-httpd(1)> for handling git clones and
+streaming large mbox downloads.
 
 =head1 CONTACT
 
@@ -25,10 +26,11 @@ L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 
 =head1 COPYRIGHT
 
-Copyright 2019-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<public-inbox-httpd(1)>, L<PublicInbox::WWW>, L<public-inbox-daemon(8)>,
+L<public-inbox-netd(1)>, L<public-inbox-httpd(1)>,
+L<PublicInbox::WWW>, L<public-inbox-daemon(8)>,
diff --git a/lib/PublicInbox/WWW.pod b/lib/PublicInbox/WWW.pod
index 9f6ba466..b55f010e 100644
--- a/lib/PublicInbox/WWW.pod
+++ b/lib/PublicInbox/WWW.pod
@@ -20,13 +20,14 @@ The PSGI web interface for public-inbox.
 
 Using this directly is not needed unless you wish to customize
 your public-inbox PSGI deployment or are using a PSGI server
-other than L<public-inbox-httpd(1)>.
+other than L<public-inbox-netd(1)> (C<-netd>) /
+L<public-inbox-httpd(1)> (C<-httpd>)
 
-While this PSGI application works with all PSGI/Plack web
+While this PSGI application should work with all PSGI/Plack web
 servers such as L<starman(1)>, L<starlet(1)> or L<twiggy(1)>;
-PublicInbox::WWW takes advantage of currently-undocumented APIs
-of L<public-inbox-httpd(1)> to improve fairness when serving
-large responses for thread views and git clones.
+PublicInbox::WWW takes advantage of internal APIs of C<-netd>
+and C<-httpd> to improve fairness when serving large responses
+for thread views, mbox downloads, and git clones.
 
 =head1 ENVIRONMENT
 
@@ -47,10 +48,11 @@ and L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta
 
 =head1 COPYRIGHT
 
-Copyright (C) 2016-2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright (C) all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 
 =head1 SEE ALSO
 
-L<http://plackperl.org/>, L<Plack>, L<public-inbox-httpd(1)>
+L<http://plackperl.org/>, L<Plack>, L<public-inbox-netd(1)>,
+L<public-inbox-httpd(1)>

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

* [PATCH 2/4] doc: flow: update with newer tools, note forkability
  2023-02-15  8:01 [PATCH 0/4] various doc updates Eric Wong
  2023-02-15  8:01 ` [PATCH 1/4] doc: WWW + cgi: favor -netd over -httpd Eric Wong
@ 2023-02-15  8:01 ` Eric Wong
  2023-02-15  8:01 ` [PATCH 3/4] doc: extindex update on configuration and union section Eric Wong
  2023-02-15  8:01 ` [PATCH 4/4] Makefile.PL: drop update-copyrights rule Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2023-02-15  8:01 UTC (permalink / raw)
  To: meta

public-inbox-{clone,fetch,netd} are all relatively new
developments which we can document, here.

We'll also update the generator Makefile snippet since there may
be more Graph::Easy-based docs coming.
---
 Documentation/flow.ge    | 13 +++++++++----
 Documentation/flow.txt   | 18 ++++++++++++------
 Documentation/include.mk | 15 +++++++++------
 3 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/Documentation/flow.ge b/Documentation/flow.ge
index 4308989a..5ad92fec 100644
--- a/Documentation/flow.ge
+++ b/Documentation/flow.ge
@@ -1,9 +1,11 @@
 # public-inbox data flow
 #
 # Note: choose either "delivery tools" OR "git mirroring tools"
-# for a given inboxdir.  Combining them for the SAME inboxdir
-# will cause conflicts.  Of course, different inboxdirs may
-# choose different means of getting mail into them.
+# for a given inboxdir.  Using them simultaneously for the
+# SAME inboxdir will cause conflicts.  Of course, different
+# inboxdirs may choose different means of getting mail into them.
+# You may fork any inbox by starting with "git mirroring tools",
+# and switching to "delivery tools".
 
 graph { flow: down }
 
@@ -13,6 +15,8 @@ graph { flow: down }
  public-inbox-learn] -> [inboxdir]
 
 [git mirroring tools:\n
+ public-inbox-clone,\n
+ public-inbox-fetch,\n
  grok-pull,\n
  various scripts
 ] -- git (clone|fetch) &&\n
@@ -20,9 +24,10 @@ graph { flow: down }
 
 [inboxdir] ->
 [read-only daemons:\n
+ public-inbox-netd\n
  public-inbox-httpd\n
  public-inbox-imapd\n
  public-inbox-nntpd]
 
-# Copyright 2020-2021 all contributors <meta@public-inbox.org>
+# Copyright all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
diff --git a/Documentation/flow.txt b/Documentation/flow.txt
index 1116a917..ed2dd80b 100644
--- a/Documentation/flow.txt
+++ b/Documentation/flow.txt
@@ -1,9 +1,11 @@
 # public-inbox data flow
 #
 # Note: choose either "delivery tools" OR "git mirroring tools"
-# for a given inboxdir.  Combining them for the SAME inboxdir
-# will cause conflicts.  Of course, different inboxdirs may
-# choose different means of getting mail into them.
+# for a given inboxdir.  Using them simultaneously for the
+# SAME inboxdir will cause conflicts.  Of course, different
+# inboxdirs may choose different means of getting mail into them.
+# You may fork any inbox by starting with "git mirroring tools",
+# and switching to "delivery tools".
 
                                                  +--------------------+
                                                  |  delivery tools:   |
@@ -15,8 +17,10 @@
                                                    |
                                                    v
 +----------------------+                         +--------------------+
-| git mirroring tools: |  git (clone|fetch) &&   |                    |
-|      grok-pull,      |  public-inbox-index     |      inboxdir      |
+| git mirroring tools: |                         |                    |
+| public-inbox-clone,  |                         |                    |
+| public-inbox-fetch,  |  git (clone|fetch) &&   |      inboxdir      |
+|      grok-pull,      |  public-inbox-index     |                    |
 |   various scripts    | ----------------------> |                    |
 +----------------------+                         +--------------------+
                                                    |
@@ -24,10 +28,12 @@
                                                    v
                                                  +--------------------+
                                                  | read-only daemons: |
+                                                 | public-inbox-netd  |
                                                  | public-inbox-httpd |
                                                  | public-inbox-imapd |
                                                  | public-inbox-nntpd |
                                                  +--------------------+
 
-# Copyright 2020-2021 all contributors <meta@public-inbox.org>
+# Copyright all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
+# This file was generated from flow.txt using Graph::Easy
diff --git a/Documentation/include.mk b/Documentation/include.mk
index bfbc495f..4395e4f4 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2013-2021 all contributors <meta@public-inbox.org>
+# Copyright (C) all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 all::
 
@@ -67,13 +67,16 @@ Documentation/standards.txt : Documentation/standards.perl
 
 # flow.txt is checked into git since Graph::Easy isn't in many distros
 Documentation/flow.txt : Documentation/flow.ge
-	(sed -ne '1,/^$$/p' <Documentation/flow.ge; \
-		$(GRAPH_EASY) Documentation/flow.ge || \
-			cat Documentation/flow.txt; \
+
+%.txt : %.ge
+	(sed -ne '1,/^$$/p' <$<; \
+		$(GRAPH_EASY) $< || grep -v '^#' $@; \
 		echo; \
-		sed -ne '/^# Copyright/,$$p' <Documentation/flow.ge \
+		sed -ne '/^# Copyright/,$$p' <$< \
 		) >$@+
-	touch -r Documentation/flow.ge $@+
+	echo >>$@+ \
+	  '# This file was generated from $(@F) using Graph::Easy'
+	touch -r $< $@+
 	mv $@+ $@
 
 Documentation/lei-q.pod : lib/PublicInbox/Search.pm Documentation/common.perl

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

* [PATCH 3/4] doc: extindex update on configuration and union section
  2023-02-15  8:01 [PATCH 0/4] various doc updates Eric Wong
  2023-02-15  8:01 ` [PATCH 1/4] doc: WWW + cgi: favor -netd over -httpd Eric Wong
  2023-02-15  8:01 ` [PATCH 2/4] doc: flow: update with newer tools, note forkability Eric Wong
@ 2023-02-15  8:01 ` Eric Wong
  2023-02-15  8:01 ` [PATCH 4/4] Makefile.PL: drop update-copyrights rule Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2023-02-15  8:01 UTC (permalink / raw)
  To: meta

The coderepo indexer will use similar ideas, I think...
---
 Documentation/public-inbox-extindex.pod | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/public-inbox-extindex.pod b/Documentation/public-inbox-extindex.pod
index f71a90e5..8370b905 100644
--- a/Documentation/public-inbox-extindex.pod
+++ b/Documentation/public-inbox-extindex.pod
@@ -77,9 +77,9 @@ L<public-inbox-extindex-format(5)>
 
 =head1 CONFIGURATION
 
-public-inbox-extindex does not currently write to the
-L<public-inbox-config(5)> file, configuration may be entered
-manually.  The extindex name of C<all> is a special case which
+public-inbox-extindex does not write to the L<public-inbox-config(5)>
+file, it must be entered manually.
+The extindex name of C<all> is a special case which
 corresponds to indexing C<--all> inboxes.  An example for
 C<--all> is as follows:
 
@@ -89,6 +89,10 @@ C<--all> is as follows:
 		coderepo = foo
 		coderepo = bar
 
+Putting an C<extindex> entry in the config allows L<PublicInbox::WWW>.
+You can have any number of C<extentry.$NAME> sections where C<$NAME>
+is something other than C<all> to display a union of several inboxes.
+
 See L<public-inbox-config(5)> for more details.
 
 =head1 ENVIRONMENT

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

* [PATCH 4/4] Makefile.PL: drop update-copyrights rule
  2023-02-15  8:01 [PATCH 0/4] various doc updates Eric Wong
                   ` (2 preceding siblings ...)
  2023-02-15  8:01 ` [PATCH 3/4] doc: extindex update on configuration and union section Eric Wong
@ 2023-02-15  8:01 ` Eric Wong
  3 siblings, 0 replies; 5+ messages in thread
From: Eric Wong @ 2023-02-15  8:01 UTC (permalink / raw)
  To: meta

I'm no longer updating them since it's noisy and acceptable
to not have them:

  https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/

I'm tired of being reminded what year it is :<
---
 Makefile.PL | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Makefile.PL b/Makefile.PL
index 9233ac9d..8de1351f 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -261,11 +261,5 @@ symlink-install : lib/PublicInbox.pm
 pure_all :: lib/PublicInbox.pm
 lib/PublicInbox.pm : FORCE
 	VERSION=\$(VERSION) \$(PERL) -w ./version-gen.perl
-
-update-copyrights :
-	\@case '\$(GNULIB_PATH)' in '') echo >&2 GNULIB_PATH unset; false;; esac
-	git ls-files | UPDATE_COPYRIGHT_HOLDER='all contributors' \\
-		UPDATE_COPYRIGHT_USE_INTERVALS=2 \\
-		xargs \$(GNULIB_PATH)/build-aux/update-copyright
 EOF
 }

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

end of thread, other threads:[~2023-02-15  8:01 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-15  8:01 [PATCH 0/4] various doc updates Eric Wong
2023-02-15  8:01 ` [PATCH 1/4] doc: WWW + cgi: favor -netd over -httpd Eric Wong
2023-02-15  8:01 ` [PATCH 2/4] doc: flow: update with newer tools, note forkability Eric Wong
2023-02-15  8:01 ` [PATCH 3/4] doc: extindex update on configuration and union section Eric Wong
2023-02-15  8:01 ` [PATCH 4/4] Makefile.PL: drop update-copyrights rule Eric Wong

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).