doc: flow: update with newer tools, note forkability

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.

diff --git a/Documentation/flow.ge b/Documentation/flow.ge
index 4308989af7ed11f279b666cc0ae7ae0eb7c84c3c..5ad92fec054621ed715786373566a266e469c9da 100644 (file)
--- 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 1116a917a12d9267f93cb481926907b534d6cdda..ed2dd80b36abfaed5467161c2b536520da2f6212 100644 (file)
--- 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 bfbc495f0470cff4e88131f596e494f7335d21c6..4395e4f4a8de44ec6432f43d77a3c9983f970b97 100644 (file)
--- 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