natour

Installation
- Prerequisites
Application
- Configuration
Library
Development
- Running
- Testing
- Formatting and linting
- Building

This RubyGem provides an application and a library to document nature activities.

Installation

Install the Prerequisites.
Install the gem:
```
gem install natour
```
Note
Use sudo on Ubuntu.

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. g. macOS).

Windows

Download and install the latest version from RubyInstaller for Windows.
Download and install the latest version from 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 Ruby:
```
sudo apt install ruby
```

Install Nokogiri dependencies:

sudo apt install build-essential patch ruby-dev zlib1g-dev liblzma-dev

Install libvips:
```
sudo apt install libvips
```

Install Google Chrome-Webbroser:

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 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

natour report create "2022-02-26 Monte Caslano"

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 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.

---
: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 FIT SDK) and add additional map layers (see API FAQ - GeoAdmin API 3.0 documentation) is shown in the example below.

---
: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.

require 'natour'

Natour::create_reports('path/to/dir')

require 'natour'

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

Development

Running

To run the application from the source code, the lib directory must be added to $LOAD_PATH.

E. g. show the application version.

ruby -Ilib ./bin/natour --version

Testing

Execute the following command to run the tests.

Note	Some tests require an Internet connection.

ruby -Ilib ./test/test.rb

Formatting and linting

Run the following command to check the style and formatting by RuboCop.

rubocop

Building

gem build ./natour.gemspec

natour

Development

Runtime

natour

Installation

Prerequisites

Windows

Ubuntu

Application

Configuration

Library

Development

Running

Testing

Formatting and linting

Building