aipp 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09151e277b537c1529951cd69b38bb5d6fc47f855e6041ca3537d36462f93907'
-  data.tar.gz: f0b9d43b940ced7998a079cf6dce602386d52ad90995b7e77a6b6429f09f798e
+  metadata.gz: aead3f21ec1e78d23e1c273e6d19f3db92834bb3dccd8ec77f85bf3c279a7a74
+  data.tar.gz: 8c1203247d9a8714fabb704fabbd972364f6c1544b2294b6ae004a59ebf94c74
 SHA512:
-  metadata.gz: 205b609c8aad3999495447f7c55aba98282b5b6347a4f89caef3e06e3edc8f8e28c4e523cc48737522f895813309fe9d4f7b8d3d2d0db37a12d5808c41509137
-  data.tar.gz: 9a228dd7a152dfd5e0bbbd22b8a068e8de404ba9a4d48f4a30f7b3f0b352c694f12b4a45b543880b20884645fbd52fa475dd738f7385541113462dcadce1fc29
+  metadata.gz: '09e058cee67ad5456af31c5cbc93462207303f89857e4bc709d9c09fb9f82212f24db2c59fe1e99a26b0153449f5b347aedd731114b2c549e246a23f270c558a'
+  data.tar.gz: 00c2fdf2386236e31f965317d1d743522adf70a10e80fbf04371ed5c350dcc22f490592ab06d05665a6d8acc55257b458a81cc5c151c031e6b4fc7b4bb04548f

checksums.yaml.gz.sig

@@ -1,2 +1,2 @@
-`��˼��e����z�t��pR3�^±�ܛ�Q�.ܾ�`�ާz|�/����rH��.cJS�@�,W��&v����C1�8�"�u��Mʡ��2|�&5tp[q�MD^�T'�C��:���2#]Zu}�oP�~ �����	�@��nE�NÞJ�4~��kW
-�}�T�v����/;��E� ��P�_"��KR���lWz��^�d/�l�9KY��-+'��wY�����1R�Z[_���bv���*V��(�;�
+��~@f���x�i�h*���=�L���b�0��'�Ђ2z
Uh���7�H�4~�]ӧ^� �\�+�0����W-��`������ۡM�n&��*^�Gm��h��킡.�LRi�&��*,�꛿
+Oʼn�7������E��F���H��;[fp�=���3���%�bS��TP̥��)���,s����Q���d#�Ku��	
����[N���byN{�'TR�i��p��/+S�b�U͂����d:V8��zw

data/CHANGELOG.md

@@ -2,10 +2,26 @@
 
 Nothing so far
 
+## 2.0.0
+
+#### Additions
+* Region LS NOTAM
+* CLI option to set a custom output file
+* `--quiet` option
+
+#### Breaking Changes
+* Drop support for Ruby 3.0
+* Rename `url_for` to `origin_for` and introduce origin structures which allow
+  for more complex download scenarios such as HTTPS with session or GraphQL.
+* Overhaul file/class layout to accommodate other than AIP, implement NOTAM.
+* Cache, borders, fixtures, options and config are now dedicated objects
+  accessible on `AIPP`.
+* Patches are no longer passed the parser instance.
+
 ## 1.0.0
 
 #### Breaking Changes
-* Switch from individual AIP HTML section files to the comprehensive AIP XML
+* Switch from individual AIP HTML files to the comprehensive AIP XML
   database dump for the LF region reference implementation.
 * Drop the mandatory `URL` helper in favour of a mandatory `url_for` method.
 * Renamed default git branch to `main`

data/README.md

@@ -4,23 +4,22 @@
 
 # AIPP
 
-Parser for Aeronautical Information Publication (AIP) available online.
+Parser for aeronautical information available online.
 
-This gem incluces two executables to download and parse aeronautical data as HTML, PDF, XSLX, ODS and CSV, then build and export is as [AIXM](https://github.com/svoop/aixm) or [OFMX](https://github.com/openflightmaps/ofmx/wiki).
+This gem incluces executables to download and parse aeronautical information (HTML, PDF, XSLX, ODS and CSV), then build and export is as [AIXM](https://github.com/svoop/aixm) or [OFMX](https://github.com/openflightmaps/ofmx/wiki).
 
 * [Homepage](https://github.com/svoop/aipp)
 * [Rubydoc](https://www.rubydoc.info/gems/aipp/AIPP)
-* Author: [Sven Schwyn - Bitcetera](http://www.bitcetera.com)
+* Author: [Sven Schwyn - Bitcetera](https://bitcetera.com)
 
 ## Table of Contents
 
-[Install](#install)<br>
-[Usage](#usage)<br>
-[Storage](#storage)<br>
-[Regions](#regions)<br>
-[AIRAC Date Calculations](#airac-date-calculations)<br>
-[References](#references)<br>
-[Development](#development)
+[Install](#label-Install) <br>
+[Usage](#label-Usage) <br>
+[Regions](#label-Regions) <br>
+[Storage](#label-Storage) <br>
+[References](#label-References) <br>
+[Development](#label-Development)
 
 ## Install
 
@@ -42,10 +41,10 @@ gem install aipp --trust-policy MediumSecurity
 
 ### Bundler
 
-If you're familiar with [Bundler](https://bundler.io) powered Ruby projects, you might prefer to add the following to your <tt>Gemfile</tt> or <tt>gems.rb</tt>:
+If you're familiar with [Bundler](https://bundler.io) powered Ruby projects, you might prefer to add the following to your <samp>Gemfile</samp> or <samp>gems.rb</samp>:
 
 ```ruby
