1 files changed, 65 insertions, 0 deletions
diff --git a/src/mailman/pipeline/docs/nntp.txt b/src/mailman/pipeline/docs/nntp.txt
new file mode 100644
index 000000000..3f48be1da
--- /dev/null
+++ b/src/mailman/pipeline/docs/nntp.txt
@@ -0,0 +1,65 @@
+NNTP (i.e. Usenet) Gateway
+==========================
+
+Mailman has an NNTP gateway, whereby messages posted to the mailing list can
+be forwarded onto an NNTP newsgroup.  Typically this means Usenet, but since
+NNTP is to Usenet as IP is to the web, it's more general than that.
+
+    >>> handler = config.handlers['to-usenet']
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> mlist.preferred_language = u'en'
+    >>> switchboard = config.switchboards['news']
+
+Gatewaying from the mailing list to the newsgroup happens through a separate
+'nntp' queue and happen immediately when the message is posted through to the
+list.  Note that gatewaying from the newsgroup to the list happens via a
+cronjob (currently not shown).  
+
+There are several situations which prevent a message from being gatewayed to
+the newsgroup.  The feature could be disabled, as is the default.
+
+    >>> mlist.gateway_to_news = False
+    >>> msg = message_from_string("""\
+    ... Subject: An important message
+    ...
+    ... Something of great import.
+    ... """)
+    >>> handler.process(mlist, msg, {})
+    >>> switchboard.files
+    []
+
+Even if enabled, messages that came from the newsgroup are never gated back to
+the newsgroup.
+
+    >>> mlist.gateway_to_news = True
+    >>> handler.process(mlist, msg, {'fromusenet': True})
+    >>> switchboard.files
+    []
+
+Neither are digests ever gated to the newsgroup.
+
+    >>> handler.process(mlist, msg, {'isdigest': True})
+    >>> switchboard.files
+    []
+
+However, other posted messages get gated to the newsgroup via the nntp queue.
+The list owner can set the linked newsgroup and the nntp host that its
+messages are gated to.
+
+    >>> mlist.linked_newsgroup = u'comp.lang.thing'
+    >>> mlist.nntp_host = u'news.example.com'
+    >>> handler.process(mlist, msg, {})
+    >>> len(switchboard.files)
+    1
+    >>> filebase = switchboard.files[0]
+    >>> msg, msgdata = switchboard.dequeue(filebase)
+    >>> switchboard.finish(filebase)
+    >>> print msg.as_string()
+    Subject: An important message
+    <BLANKLINE>
+    Something of great import.
+    <BLANKLINE>
+    >>> dump_msgdata(msgdata)
+    _parsemsg: False
+    listname : _xtest@example.com
+    version  : 3