= natour

This https://rubygems.org/[RubyGem^] provides an application and a library for reports on nature activities.

== Installation

. Install the <<Prerequisites>>
. Install the gem
+
NOTE: Use `sudo` on Ubuntu
+
[source,shell]
----
gem install natour
----

=== Prerequisites

Install the required components by following the instructions below. Please read the installation guide of the components if you encounter any problems or if your OS is not listed below (e.{nbsp}g. macOS).

==== Windows

. Download and install the latest version from https://rubyinstaller.org/[RubyInstaller for Windows^]
. Download and install the latest version from https://www.google.com/chrome/[Google Chrome-Webbroser^]
. Add `BROWSER_PATH=path\to\chrome.exe` to the environment variables
. Log off Windows and back on again to ensure the environment variable takes effect

==== Ubuntu

. Install https://www.ruby-lang.org/[Ruby^]
+
[source,shell]
----
sudo apt install ruby
----

. Install https://nokogiri.org/[Nokogiri^] dependencies
+
[source,shell]
----
sudo apt install build-essential patch ruby-dev zlib1g-dev liblzma-dev
----

. Install https://libvips.github.io/libvips/[libvips^]
+
[source,shell]
----
sudo apt install libvips42
----

. Install https://www.google.com/chrome/[Google Chrome-Webbroser^]
+
[source,shell]
----
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install ./google-chrome-stable_current_amd64.deb
----

== Application

[cols="1,4",options=header]
|===
|Command
|Description

|`natour`
|Create reports in https://asciidoc.org/[AsciiDoc^] format from a directory with GPS tracks, images and species lists. After editing the AsciiDoc files, they can be converted to various formats, including PDF and HTML. Use `natour --help` to get more information.
|===

=== Configuration

The configuration is built by loading https://yaml.org/[YAML^] files in hierarchical order. The files must be named `natour.yml` and are loaded first from the home directory of the current user and then from the current working directory. The values of the previously loaded files are overwritten by the values of the files loaded later. The key-value pairs are stored internally in a Ruby Hash, where the keys correspond to the command line arguments without leading dashes and without `no-` prefix for boolean switches.

How to restrict GPS tracks to the FIT format (see https://developer.garmin.com/fit/[FIT SDK^]) and add additional map layers (see https://api3.geo.admin.ch/api/faq/index.html#which-layers-are-available[API FAQ - GeoAdmin API 3.0 documentation^]) is shown in the example below.

[source,yml]
----
---
track-formats:
  - !ruby/sym fit
map-layers:
  - ch.swisstopo.swisstlm3d-wanderwege
  - ch.bav.haltestellen-oev
----

== Library

=== Basic Use

The basic use is shown in the following example. For details, see the source code and the unit tests.

[source,ruby]
----
require 'natour'

Natour::create('path/to/dir')
----

[source,ruby]
----
require 'natour'

Natour::convert('path/to/dir/report.adoc')
----

=== Testing

Execute the following command to run the tests. Add `-Ilib` to the command to run the tests against the library sources instead of the installed gem.

NOTE: Some tests require an Internet connection.

[source,shell]
----
ruby ./test/test.rb
----

Run the following command to check the style and formatting by https://rubocop.org/[RuboCop^].

[source,shell]
----
rubocop
----