user/dev discussion of public-inbox itself
 help / color / mirror / code / Atom feed
Search results ordered by [date|relevance]  view[summary|nested|Atom feed]
thread overview below | download mbox.gz: |
* [PATCH 1/4] doc: add data flow diagram using Graph::Easy
  2020-02-06  4:03  7% [PATCH 0/4] doc: data flow graph and doc linkification Eric Wong
@ 2020-02-06  4:03  5% ` Eric Wong
  0 siblings, 0 replies; 2+ results
From: Eric Wong @ 2020-02-06  4:03 UTC (permalink / raw)
  To: meta

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;

^ permalink raw reply	[relevance 5%]

* [PATCH 0/4] doc: data flow graph and doc linkification
@ 2020-02-06  4:03  7% Eric Wong
  2020-02-06  4:03  5% ` [PATCH 1/4] doc: add data flow diagram using Graph::Easy Eric Wong
  0 siblings, 1 reply; 2+ results
From: Eric Wong @ 2020-02-06  4:03 UTC (permalink / raw)
  To: meta

A couple of minor doc improvements.  Hopefully the flow graph
will make things easier-to-understand for new users.

And the txt2pre changes are a precursor to configurable
linkification in the WWW interface for email.

Eric Wong (4):
  doc: add data flow diagram using Graph::Easy
  doc: remove .x/ subdirectory for Xapian manpages
  doc: txt2pre: auto-linkify manpage references
  doc: v1: add a reference to git-filter-repo(1), too

 Documentation/.gitignore                 |  2 +-
 Documentation/flow.ge                    | 27 ++++++++
 Documentation/flow.txt                   | 32 +++++++++
 Documentation/include.mk                 | 21 ++++--
 Documentation/public-inbox-compact.pod   |  3 +-
 Documentation/public-inbox-edit.pod      |  2 +-
 Documentation/public-inbox-v1-format.pod |  3 +-
 Documentation/public-inbox-xcpdb.pod     |  4 +-
 Documentation/txt2pre                    | 88 +++++++++++++++++++++++-
 Makefile.PL                              |  7 +-
 10 files changed, 173 insertions(+), 16 deletions(-)
 create mode 100644 Documentation/flow.ge
 create mode 100644 Documentation/flow.txt


^ permalink raw reply	[relevance 7%]

Results 1-2 of 2 | reverse | sort options + mbox downloads above
-- links below jump to the message on this page --
2020-02-06  4:03  7% [PATCH 0/4] doc: data flow graph and doc linkification Eric Wong
2020-02-06  4:03  5% ` [PATCH 1/4] doc: add data flow diagram using Graph::Easy Eric Wong

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).