README: convert to reStructuredText

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 b9e549d..0000000
--- a/README
+++ /dev/null
@@ -1,90 +0,0 @@
-##### Overview
-
-The amavis-logwatch(1) utility is an Amavisd-new log parser, that pro-
-duces summaries, details, and statistics regarding the operation of
-Amavisd-new.
-
-This utility can be used as a standalone program, or as a Logwatch fil-
-ter module to produce Amavis summary and detailed reports from within
-Logwatch.
-
-A key feature of amavis-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  Amavis  operations  and  message  scanning,
-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 amavis-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 amavis-logwatch as a logwatch script, the files:
- 
-    amavis-logwatch
-    amavis-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 amavis-logwatch and amavis-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 amavis 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 amavis-logwatch       /etc/logwatch/scripts/services/amavis
-    cp amavis-logwatch.conf  /etc/logwatch/conf/services/amavis.conf
-    [ remove -T from line 1 of /etc/logwatch/scripts/services/amavis ]
-
-    Optional:
-    cp amavis-logwatch.1     /usr/local/man/man1/amavis-logwatch.1
-
-##### Usage
-
-The amavis-logwatch utility is used standalone as:
-
-   amavis-logwatch /path/to/amavislog
-
-For brief help:
-
-   amavis-logwatch --help
-
-To use within logwatch:
-
-   logwatch --service amavis ...
-
-See the amavis-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..e91a436
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,54 @@
+This is a minimally maintained fork of the original amavis-logwatch
+from the `logreporters project <https://logreporters.sourceforge.net/>`_.
+It should work with the latest amavisd-new, but large-scale
+improvements and refactorings are out of scope.
+
+Overview
+========
+
+The amavis-logwatch utility is an amavisd-new log parser, that
+produces summaries, details, and statistics regarding the operation of
+amavisd-new. It can be used as a standalone program to produce summary
+and detailed reports from within logwatch.
+
+A key feature of amavis-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 amavis 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 ``amavis-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/amavis-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
+
+   $ amavis-logwatch /path/to/amavislog
+
+For brief help:
+
+.. code-block:: console
+
+   $ amavis-logwatch --help
+
+See the ``amavis-logwatch.1`` man page for complete details, and see
+comments in the ``amavis-logwatch.conf`` file for additional
+information.
+
+Bugs
+====
+
+Send bugs to michael@orlitzky.com, or report them on `Codeberg
+<https://codeberg.org/mjo/amavis-logwatch/issues>`_.