From: Chris Nehren <apeiron@cpan.org>
Date: Tue, 6 Sep 2011 03:20:53 +0000 (-0400)
Subject: README -> README.pod, add some content
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FPromulger.git;a=commitdiff_plain;h=b26dbe5c1afc18c1c3e51566d025092903b1d4e7

README -> README.pod, add some content
---

diff --git a/README b/README
deleted file mode 100644
index 1988b9d..0000000
--- a/README
+++ /dev/null
@@ -1 +0,0 @@
-The promulger (pmg) MLM
diff --git a/README.pod b/README.pod
new file mode 100644
index 0000000..e5a101f
--- /dev/null
+++ b/README.pod
@@ -0,0 +1,82 @@
+=pod
+
+=head1 NAME
+
+Promulger -- Simple, Unixy mailing list manager
+
+=head1 SYNOPSIS
+
+  # In a config file somewhere:
+  aliases = /path/to/etc/aliases
+  list_home = /path/your/mta/can/write/to/lists
+
+  # then
+  /path/to/pmg/bin/pmg -c /path/to/config/pmg.conf newlist mylist
+
+  # then
+  mail -s subscribe mylist-request@yourhost < /dev/null
+  mail -s post mylist@yourhost < first_post
+
+  # cleanup
+  /path/to/pmg/bin/pmg -c /path/to/config/pmg.conf rmlist mylist
+
+=head1 DESCRIPTION
+
+Promulger is a simple, lightweight mailinglist manager (mlm) that subscribes to
+the Unix philosophy and aims to be sysadmin-friendly. Plaintext configuration
+and data files are favored over opaque binary files. The simplest possible thing
+that can work is the preferred approach. Simple algorithms, simple tools that do
+one thing well. An administrator should be able to read the config files and the
+data files without reading these docs and understand what's going on.
+
+Promulger strives to be easy to install while not reinventing the wheel. To this
+end it uses modern tools on the CPAN where it makes sense, but nonetheless tries
+to be minimal. It doesn't need the enterprise-grade flexibility of L<Catalyst>,
+but at the same time writing raw CGI was bad ten years ago and still is.
+
+Another design goal (one further in the future) is standards-compliance. There
+are a number of documents and RFCs related to email and mailing lists. Promulger
+seeks to adhere to these where it makes sense to do so, with the belief that 
+consistent software is easier to use and manage. As Promulger supports relevant
+standards, the documentation will be updated to describe which standards are
+respected and any deviations (along with the rationale therefor).
+
+=head1 LIMITATIONS
+
+Consider this section a TODO list.
+
+Presently, Promulger doesn't support VERP, and as a result doesn't support
+bounce parsing. It's being released to be tested on small, closed networks with
+clueful admins. If fishing messages out of your MTA's queue isn't something you
+feel comfortable doing, Promulger isn't for you right now.
+
+Another thing Promulger lacks is an archive. This is coming, but in the
+meantime, you're on your own. 
+
+There's no support for the standard mailing list headers. This means that
+filtering will need to work on the mailing list sender address for now. 
+
+It's not very customizable--in fact, it has no flexibility at all.
+
+=head1 ENVIRONMENT
+
+Promulger doesn't read any environment variables.
+
+=head1 AUTHOR
+
+Chris Nehren
+
+=head1 CONTRIBUTORS
+
+No one, yet. Patches welcome!
+
+=head1 COPYRIGHT
+
+Copyright (c) 2010, 2011 Chris Nehren and the CONTRIBUTORS above.
+
+=head1 LICENSE
+
+This library is free software and may be distributed under the same terms
+as perl itself.
+
+=cut