-gem aipp
+gem 'aipp'
 ```
 
 And then install the bundle:
@@ -56,98 +55,117 @@ bundle install --trust-policy MediumSecurity
 
 ## Usage
 
-See the built-in help for all options:
+AIPP parses different kind of information sources. The parsers are organized in three levels:
 
 ```
-aip2aixm --help
-aip2ofmx --help
+region            ⬅︎ aeronautical region such as "LF" (France)
+└── module        ⬅︎ subject area such as "AIP" or "NOTAM"
+    └── section   ⬅︎ part of the subject area such as "ENR-2.1" or "aerodromes"
 ```
 
-Say, you with to build the complete OFMX file for the current AIRAC cycle of the region LF:
+The following modules are currently available:
 
-```
-aip2ofmx -r LF
-```
+Module | Content | Executables | Cache
+-------|---------|-------------|------
+[AIP](lib/aipp/aip/README.md) | aeronautical information publication | `aip2aixm` and `aip2ofmx` | by AIRAC cycle
+[NOTAM](lib/aipp/notam/README.md) | notice to airmen | `notam2aixm` and `notam2ofmx` | by effective date and hour
 
-You'll find the OFMX file in the current directory if the binary exits successfully.
-
-## Storage
-
-AIPP uses a storage directory for configuration, caching and in order to keep the results of previous runs. The default location is `~/.aipp`, however, you can pass a different directory with the `--storage` argument.
+To list all available regions and sections for a given module:
 
-You'll find a directory for each region which contains the following items:
+```
+aip2aixm --list
+```
 
-* `sources/`<br>This directory contains one ZIP archive per AIRAC cycle which incrementially caches all source files used to build the AIXM/OFMX file. Therefore, to make sure it contains all source files for a region, you have to build at least one complete AIXM/OFMX file for that region.
-* `builds/`<br>This directory contains one ZIP archive per AIRAC cycle which is overwritten on every run. Therefore, to make sure it contains the complete build for a region, you have to make sure that your last run builds the complete AIXM/OFMX for that region. This archive contains:
-  * the built AIXM/OFMX file
-  * `build.yaml` – context of the build process
-  * `manifest.csv` – diffable manifest (see below)
-* `config.yml`<br>This file contains configuration which will be read on subsequent runs, most notably the namespace UUID used to identify the creator of OFMX files.
+See the built-in help for all options:
 
-The manifest is a CSV which lists every feature on a separate line along with its hashes, AIP and comment. You can `diff` or `git diff` two manifests:
+```
+notam2aixm --help
+```
 
-```diff
-$ git diff -U0 2019-09-12/manifest.csv 2019-10-10/manifest.csv
+Example: You wish to build the complete OFMX file for the current AIRAC cycle AIP of the region LF:
 
