System description and installation instructions for
Wilkinson’s Gazetteer and Bibliography of the Mines and Quarries of North Wales



This document provides a system description of the on-line (WWW) searchable implementation (data and code) of Jeremy Wilkinson’s Gazetteer and Bibliography of the Mines and Quarries of North Wales.

It is provided primarily for anyone who may have to maintain the data or the system as a whole and anyone who may have to port the system to a new server.

System Design

Design objectives

The following objectives were adopted:


System functionality is partitioned between:

Communication between these subsystems in the form of HTTP requests and responses. Each search request from the UI generates a single HTTP request and its response.

User interface

This is structured as:

The query form uses drop-down menus for the majority of search terms and the minimum of free text fields. The use of menus guides the user in formulating searches and restricts the amount of input validation required to just the two free text input fields. These fields are validated as follows:

‘name’ input field valid entries:

‘place’ field valid entries:

Responses to user queries in the form of text or map images are displayed in a delineated response display area.

Any change to the data entered in the query form will invoke a new search request (i.e. there is no explicit ‘Search’ button or icon).


User interface

This is a collection of HTML, CSS, JavaScript and map marker image files. For each type of query (site, entity and grant) there is an HTML file and a corresponding JavaScript file. A further JavaScript file contains common functions etc. and there is a common CSS file to control overall styling.

To meet the objective of allowing the user to refine a single element of their query (or change the display option) and see the results immediately whilst leaving the other elements of the query unchanged nn AJAX technique has been used (albeit not using XML).

The UI:

The web browser window can be resized without affecting system functionality.

The UI has been tested and appears to operate correctly with Firefox, Google Chrome, Microsoft Edge, Opera and Safari web browsers on Apple Macinstosh and Safari on Apple iPad.

Server software

This is a collection of Perl CGI scripts and supporting Perl modules. Perl was chosen as the scripting language primarily because of the author’s familiarity with it.

The server software:

Scripts are invoked once per user request and terminate once the request is satisfied.

Data Maintenace

Data files are plain text flat files which are searched sequentially. A database was not used on the grounds of simplicity of data maintenance and to reduce external dependencies.

The optional URL argument SHOW_IDS will invoke the following aids to data maintenance:

SHOW_IDS=1The site, entity or grant record id is shown in output (in red) for each record displayed. A ‘Refresh’ button is provided for each gazetteer record displayed so that changes to data can be made visible as soon as those changes have been made and the display refreshed.
SHOW_IDS=2As SHOW_IDS=1 plus site and entity ids are shown (again in red) within records.

Directory organisation

Top-level directory Wilkinson/

index.htmlGazetteer ‘front page’ with an introduction to the system and link to the gazetteer search page. It includes acknowledgments and copyright information.
README.htmlThis file

Sub-directory Wilkinson/info/

changeLog.htmlSystem change log
gazetteerData.htmlBackground information for users about the origin of, and subsequent changes to, the data used by the gazetteer.

Sub-directory Wilkinson/ui/

User interface: HTML, CSS, JavaScript, map marker images etc.

index.htmlGazetteer user interface ‘front page’
entity.htmlSearch form and results display for individuals, companies and organisations
entity.jsJavaScript for entity.html
grant.htmlSearch form and results display for crown grants
grant.jsJavaScript for grant.html
site.htmlSearch form and results display for mine and quarry searches
site.jsJavaScript for site.html
wilkinson.cssStyle sheet for above HTML files
wilkinson.jsCommon JavaScript functions for the above HTML files
jquery.jsjQuery JavaScript API library (renamed from jQuery 3.5.1.js)
Image files for site markers on map display

Sub-directory Wilkinson/cgi/

Perl 5 CGI scripts (.cgi) and their supporting Perl module files (.pm)

