about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/design_notes.txt24
-rw-r--r--Documentation/design_www.txt6
-rw-r--r--Documentation/include.mk65
-rwxr-xr-xDocumentation/txt2pre26
4 files changed, 109 insertions, 12 deletions
diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt
index 286f35c0..d7313cb6 100644
--- a/Documentation/design_notes.txt
+++ b/Documentation/design_notes.txt
@@ -1,5 +1,5 @@
-Design notes
-------------
+public-inbox design notes
+-------------------------
 
 Challenges to running normal mailing lists
 ------------------------------------------
@@ -14,7 +14,6 @@ confused users who cannot unsubscribe.
 
 Use existing infrastructure
 ---------------------------
-
 * public-inbox can coexist with existing mailing lists, any subscriber
   to the existing mailing list can begin delivering messages to
   public-inbox-mda(1)
@@ -35,7 +34,6 @@ Use existing infrastructure
 
 Why email?
 ----------
-
 * Freedom from proprietary services, tools and APIs.  Communicating with
   developers and users of Free Software should not rely on proprietary
   tools or services.
@@ -53,9 +51,9 @@ Why email?
   There is no need to ask the NSA for backups of your mail archives :)
 
 * git, one of the most widely-used version control systems, includes many
-  tools for for email: git-format-patch(1), git-send-email(1), git-am(1).
-  Furthermore, the development of git itself is based on the git mailing
-  list.
+  tools for for email, including: git-format-patch(1), git-send-email(1),
+  git-am(1), git-imap-send(1).  Furthermore, the development of git itself
+  is based on the git mailing list.
 
 * Email is already the de-facto form of communication in many Free Software
   communities..
@@ -66,7 +64,6 @@ Why email?
 
 Why git?
 --------
-
 * git is distributed and robust while being both fast and
   space-efficient with text data.  NNTP was considered, but does not
   support delta-compression and places no guarantees on data/transport
@@ -78,7 +75,6 @@ Why git?
 
 Why perl 5?
 -----------
-
 * Perl 5 is widely available on modern *nix systems with good a history
   of backwards and forward compatibility.
 
@@ -87,7 +83,6 @@ Why perl 5?
 
 Laziness
 --------
-
 * Stick to dependencies available in Debian main, this should make it
   easier for potential users to install, and easier for distro
   maintainers to pick up.
@@ -115,7 +110,6 @@ Laziness
 
 Web notes
 ---------
-
 * Getting users to install/run ssoma (or any new tool) is difficult.
   The web views must be easily read/cache/mirror-able.
 
@@ -128,9 +122,15 @@ Web notes
 * Raw text endpoint allows users to write client-side JS endpoints
   without hosting the data themselves (or on a different server).
 
+What sucks about public-inbox
+-----------------------------
+* Lack of push notification.  On the other hand, feeds seem popular.
+
+* some (mostly GUI) mail clients cannot set In-Reply-To headers
+  properly without the original message.
+
 Scalability notes
 -----------------
-
 Even with shallow clone, storing the history of large/busy mailing lists
 may place much burden on subscribers and servers.  However, having a
 single (or few) refs representing the entire history of a list is good
diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt
index 0f63fdf2..1cd0d96e 100644
--- a/Documentation/design_www.txt
+++ b/Documentation/design_www.txt
@@ -1,15 +1,21 @@
 URL naming
 ----------
 
+### Unstable endpoints
 /$LISTNAME/?r=$GIT_COMMIT                       -> HTML only
 /$LISTNAME/index.atom.xml                       -> Atom feed
 /$LISTNAME/all.atom.xml                         -> Atom feed, includes replies
+
+### Stable endpoints
 /$LISTNAME/m/$MESSAGE_ID.html                   -> HTML content (short quotes)
 /$LISTNAME/m/$MESSAGE_ID.txt                    -> raw original
 /$LISTNAME/m/$MESSAGE_ID                        -> 301 to .html version
 /$LISTNAME/f/$MESSAGE_ID.html                   -> HTML content (full quotes)
 /$LISTNAME/f/$MESSAGE_ID                        -> 301 to .html version
 /$LISTNAME/f/$MESSAGE_ID.txt                    -> 301 to m/$MESSAGE_ID.txt