---- a/2019-09-12/manifest.csv
-+++ b/2019-10-10/manifest.csv
-@@ -204 +204 @@ AD-1.3,Ahp,9e9f031e,d6f22057,Airport: LFLJ COURCHEVEL
--AD-1.3,Ahp,9f1eed18,37ddbbde,Airport: LFQD ARRAS ROCLINCOURT
-+AD-1.3,Ahp,9f1eed18,f0e60105,Airport: LFQD ARRAS ROCLINCOURT
-@@ -312 +312 @@ AD-2,Aha,4250c9ee,04d49dc7,Address: RADIO for LFHV
--AD-2,Aha,6b381b32,fb947716,Address: RADIO for LFPO
-+AD-2,Aha,6b381b32,b9723b7e,Address: RADIO for LFPO
-@@ -664 +663,0 @@ AD-2,Ser,3920a7fd,4545c5eb,Service: AFIS by LFGA TWR
--AD-2,Ser,39215774,1f13f2cf,Service: APP by LFCR APP
-@@ -878 +876,0 @@ AD-2,Ser,bb5228d7,7cfb4572,Service: TWR by LFMH TWR
--AD-2,Ser,bc72caf2,0a15b39c,Service: FIS by LFCR FIC
-(...)
+```
+aip2ofmx -r LF
 ```
 
-The advantage of `git diff` is it's ability to hightlight exactly which part of a line has changed. [Check out this post to learn how](https://www.viget.com/articles/dress-up-your-git-diffs-with-word-level-highlights/).
+You'll find the OFMX file in the current directory if the binary exits successfully.
 
 ## Regions
 
-The reference implementation is region "LF" (France).
+To implement a region, you have to create a directory <samp>lib/aipp/regions/{REGION}/</samp> off the gem root and then subdirectories for each module as well as for support files. Here's a simplified overview for the region "LF" (France):
 
-To implement a region, you have to create a new directory <tt>lib/aipp/regions/{REGION}/</tt> and place the following files there:
+```
+LF/                         ⬅︎ region "LF"
+├── README.md
+├── aip                     ⬅︎ module "AIP"
+│   ├── AD-2.rb             ⬅︎ section "AD-2"
+│   └── ENR-4.3.rb          ⬅︎ section "ENR-4.3"
+├── notam                   ⬅︎ module "NOTAM"
+│   ├── AD.rb               ⬅︎ section "AD"
+│   └── ENR.rb              ⬅︎ section "ENR"
+├── borders
+│   ├── france_atlantic_coast.geojson
+│   └── france_atlantic_territorial_sea.geojson
+├── fixtures
+│   └── aerodromes.yml
+└── helpers
+    ├── base.rb
+    └── surface.rb
+```
 
-### AIP Parsers
+<table>
+  <tr>
+    <td>⚠️</td>
+    <td>All paths from here on forward are relative to the region directory.</td>
+  </tr>
+</table>
 
-Say, you want to parse ENR-4.3, you have to create the file <tt>ENR-4.3.rb</tt> which defines the class `AIPP::LF::ENR43` as follows:
+### Parsers
+
+Say, you want to parse AIP ENR-4.1. You have to create the file <samp>aip/ENR-4.1.rb</samp> which defines the class `ENR41` as follows:
 
 ```ruby
-module AIPP
-  module LF
-    class ENR43 < AIP
+module AIPP::LF::AIP
+  class ENR41 < AIPP::AIP::Parser
+    depends_on :ENR21, :ENR22   # declare dependencies to other parsers
+    (...)
+  end
+end
+```
 
