From 67727c4d12052e8b7f1e07cc3806eb7e9140d2bf Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Fri, 8 May 2020 19:13:46 +0200 Subject: Extend README --- README | 45 ------------------ README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 45 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 18280d2..0000000 --- a/README +++ /dev/null @@ -1,45 +0,0 @@ -Travel::Status::DE::DeutscheBahn - -Interface to the DeutscheBahn online departure monitor ------------------------------------------------------- - -* - - -Dependencies ------------- - - * perl version 5.10.1 or newer - * Class::Accessor - * DateTime - * DateTime::Format::Strptime - * JSON - * List::MoreUtils - * LWP::UserAgent (usually shipped by libwww-perl) - * LWP::Protocol::https - * XML::LibXML - -Installation ------------- - -From a release tarball: - -$ perl Build.PL -$ perl Build -$ sudo perl Build install - -From git: - -$ perl Build.PL -$ perl Build -$ perl Build manifest -$ sudo perl Build install - -You can then run 'man Travel::Status::DE::HAFAS' for more information. -This distribution also ships the example script 'hafas-m', see 'man hafas-m'. - -Testing -------- - -$ perl Build test - -This requires the Test::More, Test::Compile and Test::Pod modules. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b49d67b --- /dev/null +++ b/README.md @@ -0,0 +1,156 @@ +# hafas-m - Commandline Public Transit Departure Monitor + +hafas-m is a commandline client and Perl module for HAFAS public transit +departure interfaces such as +[bahn.de/ris](https://reiseauskunft.bahn.de//bin/bhftafel.exe/dn). See the +[Travel::Status::DE::DeutscheBahn +homepage](https://finalrewind.org/projects/Travel-Status-DE-DeutscheBahn) for +details. + +## Installation + +You have four installation options: + +* Nightly `.deb` builds for Debian-based distributions +* Installing the latest release from CPAN +* Installation from source +* Using a Docker image + +Except for Docker, __hafas-m__ is available in your PATH after installation. +You can run `hafas-m --version` to verify this. Documentation is available via +`man hafas-m`. + +### 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: + +``` +wget https://lib.finalrewind.org/deb/libtravel-status-de-deutschebahn-perl_latest_all.deb +sudo dpkg -i libtravel-status-de-deutschebahn-perl_latest_all.deb +sudo apt --fix-broken install +rm libtravel-status-de-deutschebahn-perl_latest_all.deb +``` + +For a (possibly broken) development snapshot of the Git master branch, run: + +``` +wget https://lib.finalrewind.org/deb/libtravel-status-de-deutschebahn-perl_dev_all.deb +sudo dpkg -i libtravel-status-de-deutschebahn-perl_dev_all.deb +sudo apt --fix-broken install +rm libtravel-status-de-deutschebahn-perl_dev_all.deb +``` + +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::DeutscheBahn installation. + +Uninstallation works as usual: + +``` +sudo apt remove libtravel-status-de-deutschebahn-perl +``` + +### Installation from CPAN + +Travel::Status::DE::DeutscheBahn 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: + +* libssl +* libxml2 +* zlib + +Now, use a tool of your choice to install the module. Minimum working example: + +``` +cpanm Travel::Status::DE::DeutscheBahn +``` + +If you run this as root, it will install script and module to `/usr/local` by +default. + +### Installation from Source + +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. + +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 using the Git repository, use the following commands: + +``` +./Build +./Build manifest +./Build test +sudo ./Build install +``` + +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 **hafas-m** from the +current working directory. + +With carton: + +``` +carton exec hafas-m --version +``` + +Otherwise (also works with carton): + +``` +perl -Ilocal/lib/perl5 -Ilib bin/hafas-m --version +``` + +### Running hafas-m via Docker + +A hafas-m image is available on Docker Hub. It is intended for testing +purposes: due to the latencies involved in spawning a container for each +hafas-m invocation, it is less convenient for day-to-day usage. + +Installation: + +``` +docker pull derfnull/hafas-m:latest +``` + +Use it by prefixing hafas-m commands with `docker run --rm +derfnull/hafas-m:latest`, like so: + +``` +docker run --rm derfnull/hafas-m:latest --version +``` + +Documentation is not available in this image. Please refer to the +[online hafas-m manual](https://man.finalrewind.org/1/hafas-m/) instead. -- cgit v1.2.3