Extend README

1 files changed, 115 insertions, 72 deletions

diff --git a/README.md b/README.md
index 6cbae89..f529ea0 100644
--- a/README.md
+++ b/README.md
@@ -1,121 +1,164 @@
-Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors
----
+# db-iris - Commandline Client for DB IRIS Departure Monitor
 
-<https://finalrewind.org/projects/Travel-Status-DE-IRIS/>
+db-iris is a commandline client and Perl module for the DB IRIS departure
+monitor located at iris.noncd.db.de. See the [Travel::Status::DE::IRIS
+homepage](https://finalrewind.org/projects/Travel-Status-DE-IRIS/) for details.
 
-Travel::Status::DE::IRIS and the accompanying **db-iris** program provide both
-human- and machine-readable access to departure data at german train stations.
-They can be used by Perl scripts or modules, on the command-line, and (via JSON
-output) by other programs.
+It provides both human- and machine-readable access to departure data at german
+train stations via text and JSON output.
 
-Local Installation
----
+## Installation
 
-This will install db-iris and Travel::Status::DE::IRIS to a local directory.
-They will not be made available system-wide; db-iris will not be added to
-your program PATH. See the next section for system-wide installation.
+You have four installation options:
 
-All you need for this variant is **perl** (v5.14.2 or newer), **carton**
-(packaged for many operating systems), and **libxml2** with development headers
-(packaged as `libxml2-dev` on Debian-based Linux distributions).
+* Nightly `.deb` builds for Debian-based distributions
+* Installing the latest release from CPAN
+* Installation from source
+* Using a Docker image
 
-After installing these, run the following command to install the remaining
-dependencies:
+Except for Docker, **db-iris** is available in your PATH after installation.
+You can run `db-iris --version` to verify this. Documentation is available via
+`man db-iris`.
+
+### Nightly Builds for Debian
+
+[lib.finalrewind.org/deb](https://lib.finalrewind.org/deb) provides Debian
+packages of both development and release versions. Note that these are not part
+of the official Debian repository and are not covered by its quality assurance
+process.
+
+To install the latest release, run:
 
 ```
-carton install
+wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_latest_all.deb
+sudo dpkg -i libtravel-statusg-de-iris-perl_latest_all.deb
+sudo apt --fix-broken install
+rm libtravel-status-de-iris-perl_latest_all.deb
 ```
 
-You are now ready to use db-iris by providing Perl with the module paths
-set up by carton and Travel::Status::DE::IRIS:
+For a (possibly broken) development snapshot of the Git master branch, run:
 
 ```
-perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version
+wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_dev_all.deb
+sudo dpkg -i libtravel-status-de-iris-perl_dev_all.deb
+sudo apt --fix-broken install
+rm libtravel-status-de-iris-perl_dev_all.deb
 ```
 
-For documentation, see `perldoc -F lib/Travel/Status/DE/IRIS.pm` and
-`perldoc -F bin/db-iris`.
+Note that dpkg, unlike apt, does not automatically install missing
+dependencies. If a dependency is not satisfied yet, `dpkg -i` will complain
+about unmet dependencies and bail out. `apt --fix-broken install` installs
+these dependencies and also silently finishes the Travel::Status::DE::VRR
+installation.
+
+Uninstallation works as usual:
+
+```
+sudo apt remove libtravel-status-de-iris-perl
+```
 
-System-Wide Installation
----
+### Installation from CPAN
+
+Travel::Status::DE::IRIS releases are published on the Comprehensive Perl
+Archive Network (CPAN) and can be installed using standard Perl module tools
+such as `cpanminus`.
+
+Before proceeding, ensure that you have standard build tools (i.e. make,
+pkg-config and a C compiler) installed. You will also need the following
+libraries with development headers:
+
+* libdb
+* libssl
+* libxml2
+* zlib
+
+Now, use a tool of your choice to install the module. Minimum working example:
+
+```
+cpanm Travel::Status::DE::VRR
+```
 
-This will install db-iris and Travel::Status::DE::IRIS in system-wide
-directories in `/usr/local`, allowing them to be used on the command line and
-by Perl scripts without the need to specify search paths or module directories.
-Building and installation is managed by the **Module::Build** perl module.
+If you run this as root, it will install script and module to `/usr/local` by
+default.
 
-For this variant, you must install Module::Build and all dependencies (see the
-Dependencies section below) yourself. Many of them are packaged for Debian and
-other Linux distributions. Run `perl Build.PL` to check dependency availability
--- if it complains about "ERRORS/WARNINGS FOUND IN PREREQUISITES", install the
-modules it mentions and run `perl Build.PL` again. Repeat this process until it
-no longer complains about missing prerequisites.
+### Installation from Source
 
-You are now ready to build and install the module.
+In this variant, you must ensure availability of dependencies by yourself.
+You may use carton or cpanminus with the provided `Build.PL`, Module::Build's
+installdeps command, or rely on the Perl modules packaged by your distribution.
+On Debian 10+, all dependencies are available from the package repository.
 
-If you downloaded a release tarball, use the following commands:
+To check whether dependencies are satisfied, run:
 
 ```
 perl Build.PL
+```
+
+If it complains about "... is not installed" or "ERRORS/WARNINGS FOUND IN
+PREREQUISITES", it is missing dependencies.
+
+Once all dependencies are satisfied, use Module::Build to build, test and
+install the module. Testing is optional -- you may skip the "Build test"
+step if you like.
+
+If you downloaded a release tarball, proceed as follows:
+
+```
 ./Build
+./Build test
 sudo ./Build install
 ```
 
-If you are working with the git version, use these instead:
+If you are using the Git repository, use the following commands:
 
 ```
-perl Build.PL
 ./Build
 ./Build manifest
+./Build test
 sudo ./Build install
 ```
 
-You can now use Travel::Status::DE::IRIS and db-iris like any other perl
-module. See `man Travel::Status::DE::IRIS` and `man db-iris` for documentation.
+If you do not have superuser rights or do not want to perform a system-wide
+installation, you may leave out `Build install` and use **db-iris** from the
+current working directory instead.
 
-Dependencies
----
+With carton:
 
-* perl version 5.14.2 or newer
-* Class::Accessor
-* DateTime
-* DateTime::Format::Strptime
-* Geo::Distance
-* List::Compare
-* List::MoreUtils
-* List::UtilsBy
-* LWP::UserAgent
-* LWP::Protocol::https
-* Text::LevenshteinXS
-* XML::LibXML
+```
+carton exec db-iris --version
+```
 
-Additional dependencies for building this module:
+Otherwise (also works with carton):
 
-* File::Slurp
-* JSON
+```
+perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version
+```
 
-Note about Text::LevenshteinXS: This module is old and unmaintained, but
-appears to be packaged for slightly more distros than its successor
-Text::Levenshtein::XS. If it is not available for your distro (and you do
-not wish to build it), the following drop-in replacements are available:
+### Running db-iris via Docker
 
-* Text::Levenshtein::XS
-* Text::Levenshtein (about 10 times slower than the XS modules)
+A db-iris image is available on Docker Hub. It is intended for testing
+purposes: due to the latencies involved in spawning a container for each
+db-iris invocation, and the lack of persistent caching, it is less convenient
+for day-to-day usage.
 
-To use them, run:
+Installation:
 
 ```
-sed -i 's/Text::LevenshteinXS/Text::Levenshtein::XS/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm
+docker pull derfnull/db-iris:latest
 ```
 
-or
+Use it by prefixing db-iris commands with `docker run --rm
+derfnull/db-iris:latest`, like so:
 
 ```
-sed -i 's/Text::LevenshteinXS/Text::Levenshtein/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm
+docker run --rm derfnull/db-iris:latest --version
 ```
 
-Managing stations
----
+Documentation is not available in this image. Please refer to the
+[online db-iris manual](https://man.finalrewind.org/1/db-iris/) instead.
+
+
+## Managing stations
 
 Travel::Status::DE::IRIS needs a list of train stations to operate, which is
 located in `share/stations.json`. There are two recommended editing methods.
@@ -152,5 +195,5 @@ curl -s https://iris.noncd.db.de/iris-tts/timetable/station/DS100
 return a `<station>` element with "name", "eva" and "ds100" attributes, you're
 good to go.
 
-Note that although EVA numbers are often identical with UIC station IDs,
-there are stations where this is not the case.
+Note that although EVA numbers are often identical with UIC station IDs, this
+is not always the case. Please do not rely on UIC IDs when managing stations.