release 0.6.1

[bdrem.git] / README.rst

diff --git a/README.rst b/README.rst
index b0cb9c18c6107c191433fa5d0a8570f3b1ed6b03..29e8bda22d14768fc34a741b67aeb56c7269937a 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -3,7 +3,8 @@ bdrem - Birthday reminder by mail
 *********************************
 Birthday reminder that sends out e-mails.
 
-It can also generate ASCII tables on your console/shell and normal HTML pages.
+It can also generate ASCII tables on your console, iCalendar files
+and normal HTML pages.
 
 .. contents::
 
@@ -16,14 +17,16 @@ Data sources
 - Any SQL database.
 
   - Multiple date fields per record supported.
-- An LDAP server
-- `Birthday reminder <http://cweiske.de/birthday3.htm>` files (``.bdf``)
+- An LDAP server with ``evolutionPerson`` records
+- `Birthday reminder <http://cweiske.de/birthday3.htm>`_ files (``.bdf``)
+- CSV files
 
 Output formats
 ==============
 - ASCII table
 - HTML
 - Email (text + HTML parts)
+- iCalendar
 
 
 =====
@@ -59,6 +62,8 @@ To find out about all supported command line options, use ``--help``::
       -e, --stoponempty                 Output nothing when list is empty
       -d date, --date=date              Date to show events for
       -c FILE, --config=FILE            Path to configuration file
+      --debug                           Development helper (mail)
+      --no-color                        Do not output ANSI color codes
       -h, --help                        show this help message and exit
       -v, --version                     show the program version and exit
     
@@ -80,6 +85,24 @@ If you only want an email if there is a birthday, use ``--stoponempty``::
 Make sure your config file contains ``$mail_from`` and ``$mail_to`` settings.
 
 
+iCalendar
+=========
+Exporting birthday events into an ``.ics`` file is easy::
+
+   $ bdrem --renderer=ical > birthdays.ics
+
+It is possible to access the calendar via HTTP, too::
+
+    http://example.org/bdrem/?renderer=ical
+
+You can subscribe to it in your calendar or email application.
+Integration has been tested with Thunderbird's Lightning__ and Claws Mail's
+vCalendar__ plugin.
+
+__ https://addons.mozilla.org/en-US/thunderbird/addon/lightning/
+__ http://www.claws-mail.org/plugin.php?plugin=vcalendar
+
+
 HTML page
 =========
 Simply point your web browser to the ``.phar`` file, or ``index.php``.
@@ -113,6 +136,63 @@ __ http://cweiske.de/birthday.htm
 __ http://cweiske.de/birthday3.htm 
 
 
+CSV file
+========
+Comma separated value files can be used with bdrem.
+They should at least contain a column with the name, and one with the date.
+
+Simple configuration if you use the default settings::
+
+    $source = array(
+        'Csv',
+        '/path/to/file.csv'
+    );
+
+Complex configuration::
+
+    $source = array(
+        'Csv',
+        array(
+            'filename' => '/path/to/file.csv',
+            'columns' => array(
+                'name'  => 0,
+                'event' => 1,
+                'date'  => 2
+            ),
+            'firstLineIsHeader' => true,
+            'defaultEvent' => 'Birthday',
+            'separator' => ',',
+        )
+    );
+
+Configuration options
+---------------------
+``columns``
+  Determines the position of the name, event and date columns.
+  ``0`` is the first column.
+  You can use ``false`` to disable a column; helpful if there is no
+  ``event`` column.
+
+  Default:
+
+  ``array('name' => 0, 'event' => 1, 'date' => 2)``
+  
+``defaultEvent``
+  Text to use as event if there is no event column.
+
+  Defaults to ``Birthday``
+
+``firstLineIsHeader``
+  If the first line in the CSV is column header data
+
+  Defaults to ``true``
+
+``separator``
+  How columns are separated.
+
+  Defaults to ``,``
+
+
 LDAP server
 ===========
 *bdrem* can read birthdays and other events from persons in an LDAP server.
@@ -188,11 +268,15 @@ Dependencies
 - PDO
 - PEAR packages:
 
-  - Console_CommandLine
-  - Console_Table
-  - Mail
-  - Mail_mime
-  - Net_LDAP2
+  - `Console_Color2 <https://pear.php.net/package/Console_Color2>`_
+  - `Console_CommandLine <https://pear.php.net/package/Console_CommandLine>`_
+  - `Console_Table <https://pear.php.net/package/Console_Table>`_
+  - `Mail_mime <https://pear.php.net/package/Mail_mime>`_
+  - `Net_LDAP2 <https://pear.php.net/package/Net_LDAP2>`_
+
+
+Note that the ``.phar`` file already includes all dependencies;
+you do not need to install anything.
 
 
 =======
@@ -203,6 +287,18 @@ License
 __ http://www.gnu.org/licenses/agpl.html
 
 
+========
+Homepage
+========
+Web site
+   http://cweiske.de/bdrem.htm
+
+Source code
+   http://git.cweiske.de/bdrem.git
+
+   Mirror: https://github.com/cweiske/bdrem
+
+
 ======
 Author
 ======