release 0.6.0
[bdrem.git] / README.rst
index 8db33cd..e503d3b 100644 (file)
@@ -3,8 +3,10 @@ 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::
 
 ========
 Features
@@ -12,15 +14,100 @@ Features
 
 Data sources
 ============
-- Any SQL database
+- Any SQL database.
+
+  - Multiple date fields per record supported.
 - An LDAP server
-- Birthday reminder files (``.bdf``)
+- `Birthday reminder <http://cweiske.de/birthday3.htm>`_ files (``.bdf``)
+- CSV files
 
 Output formats
 ==============
 - ASCII table
 - HTML
 - Email (text + HTML parts)
+- iCalendar
+
+
+=====
+Usage
+=====
+
+Command line
+============
+After configuration_, you can test and use *bdrem* via command line::
+
+    $ bdrem
+    -----------------------------------------------------------
+    Days  Age  Name                  Event      Date        Day
+    -----------------------------------------------------------
+       0   32  Foo Bar               Birthday   20.03.1982  Do 
+       1   33  Andrea Milestone      Birthday   21.03.1981  Fr 
+       7   32  Hugh Success          Birthday   27.03.1982  Do 
+      12       Welt                  Scherztag  01.04.????  Di
+
+Help
+----
+To find out about all supported command line options, use ``--help``::
+
+    Usage:
+      ./bin/bdrem.php [options]
+      ./bin/bdrem.php [options] <command> [options]
+    
+    Options:
+      -n NUM, --next=NUM                Show NUM days after date
+      -p NUM, --prev=NUM                Show NUM days before date
+      -r renderer, --renderer=renderer  Output mode
+      --list-renderer                   lists valid choices for option renderer
+      -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
+      -h, --help                        show this help message and exit
+      -v, --version                     show the program version and exit
+    
+    Commands:
+      readme  Show README.rst file
+      config  Extract configuration file
+
+
+E-Mail
+======
+To send birthday reminder e-mails, use the ``mail`` renderer::
+
+    $ bdrem --renderer=mail
+
+If you only want an email if there is a birthday, use ``--stoponempty``::
+
+    $ bdrem --renderer=mail --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``.
+You will get a colorful HTML table:
+
+.. image:: docs/html.png
+
 
 
 =============
@@ -29,9 +116,130 @@ Configuration
 Copy ``data/bdrem.config.php.dist`` to ``data/bdrem.config.php`` and
 adjust it to your liking.
 
+When running the ``.phar``, extract the configuration file first::
 
-MS SQL server
+    $ php dist/bdrem-0.1.0.phar config > bdrem-0.1.0.phar.config.php
+
+
+Birthday file
 =============
+If you have a ``.bdf`` file from `birthday reminder`__ or `birthday reminder 3`__,
+you can use it with *bdrem*.
+
+Configure your source as follows::
+
+    $source = array('Bdf', '/path/to/birthday.bdf');
+
+__ 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.
+It is known to work fine with ``evolutionPerson`` objects.
+Attributes ``birthDate`` and ``anniversary`` are read.
+
+Configure it as follows::
+
+    $source = array(
+        'Ldap',
+        array(
+            'host'   => 'ldap.example.org',
+            'basedn' => 'ou=adressbuch,dc=example,dc=org',
+            'binddn' => 'cn=FIXME,ou=users,dc=example,dc=org',
+            'bindpw' => 'FIXME'
+        )
+    );
+
+
+SQL database
+============
+Events can be fetched from any SQL database supported by PHP's
+PDO extension - MySQL, SQLite, PostgreSQL and so on.
+
+You may configure every little detail of your database::
+
+    $source = array(
+        'Sql',
+        array(
+            'dsn' => 'mysql:dbname=bdrem;host=127.0.0.1',
+            'user' => 'FIXME',
+            'password' => 'FIXME',
+            'table' => 'contacts',
+            'fields' => array(
+                'date' => array(
+                    //column name => event title
+                    'c_birthday' => 'Birthday'
+                ),
+                //column with name, or array with column names
+                'name' => array('c_name'),
+                //sprintf-compatible name formatting instruction
+                'nameFormat' => '%s',
+            )
+        )
+    );
+
+
+MS SQL server
+-------------
 Configure the date format in ``/etc/freetds/locales.conf``::
 
     [default]
@@ -58,11 +266,15 @@ Dependencies
 - PDO
 - PEAR packages:
 
-  - Console_CommandLine
-  - Mail
-  - Mail_mime
-  - Console_Table
-  - 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.
 
 
 =======
@@ -73,6 +285,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
 ======