entity.cgiIndividual, company and organisation search
grant.cgiCrown grant search
site.cgiMine and quarry site search
osgb.pmConversion routines for latitude/longitude to/from OS British national grid and alphanumberic numeric to/from numeric grid references. Used by site.cgi. The code used for conversions between GB OS grid and latitude/logitude and their supporting subroutines is directly derived from Toby Thurston’s Perl cpan package Copyright © Toby Thurston ( 2002–2013.
wilkinson.pmCommon functions for CGI scripts. This module contains file names and file record formats (used with unpack() expressions) for the above scripts.
These scripts extract data in response to the search criteria, collate references, generate cross-references and apply style directives to the data for display.

Identifiers in code generally have meaningful names. Comments are generally minimal.

CGI development has used Perl v5.018.004

Sub-directory  Wilkinson/data/

The design philosophy is:

File content:

ENTITY.datIndividual, company and organisation names – each entity has a 5-digit identifier
GRANT.datCrown grants
SITE.datMine and quarry sites – each site has a 5-digit identifier
EMPLOYMENT.datNumbers of men employed above and below ground at sites
LTDCO.datLimited company registered address(es) and main objects clause text
British grid references for post codes and place names – used by site.cgi when searching for sites within a specified distance of a postcode area or named place
PRODUCTION.datProduction records for sites
REFERENCE.datBibliographical references for sites. When displayed, reference page numbers are de-duplicated, page ranges are elided correctly, overlapping and contained page number ranges are normalised and references are sorted for output.
ROLE.datAssociates entities with roles and years active at sites (e.g. agent) or in companies (e.g. company director)

Sub-directory Wilkinson/translations/

Used to expand various fixed-length codes in data files for county, parish, product etc. to human-readable text.

COUNTY.datCounty identifier in GRANT.dat and SITE.dat to county name e.g. M translates to ‘Merioneth’
GRANT_TYPE.datGrant type id in GRANT.dat to grant type e.g. 3 translates to ‘take note’
NLS_MAP.datMap series identifier and sheet number in REFERENCE.dat to NLS sheet file name and survey/revision and publication dates (used to create links to maps on NLS website)
PARISH.datParish identifier in GRANT.dat and SITE.dat to parish name e.g. AM translates to ‘Llanaber’
PRODUCT.datProduct identifier in SITE.dat to product name e.g. MN translates to ‘manganese’
ROLE_NAME.datRole identifier in ROLE.dat to role name e.g. AG translates to ‘Agent’
SOURCE.datSource identifier in REFERENCE.dat to source title e.g. 013 translates to ‘Inspector of Mines Reports’

Sub-directory Wilkinson/utilities/

Data maintenance utilities (not available on public server)

checkData.cgiError and consistency checks on gazetteer data. This checks for:
  • limited companies with no company information
  • site references that do not have a corresponding site record (as may happen if a site is deleted but its references are not deleted)
  • coded information such as product code, role id etc. that do not have a corresponding translation
  • duplicate entity and reference records
  • incomplete entity names
  • missing page references
  • unresolved ‘see’ and ‘see also’ references

wilkinson.pmCommon functions for CGI utility scripts (alias to in Wilkinson/cgi/ directory)

Sub-directory Wilkinson/search/

index.htmlRedirection page following directory reorganisations 9 May 2020

External Dependencies


The main external dependency is the use of the Ordnance Survey’s Data Hub map service to source OS map tiles used for maps on which site locations can be shown.

The Leaflet open-source JavaScript library is used to implement map display and related functionality.

The jQuery JavaScript library is used to simplify the JavaScript code. A local copy of this is included in the Wilkinson/ui directory.

External data

The gazetteer reference data contain links to a number of external sites. In particular use is made of National Library of Scotland’s online historic OS maps. All external links open in a new window and their non-availablity does not affect the operation of the gazetteer.


An appropriate Web server and Perl interpreter installation is required. (The current public server uses Apache 2.4.46 (Unix) and Perl v5.016.) The system requires approximately 2.7 MByte of disk space.

The top-level directory Wilkinson/ should be put in a suitable location for the web server to serve the html pages and execute the CGI scripts. (The server configuration should allow execution of the CGI scripts in the Wilkinson/cgi/ directory.)

CGI scripts should have ‘execute’ permission set for the server process. (If in doubt use ’world’ to allow CGI execution by any process.)

An API key for the Ordnance Survey data is required. This is stored as a text string assigned to the variable $API_KEY as the first non-comment statement in Wilkinson/cgi/site.cgi

Return to Gazetteer front page