= natour

This https://rubygems.org/gems/natour[RubyGem^] provides an application and a library to document 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 libvips
----

. 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

Create reports in https://asciidoc.org/[AsciiDoc^] format from a directory with GPS tracks, images and species lists. After editing the AsciiDoc files (e.g. selecting the images and describing the adventure), they can be converted to various formats, including PDF and HTML. A typical directory structure and the necessary commands are shown in the following example.

....
└─ 2022-02-26 Monte Caslano             < Root directory
   ├─ Bilder                            < Directory containing images
   │  ├─ IMG_7687.JPG
   │  ├─ IMG_7688.JPG
   │  ├─ ...
   │  └─ IMG_7870.JPG
   ├─ 2022-02-26 14.45.27.fit           < GPS track exported by GPS device
   ├─ 2022-02-26 14.45.27.gpx           < GPS track exported by GPS device
   ├─ 2022-02-26 14.45.27.jpg           < Image of the map section created
   ├─ 2022-02-26 Monte Caslano.adoc     < Report in AsciiDoc format created
   ├─ 2022-02-26 Monte Caslano.pdf      < Report converted from AsciiDoc to PDF
   ├─ 2022-02-26MonteCaslano.csv        < Species list exported from Kosmos Vogelführer
   └─ flora_helvetica_sammlungen.csv    < Species list exported from Flora Helvetica
....

[source,shell]
----
natour report create "2022-02-26 Monte Caslano"
----

[source,shell]
----
natour report convert "2022-02-26 Monte Caslano/2022-02-26 Monte Caslano.adoc"
----

NOTE: 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 values are stored internally in nested, dictionary-like collections (Ruby `Hash`), where the structure follows to the command line interface. All keys are of type Ruby `Symbol` and correspond to the commands and options, with middle hyphens replaced by underscores, leading hyphens removed, and without the `no-` prefix for boolean switches. The following configuration file shows all entries and their default values.

[source,yml]
----
---
:report:
  :create:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :track_formats:
      - :gpx
      - :fit
    :map: true
    :map_layers: []
    :adoc_author: null
    :short_species_names: false
  :convert:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :backend: :pdf
    :draft: false
    :draft_backend: null
    :image_maxdim: 1800
:map:
  :create:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :gps_colors: []
    :map_layers: []
    :image_size: [1200, 900]
----

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]
----
---
:report:
  :create:
    :track_formats:
      - :fit
    :map_layers:
      - ch.swisstopo.swisstlm3d-wanderwege
      - ch.bav.haltestellen-oev
----

== Library

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_reports('path/to/dir')
----

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

Natour::convert_report('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
----