+
+TODO (these might be expensive)
+-------------------------------
 /$LISTNAME/t/$MESSAGE_ID.html                   -> HTML content of thread
 /$LISTNAME/t/$MESSAGE_ID.mbox                   -> mbox content of thread
 
diff --git a/Documentation/include.mk b/Documentation/include.mk
new file mode 100644
index 00000000..776413e6
--- /dev/null
+++ b/Documentation/include.mk
@@ -0,0 +1,65 @@
+# Copyright (C) 2013, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+all::
+
+RSYNC = rsync
+RSYNC_DEST = public-inbox.org:/srv/public-inbox/
+docs := README COPYING INSTALL $(shell git ls-files 'Documentation/*.txt')
+INSTALL = install
+PANDOC = pandoc
+PANDOC_OPTS = -f markdown --email-obfuscation=none
+pandoc = $(PANDOC) $(PANDOC_OPTS)
+
+m1 =
+m1 += public-inbox-mda
+m5 =
+m7 =
+
+man1 := $(addsuffix .1, $(m1))
+man5 := $(addsuffix .5, $(m5))
+man7 := $(addsuffix .7, $(m7))
+
+all:: man html
+
+man: $(man1) $(man5) $(man7)
+
+prefix ?= $(HOME)
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man5dir = $(mandir)/man5
+man7dir = $(mandir)/man7
+
+install-man: man
+        test -z "$(man1)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+        test -z "$(man5)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+        test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
+        test -z "$(man1)" || $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+        test -z "$(man5)" || $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
+        test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
+%.1 %.5 %.7 : Documentation/%.txt
+        $(pandoc) -s -t man < $< > $@+ && mv $@+ $@
+
+txt2pre = ./Documentation/txt2pre < $< > $@+ && touch -r $< $@+ && mv $@+ $@
+txt = INSTALL README COPYING
+
+INSTALL.html: INSTALL
+        $(txt2pre)
+index.html: README
+        $(txt2pre)
+
+docs_html := index.html INSTALL.html
+html: $(docs_html)
+gz_docs := $(addsuffix .gz, $(docs) $(docs_html))
+rsync_docs := $(gz_docs) $(docs) $(txt) $(docs_html)
+%.gz: %
+        gzip -9 --rsyncable < $< > $@+
+        touch -r $< $@+
+        mv $@+ $@
+
+gz-doc: $(gz_docs)
+rsync-doc:
+        git set-file-times $(docs) $(txt)
+        $(MAKE) gz-doc
+        $(RSYNC) --chmod=Fugo=r -av $(rsync_docs) $(RSYNC_DEST)
+clean-doc:
+        $(RM) $(man1) $(man5) $(man7) $(gz_docs) $(docs_html)
diff --git a/Documentation/txt2pre b/Documentation/txt2pre
new file mode 100755
index 00000000..f84f9c06
--- /dev/null
+++ b/Documentation/txt2pre
@@ -0,0 +1,26 @@
+#!/usr/bin/env perl
+# Copyright (C) 2014, Eric Wong <normalperson@yhbt.net> and all contributors
+# License: AGPLv3 or later (https://www.gnu.org/licenses/agpl-3.0.txt)
+#
+# Stupid script to make HTML from preformatted, utf-8 text versions,
+# only generating links for http(s).  Markdown does too much
+# and requires indentation to output preformatted text.
+use strict;
+use warnings;
+use CGI qw/escapeHTML/;
+use Encode qw/encode/;
+my $str = eval { local $/; <> };
+$str = escapeHTML($str);
+$str = encode('us-ascii', $str, Encode::HTMLCREF);
+my ($title) = ($str =~ /\A([^\n]+)/);
+
+# temporarily swap &gt; for escape so our s!! to add href works.
+# there's probably a way to do this with only a single s!! ...
+$str =~ s!&gt;!\e!g;
+$str =~ s!\b(https?://[\w+\+\&\?\.\%\;/-]+)!<a\nhref="$1"\n>$1</a>!g;
+$str =~ s!\e!&gt;!g; # swap escapes back to &gt;
+
+print '<html><head>',
+  '<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />',
+  "<title>$title</title>",
+  "</head><body>\n<pre>",  $str , '</pre></body></html>';