From: Eric Wong <e@yhbt.net>
To: meta@public-inbox.org
Subject: [PATCH 1/4] doc: add data flow diagram using Graph::Easy
Date: Wed, 5 Feb 2020 22:03:46 -0600 [thread overview]
Message-ID: <20200206040349.11587-2-e@yhbt.net> (raw)
In-Reply-To: <20200206040349.11587-1-e@yhbt.net>
Maybe this can make it easier for new and potential
users to understand what's going on.
---
Documentation/flow.ge | 27 +++++++++++++++++++++++++++
Documentation/flow.txt | 32 ++++++++++++++++++++++++++++++++
Documentation/include.mk | 18 +++++++++++++++++-
Makefile.PL | 1 +
4 files changed, 77 insertions(+), 1 deletion(-)
create mode 100644 Documentation/flow.ge
create mode 100644 Documentation/flow.txt
diff --git a/Documentation/flow.ge b/Documentation/flow.ge
new file mode 100644
index 00000000..27f2bfcb
--- /dev/null
+++ b/Documentation/flow.ge
@@ -0,0 +1,27 @@
+# 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.
+
+graph { flow: down }
+
+[delivery tools:\n
+ public-inbox-mda\n
+ public-inbox-watch\n
+ public-inbox-learn] -> [inboxdir]
+
+[git mirroring tools:\n
+ grok-pull,\n
+ various scripts
+] -- git (clone|fetch) &&\n
+ public-inbox-index --> [inboxdir]
+
+[inboxdir] ->
+[read-only daemons:\n
+ public-inbox-httpd\n
+ public-inbox-nntpd]
+
+# Copyright 2020 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
new file mode 100644
index 00000000..ac3459e4
--- /dev/null
+++ b/Documentation/flow.txt
@@ -0,0 +1,32 @@
+# 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.
+
+ +--------------------+
+ | delivery tools: |
+ | public-inbox-mda |
+ | public-inbox-watch |
+ | public-inbox-learn |
+ +--------------------+
+ |
+ |
+ v
++----------------------+ +--------------------+
+| git mirroring tools: | git (clone|fetch) && | |
+| grok-pull, | public-inbox-index | inboxdir |
+| various scripts | ----------------------> | |
++----------------------+ +--------------------+
+ |
+ |
+ v
+ +--------------------+
+ | read-only daemons: |
+ | public-inbox-httpd |
+ | public-inbox-nntpd |
+ +--------------------+
+
+# Copyright 2020 all contributors <meta@public-inbox.org>
+# License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
diff --git a/Documentation/include.mk b/Documentation/include.mk
index 3d88fcec..41de0a72 100644
--- a/Documentation/include.mk
+++ b/Documentation/include.mk
@@ -10,6 +10,9 @@ MAN = man
# this is "xml" on FreeBSD and maybe some other distros:
XMLSTARLET = xmlstarlet
+# libgraph-easy-perl from Debian, Graph::Easy from CPAN
+GRAPH_EASY = graph-easy
+
# same as pod2text
COLUMNS = 76
@@ -62,6 +65,17 @@ Documentation/standards.txt : Documentation/standards.perl
touch -r Documentation/standards.perl $@+
mv $@+ $@
+# 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; \
+ echo; \
+ sed -ne '/^# Copyright/,$$p' <Documentation/flow.ge \
+ ) >$@+
+ touch -r Documentation/flow.ge $@+
+ mv $@+ $@
+
NEWS NEWS.atom NEWS.html : $(news_deps)
$(PERL) -I lib -w Documentation/mknews.perl $@ $(RELEASES)
@@ -99,7 +113,9 @@ rsync-doc: NEWS.atom.gz
clean-doc:
$(RM_F) $(man1) $(man5) $(man7) $(man8) $(gz_docs) $(docs_html) \
$(mantxt) $(rsync_xdocs) \
- NEWS NEWS.atom NEWS.html Documentation/standards.txt
+ NEWS NEWS.atom NEWS.html Documentation/standards.txt \
+ Documentation/flow.html Documentation/flow.html.gz \
+ Documentation/flow.txt.gz
clean :: clean-doc
diff --git a/Makefile.PL b/Makefile.PL
index d626aef4..59874170 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -13,6 +13,7 @@ $v->{news_deps} = [ map { "Documentation/RelNotes/$_.eml" } @RELEASES ];
$v->{txt} = [ qw(INSTALL README COPYING TODO HACKING) ];
my @dtxt = grep(m!\ADocumentation/[^/]+\.txt\z!, @manifest);
push @dtxt, 'Documentation/standards.txt';
+push @dtxt, 'Documentation/flow.txt';
push @dtxt, @{$v->{txt}};
for my $txt (@dtxt) {
my $html = $txt;
next prev parent reply other threads:[~2020-02-06 4:03 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-06 4:03 [PATCH 0/4] doc: data flow graph and doc linkification Eric Wong
2020-02-06 4:03 ` Eric Wong [this message]
2020-02-06 4:03 ` [PATCH 2/4] doc: remove .x/ subdirectory for Xapian manpages Eric Wong
2020-02-06 4:03 ` [PATCH 3/4] doc: txt2pre: auto-linkify manpage references Eric Wong
2020-02-06 4:03 ` [PATCH 4/4] doc: v1: add a reference to git-filter-repo(1), too Eric Wong
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://public-inbox.org/README
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200206040349.11587-2-e@yhbt.net \
--to=e@yhbt.net \
--cc=meta@public-inbox.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/public-inbox.git
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).