README: convert to reStructuredText and rewrite

For the benefit of Codeberg, and to state that this is a (minimally
maintained) fork intended to be used as a standalone utility only.

diff --git a/README b/README
deleted file mode 100644 (file)
index 1327bf1..0000000
--- a/README
+++ /dev/null
@@ -1,90 +0,0 @@
-##### Overview
-
-The  postfix-logwatch(1) utility is a Postfix MTA log parser, that pro-
-duces summaries, details, and statistics  regarding  the  operation  of
-Postfix.
-
-This utility can be used as a standalone program, or as a Logwatch fil-
-ter module to produce Postfix summary and detailed reports from  within
-Logwatch.
-
-A key feature of postfix-logwatch is its ability to produce a very wide
-range of reports with data grouped and sorted as much  as  possible  to
-reduce  noise  and highlight patterns.  Brief summary reports provide a
-quick overview of general  Postfix  operations  and  message  delivery,
-calling out warnings that may require attention.  Detailed reports pro-
-vide easy to scan, hierarchically-arranged and  organized  information,
-with as much or little detail as desired.
-
-##### Installation: standalone
-
-The included Makefile will install the postfix-logwatch utility
-for you.  Run:
-
-    make install-standalone
-
-to install the utility and its configuration file.  Installation
-will default to /usr/local/bin and /usr/local/etc, respectively.
- 
-##### Installation: logwatch
-
-To use postfix-logwatch as a logwatch script, the files:
- 
-    postfix-logwatch
-    postfix-logwatch.conf
- 
-will need to be installed into one of logwatch's known directories.
-To avoid overwriting your existing default logwatch filter files,
-the enclosed files can be installed into the global logwatch
-installation directory, which is typically:
-
-   /etc/logwatch
-
-The included Makefile can be used to install the files into
-/etc/logwatch for you. To install the filter into an existing
-logwatch installation, run:
-
-    make install-logwatch
-
-NOTE: the files postfix-logwatch and postfix-logwatch.conf must be
-renamed (by removing the "-logwatch" suffix), for logwatch to
-function correctly.  The Makefile takes care of this.  The
-Makefile also disables perl's taint mode (-T) when running under
-logwatch.  If you install the files manually, be sure to remove
-the -T from the first line of the postfix filter.
-
-For non-standard installations, you will need to determine your
-global logwatch directory, and define "prefix" in the attached
-Makefile.
-
-Alternatively, you can manually copy the files to their proper
-locations:
-
-    cp postfix-logwatch       /etc/logwatch/scripts/services/postfix
-    cp postfix-logwatch.conf  /etc/logwatch/conf/services/postfix.conf
-    [ remove -T from line 1 of /etc/logwatch/scripts/services/postfix ]
-
-    Optional:
-    cp postfix-logwatch.1     /usr/local/man/man1/postfix-logwatch.1
-
-##### Usage
-
-The postfix-logwatch utility is used standalone as:
-
-   postfix-logwatch /path/to/maillog
-
-For brief help:
-
-   postfix-logwatch --help
-
-To use within logwatch:
-
-   logwatch --service postfix ...
-
-See the postfix-logwatch(1) man page for complete details, and
-see comments in the postfix-logwatch.conf file for additional
-information.
-
-Mike Cappella
-mike (at) cappella (dot) us
-last updated: 01/11/2012

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..0bc0a0c
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,53 @@
+This is a minimally maintained fork of the original postfix-logwatch
+from the `logreporters project <https://logreporters.sourceforge.net/>`_.
+It should work with the latest postfix, but large-scale
+improvements and refactorings are out of scope.
+
+Overview
+========
+
+The postfix-logwatch utility is a postfix log parser that produces
+summaries, details, and statistics regarding the operation of
+postfix.
+
+A key feature of postfix-logwatch is its ability to produce a very
+wide range of reports with data grouped and sorted as much as possible
+to reduce noise and highlight patterns. Brief summary reports provide
+a quick overview of general postfix operations and message scanning,
+calling out warnings that may require attention. Detailed reports
+provide easy to scan, hierarchically-arranged and organized
+information, with as much or little detail as desired.
+
+Installation
+============
+
+Copy ``postfix-logwatch`` to the location of your choosing, mark it
+executable, and run it. The path to the config file is hard-coded
+in the script, to ``/usr/local/etc/postfix-logwatch.conf``. If you
+want to customize the reports, edit the included example config
+and place it there (or point the script to a better location).
+
+Usage
+=====
+
+Basic usage:
+
+.. code-block:: console
+
+   $ postfix-logwatch /path/to/mail.log
+
+For brief help:
+
+.. code-block:: console
+
+   $ postfix-logwatch --help
+
+See the ``postfix-logwatch.1`` man page for complete details, and see
+comments in the ``postfix-logwatch.conf`` file for additional
+information.
+
+Bugs
+====
+
+Send bugs to michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/postfix-logwatch/issues>`_.