-      DEPENDS = %w(ENR-2.1 ENR-2.2)   # declare dependencies to other AIPs
+Another parser might target en-route NOTAM and therefore has to go to <samp>notam/ENR.rb</samp> like so:
 
-    end
+```ruby
+module AIPP::LF::NOTAM
+  class ENR < AIPP::NOTAM::Parser
+    (...)
   end
 end
 ```
 
-The class has to implement some methods either in the class itself or in a [helper](#Helpers) included by the class.
+<table>
+  <tr>
+    <td>⚠️</td>
+    <td>Parser files and classes may follow AIP naming conventions such as <samp>ENR-4.1.rb</samp>. However, you're free to use arbitrary naming for parser files like <samp>navaids.rb</samp> (e.g. if you're working with one big data source which contains the full AIP dataset you'd like to split into smaller parts).</td>
+  </tr>
+</table>
 
-⚠️ Parser files usually follow AIP naming conventions such as `ENR-4.3`. However, you're free to use arbitrary naming for parser files e.g. if you're working with one big data source which contains the full AIP dataset.
+The class has to implement some methods either in the class itself or in a [helper](#Helpers) included by the class.
 
 #### Mandatory `parse` Method
 
 The class must implement the `parse` method which contains the code to read, parse and write the data:
 
 ```ruby
-module AIPP
-  module LF
-    class ENR43 < AIP
-
-      def parse
-        html = read             # read the Nokogiri::HTML5 document
-        feature = (...)         # build the feature
-        add(feature: feature)   # add the feature to AIXM::Document
-      end
+module AIPP::LF::AIP
+  class ENR41 < AIPP::AIP::Parser
 
+    def parse
+      html = read             # read the Nokogiri::HTML5 document
+      feature = (...)         # build the feature
+      add(feature: feature)   # add the feature to AIXM::Document
     end
+
   end
 end
 ```
@@ -155,95 +173,171 @@ end
 Some AIP may be split over several files which require a little more code to load the individual HTML source files:
 
 ```ruby
-module AIPP
-  module LF
-    class AD2 < AIP
-
-      def parse
-        %i(one two three).each do |part|
-          html = read("#{aip}.#{part}")   # read with a non-standard name
-          support_html = read('AD-0.6')   # maybe read necessary support documents
-          (...)
-        end
+module AIPP::LF::AIP
+  class AD2 < AIPP::AIP::Parser
+
+    def parse
+      %i(one two three).each do |part|
+        html = read("#{aip}.#{part}")   # read with a non-standard name
+        support_html = read('AD-0.6')   # maybe read necessary support documents
+        (...)
       end
-
     end
+
   end
 end
 ```
 
-Inside the `parse` method, you have access to the following methods:
+The parser has access to the following methods:
 
 Method | Description
 -------|------------
-[`read`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#read-instance_method) | download and read an AIP file
-[`add`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#add-instance_method) | add a [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)
-[`find`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by object
-[`find_by`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find_by-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by class and attribute values
-[`unique`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#unique-instance_method) | prevent duplicate [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s
-[`given`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#given-instance_method) | inline condition for assignments
-[`link_to`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#link_to-instance_method) | optionally checked Markdown link
-[`Object#blank`](https://www.rubydoc.info/gems/activesupport/Object#blank%3F-instance_method) and [`String`](https://www.rubydoc.info/gems/activesupport/String) | some core extensions from ActiveSupport
-[`aip`](https://www.rubydoc.info/gems/aipp/AIPP%2FAIP:aip) | AIP name (equal to the parser file name without its file extension such as "ENR-2.1" implemented in the file "ENR-2.1.rb")
-[`aip_file`](https://www.rubydoc.info/gems/aipp/AIPP%2FAIP:aip_file) | AIP file as passed and possibly renamed by `url_for`
-[`options`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#options-instance_method) | arguments read from <tt>aip2aixm</tt> or <tt>aip2ofmx</tt> respectively
-[`config`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#config-instance_method) | configuration read from <tt>config.yml</tt>
-[`borders`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#borders-instance_method) | borders defined as GeoJSON read from the region (see below)
-[`cache`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#cache-instance_method) | `OStruct` instance to make objects available across AIPs
-
-To make the parser code more readable, this gem provides a few useful core extensions as well:
+[`section`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#section-instance_method) | current section (e.g. `ENR-2.1` or `aerodromes`)
+[`read`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#read-instance_method) | download, cache and read a document from source
+[`add`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#add-instance_method) | add a [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)
+[`find`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#find-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by object
+[`find_by`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#find_by-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by class and attribute values
+[`unique`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#unique-instance_method) | prevent duplicate [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s
+[`given`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#given-instance_method) | inline condition for assignments
+[`link_to`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#link_to-instance_method) | optionally checked Markdown link
 
+Equally available is the current runtime environment. All of the following objects behave like `OpenStruct`:
+
+Method | Description
+-------|------------
+[`AIPP.cache`](https://www.rubydoc.info/gems/aipp/AIPP/Enrivonment/Cache) | cache to make transient objects available across AIPs
+[`AIPP.borders`](https://www.rubydoc.info/gems/aipp/AIPP/Enrivonment/Borders) | [borders](#Borders) of the current region
+[`AIPP.fixtures`](https://www.rubydoc.info/gems/aipp/AIPP/Enrivonment/Fixtures) | [fixtures](#Fixtures) of the current region
+[`AIPP.options`](https://www.rubydoc.info/gems/aipp/AIPP/Environment/Options) | arguments read from <samp>aip2aixm</samp> or <samp>aip2ofmx</samp> respectively
+[`AIPP.config`](https://www.rubydoc.info/gems/aipp/AIPP/Environment/Config) | configuration read from <samp>config.yml</samp>
+
+To make the parser code more readable, a few core extensions are provided:
+
+* [`Object#blank` (ActiveSupport)](https://www.rubydoc.info/gems/activesupport/Object#blank%3F-instance_method)
 * [`NilClass`](https://www.rubydoc.info/gems/aipp/NilClass)
 * [`Integer`](https://www.rubydoc.info/gems/aipp/Integer)
+* [`String` (ActiveSupport)](https://www.rubydoc.info/gems/activesupport/String)
 * [`String`](https://www.rubydoc.info/gems/aipp/String)
+* [`Array`](https://www.rubydoc.info/gems/aipp/Array)
 * [`Hash`](https://www.rubydoc.info/gems/aipp/Hash)
 * [`Enumerable`](https://www.rubydoc.info/gems/aipp/Enumerable)
+* [`DateTime` (ActiveSupport)](https://www.rubydoc.info/gems/activesupport/DateTime)
 * [`Nokogiri`](https://www.rubydoc.info/gems/aipp/Nokogiri)
 
-#### Mandatory `url_for` Method
+#### Mandatory `origin_for` Method
 
-The class must implement the `url_for` method which returns the URL from where to download the AIP file:
+The class must implement the `origin_for` method which returns an origin object describing how to download the source data (e.g. an AIP file or NOTAM message):
 
 ```ruby
-module AIPP
-  module LF
-    class AD2 < AIP
-
-      def url_for(aip_file)
-        # build and return the download URL for the aip file
-      end
+module AIPP::LF::AIP
+  class AD2 < AIPP::AIP::Parser
 
+    def origin_for(document)
+      # build and return the origin object
     end
+
   end
 end
 ```
 
-There are a few things to note about `url_for`:
+Return any of the following origin objects best explained by example:
 
-* If the returned string begins with a protocol like `https:`, the downloader will fetch the file from there.
-* If the returned string is just a file name, the downloader will look for this exact file in the current local directory.
-* The passed `aip_file` will be used as the file name for the local copy in the sources directory. You can rename it on the fly by assigning a new value to this variable.
+```
+AIPP::Downloader::File.new(
+  file: "file.dat",   # relative path to file
+  type: :pdf          # optional: file type if different from extension
+)
+```
 
-#### Optional `setup` Method
+```
+AIPP::Downloader::File.new(
+  archive: "foobar.zip",     # relative path to archive
+  file: "subdir/file.dat",   # file to extract from archive
+  type: :pdf                 # optional: file type if different from extension
+)
+```
 
-The class may implement the `setup` method. If present, it will be called when this parser is instantiated:
+See [Downloader](https://www.rubydoc.info/gems/aipp/AIPP/Downloader) for more on recognised file and archive types.
 
+```
+AIPP::Downloader::HTTP.new(
+  file: "https://example.com/foobar.zip",   # URL where the file is located
+  type: :pdf,                               # optional: file type if different from extension
+  headers: "Cookie: name=value",            # optional: additional headers e.g. for session
+)
+```
+
+```
+AIPP::Downloader::HTTP.new(
+  archive: "https://example.com/foobar.zip",   # URL where the archive is located
+  file: "subdir/file.dat",                     # file to extract from archive
+  type: :pdf,                                  # optional: file type if different from extension
+  headers: "Cookie: name=value",               # optional: additional headers e.g. for session
+)
+```
+
+The [excon gem](https://www.rubydoc.info/gems/excon) is used to perform HTTP requests.
+
+```
+AIPP::Downloader::GraphQL.new(
+  client: MyAPI::Client,       # GraphQL client class
+  query: MyAPI::Name::Query,   # GraphQL query class
+  variables: {                 # dynamic query parameters
+    first_name: 'Geronimo',
+    age: 50
+  }
+)
+```
+
+For this GraphQL downloader to work, you have to declare a GraphQL client class beforehand. See the [graphql-client gem documentation](https://www.rubydoc.info/gems/graphql-client) for details, the following example fits the downloader above:
 
 ```ruby
-module AIPP
-  module LF
-    class AD2 < AIP
+module MyAPI
+  HttpAdapter = GraphQL::Client::HTTP.new(ENV['MY_API_URL']) do
+    def headers(context)
+      { "Authorization": "Bearer #{ENV['MY_API_AUTHORIZATION']}" }
+    end
+  end
+  Schema = GraphQL::Client.load_schema(HttpAdapter)
+  Client = GraphQL::Client.new(schema: Schema, execute: HttpAdapter)
+
+  class Name
+    Query = Client.parse <<~END
+      query ($first_name: String!, $age: Int!) {
+        queryNOTAMs(
+          filter: {first_name: $first_name, age: $age}
+        ) {
+          name
+        }
+      }
+    END
+  end
+end
+```
 
-      def setup
-        AIXM.config.voice_channel_separation = :any
-        cache.setup_at ||= Time.now
-      end
+For performance, all downloads are cached and subsequent runs will use the cached data rather than fetching the sources anew. Each module defines a cache time window, see the [table of modules above](#label-Usage). You can discard existing and rebuild caches by use of the `--clean` command line argument.
+
+#### Optional `setup` Method
+
+The class may implement the `setup` method. If present, it will be called when this parser is instantiated:
 
+```ruby
+module AIPP::LF::AIP
+  class AD2 < AIPP::AIP::Parser
+
+    def setup
+      AIXM.config.voice_channel_separation = :any
+      AIPP.cache.setup_at ||= Time.now
     end
+
   end
 end
 ```
 
+### Helpers
+
+Helpers are mixins defined in the <samp>helpers/</samp> subdirectory. All helpers are required automatically in alphabetic order.
+
 ### Borders
 
 AIXM knows named borders for country boundaries. However, you might need additional borders which don't exist as named borders.
@@ -252,7 +346,7 @@ You can define additional borders as [`AIPP::Border`](https://www.rubydoc.info/g
 
 #### From GeoJSON
 
-Create simple GeoJSON files in the <tt>lib/aipp/regions/{REGION}/borders/</tt> directory, for example this `my_border_1.geojson`:
+Create simple GeoJSON files in the <samp>borders/</samp> subdirectory, for example this `my_border_1.geojson`:
 
 ```json
 {
@@ -276,7 +370,12 @@ Create simple GeoJSON files in the <tt>lib/aipp/regions/{REGION}/borders/</tt> d
 }
 ```
 
-⚠️ The GeoJSON file must consist of exactly one `GeometryCollection` which may contain any number of `LineString` geometries. Only `LineString` geometries are recognized! To define a closed polygon, the first coordinates of a `LineString` must be identical to the last coordinates.
+<table>
+  <tr>
+    <td>⚠️</td>
+    <td>The GeoJSON file must consist of exactly one `GeometryCollection` which may contain any number of `LineString` geometries. Only `LineString` geometries are recognised! To define a closed polygon, the first coordinates of a `LineString` must be identical to the last coordinates.</td
+  </tr>
+</table>
 
 #### From Coordinates
 
@@ -309,28 +408,26 @@ The border object implements simple nearest point and segment calculations to cr
 
 See [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) for more on this.
 
-### Helpers
+### Fixtures
 
-Helpers are modules defined in the <tt>lib/aipp/regions/{REGION}/helpers/</tt> directory. All helper modules are required automatically in alphabetic order.
+Fixtures are static YAML data files in the <samp>fixtures/</samp> subdirectory. All fixtures are read automatically, e.g. the contents of the <samp>lib/aipp/regions/{REGION}/fixtures/aerodromes.yml</samp> will be available from `AIPP.fixtures.aerodromes`.
 
-### Fixtures and Patches
+Read on for how to best use fixtures.
 
-Fixtures are static YAML data files in the <tt>lib/aipp/regions/{REGION}/fixtures/</tt> directory. All fixtures are read automatically. Please note that the name of the AIP parser (e.g. `AD-1.3.rb`) must match the name of the corresponding fixture (e.g. `fixtures/AD-1.3.yml`).
+### Patches
 
-When parsed data is faulty or missing, you may fall back to such static data instead. This is where patches come in. You can patch any AIXM attribute setter by defining a patch block inside the AIP parser and accessing the static data via `parser.fixture`:
+When parsed data is faulty or missing, you may fall back to fixtures instead. This is where patches come in. You can patch any AIXM attribute setter by defining a patch block inside the AIP parser and accessing the static data via `parser.fixture`:
 
 ```ruby
-module AIPP
-  module LF
-    class AD2 < AIP
-
-      patch AIXM::Feature::Airport, :z do |parser, object, value|
-        throw(:abort) unless value.nil?
-        throw(:abort, 'fixture missing') unless z = parser.fixture.dig(object.id, 'z')
-        AIXM.z(z, :qnh)
-      end
+module AIPP::LF::AIP
+  class AD2 < AIP
 
+    patch AIXM::Feature::Airport, :z do |object, value|
+      throw(:abort) unless value.nil?
+      throw(:abort, 'fixture missing') unless z = AIPP.fixtures.aerodromes.dig(object.id, 'z')
+      AIXM.z(z, :qnh)
     end
+
   end
 end
 ```
@@ -341,12 +438,6 @@ The patch receives the object and the value which is about to be assigned. It sh
 * Otherwise, try to fetch a better value e.g. from the fixtures. If no better value can be found (e.g. outdated fixtures), `throw(:abort, "reason")` to leave the patch block and fail with a useful error message which contains the reason thrown.
 * At last, build and return the value object which will be assigned instead of the original value.
 
-In case the `object` does not carry enough details, you can access instance variables of the parser like so:
-
-```ruby
-parser.instance_variable_get(:@instance_variable)
-```
-
 ### Source File Line Numbers
 
 In order to reference the source of an AIXM/OFMX feature, it's necessary to know the line number where a particular node occurs in the HTML source file. You can ask any HTML element as follows:
@@ -369,7 +460,12 @@ You should `warn` on non-fatal problems which should be fixed (default) or might
 
 ```ruby
 warn("my message")
-warn("my message", severe: false)   # show warning only when --unsevere-warn argument is set
+```
+
+Less important warnings are only shown if the `--verbose` mode is set:
+
+```ruby
+warn("my message", severe: false)
 ```
 
 ### Messages
@@ -399,18 +495,41 @@ The [default Ruby debugger](https://github.com/ruby/debug#debug-command-on-the-d
 debugger
 ```
 
-## AIRAC Date Calculations
+## Storage
+
+AIPP uses a storage directory for configuration, caching and in order to keep the results of previous runs. The default location is `~/.aipp`, however, you can pass a different directory with the `--storage` argument.
 
-The `AIPP::AIRAC` class is used to calculate AIRAC cycles:
+You'll find a directory for each region and module which contains the following items:
 
-```ruby
-airac = AIPP::AIRAC.new(Date.parse('2017-12-24'))
-airac.date        # => 2018-12-07
-airac.id          # => 1713
-airac.next_date   # => 2018-01-04
-airac.next_id     # => 1801
+* `sources/`<br>ZIP archives which cache all source files used to build.
+* `builds/`<br>ZIP archives of successful builds containing:
+  * the built AIXM/OFMX file
+  * `build.yaml` – context of the build process
+  * `manifest.csv` – diffable manifest (see below)
+* `config.yml`<br>This file contains configuration which will be read on subsequent runs, most notably the namespace UUID used to identify the creator of OFMX files.
+
+The manifest is a CSV which lists every feature on a separate line along with its hashes, AIP and comment. You can `diff` or `git diff` two manifests:
+
+```diff
+$ git diff -U0 2019-09-12/manifest.csv 2019-10-10/manifest.csv
+
+--- a/2019-09-12/manifest.csv
++++ b/2019-10-10/manifest.csv
+@@ -204 +204 @@ AD-1.3,Ahp,9e9f031e,d6f22057,Airport: LFLJ COURCHEVEL
+-AD-1.3,Ahp,9f1eed18,37ddbbde,Airport: LFQD ARRAS ROCLINCOURT
++AD-1.3,Ahp,9f1eed18,f0e60105,Airport: LFQD ARRAS ROCLINCOURT
+@@ -312 +312 @@ AD-2,Aha,4250c9ee,04d49dc7,Address: RADIO for LFHV
+-AD-2,Aha,6b381b32,fb947716,Address: RADIO for LFPO
++AD-2,Aha,6b381b32,b9723b7e,Address: RADIO for LFPO
+@@ -664 +663,0 @@ AD-2,Ser,3920a7fd,4545c5eb,Service: AFIS by LFGA TWR
+-AD-2,Ser,39215774,1f13f2cf,Service: APP by LFCR APP
+@@ -878 +876,0 @@ AD-2,Ser,bb5228d7,7cfb4572,Service: TWR by LFMH TWR
+-AD-2,Ser,bc72caf2,0a15b39c,Service: FIS by LFCR FIC
+(...)
 ```
 
+The advantage of `git diff` is its ability to highlight exactly which part of a line has changed. [Check out this post to learn how](https://www.viget.com/articles/dress-up-your-git-diffs-with-word-level-highlights/).
+
 ## References
 
 * [Geo Maps – programmatically generated GeoJSON maps](https://github.com/simonepri/geo-maps)
@@ -431,7 +550,7 @@ Please submit issues on:
 
 https://github.com/svoop/aipp/issues
 
-To contribute code, fork the project on Github, add your code and submit a pull request:
+To contribute code, fork the project on GitHub, add your code and submit a pull request:
 
 https://help.github.com/articles/fork-a-repo