Merge remote-tracking branch 'upstream/master'

diff --git a/.github/actions/build-nominatim/action.yml b/.github/actions/build-nominatim/action.yml
index d0a89774637eb9238de77f767daa4451d047e34b..191ef2ee3f8af8c13519cb315bd83a6f47cf13c8 100644 (file)
--- a/.github/actions/build-nominatim/action.yml
+++ b/.github/actions/build-nominatim/action.yml
@@ -6,7 +6,7 @@ runs:
     steps:
         - name: Install prerequisites
           run: |
-            sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu
+            sudo apt-get install -y -qq libboost-system-dev libboost-filesystem-dev libexpat1-dev zlib1g-dev libbz2-dev libpq-dev libproj-dev libicu-dev python3-psycopg2 python3-pyosmium python3-dotenv python3-psutil python3-jinja2 python3-icu python3-argparse-manpage
           shell: bash
 
         - name: Download dependencies

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 40140056a1d99e9355ae1e9656bf70ee1523e782..7c2d7bb38a3ffcc7d61b341376902e1342988e51 100644 (file)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -36,6 +36,7 @@ set(BUILD_API on CACHE BOOL "Build everything for the API server")
 set(BUILD_MODULE on CACHE BOOL "Build PostgreSQL module")
 set(BUILD_TESTS on CACHE BOOL "Build test suite")
 set(BUILD_DOCS on CACHE BOOL "Build documentation")
+set(BUILD_MANPAGE on CACHE BOOL "Build Manual Page")
 set(BUILD_OSM2PGSQL on CACHE BOOL "Build osm2pgsql (expert only)")
 
 #-----------------------------------------------------------------------------
@@ -229,6 +230,14 @@ if (BUILD_DOCS)
    add_subdirectory(docs)
 endif()
 
+#-----------------------------------------------------------------------------
+# Manual page
+#-----------------------------------------------------------------------------
+
+if (BUILD_MANPAGE)
+   add_subdirectory(manual)
+endif()
+
 #-----------------------------------------------------------------------------
 # Installation
 #-----------------------------------------------------------------------------

diff --git a/lib-php/website/search.php b/lib-php/website/search.php
index 4dcbc5b7b84b062354da6e8fca59745103a3c059..72ddebe1e3d32b265775596dc1538d21dad0f612 100644 (file)
--- a/lib-php/website/search.php
+++ b/lib-php/website/search.php
@@ -72,11 +72,11 @@ if (isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) {
 }
 
 if (isset($_SERVER['REQUEST_SCHEME'])
-    && isset($_SERVER['SERVER_NAME'])
+    && isset($_SERVER['HTTP_HOST'])
     && isset($_SERVER['DOCUMENT_URI'])
 ) {
     $sMoreURL = $_SERVER['REQUEST_SCHEME'].'://'
-                .$_SERVER['SERVER_NAME'].$_SERVER['DOCUMENT_URI'].'/?'
+                .$_SERVER['HTTP_HOST'].$_SERVER['DOCUMENT_URI'].'/?'
                 .http_build_query($aMoreParams);
 } else {
     $sMoreURL = '/search.php'.http_build_query($aMoreParams);

diff --git a/manual/CMakeLists.txt b/manual/CMakeLists.txt
new file mode 100644 (file)
index 0000000..9b69b79
--- /dev/null
+++ b/manual/CMakeLists.txt
@@ -0,0 +1,15 @@
+# Creates and installs manual page
+
+configure_file(${PROJECT_SOURCE_DIR}/manual/create-manpage.tmpl create_manpage.py)
+
+find_program(ARGPARSEMANPAGE argparse-manpage)
+
+ADD_CUSTOM_TARGET(manpage
+    COMMAND ${ARGPARSEMANPAGE} --pyfile ${CMAKE_CURRENT_BINARY_DIR}/create_manpage.py
+    --function get_parser --project-name Nominatim
+    --url https://nominatim.org  > ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1
+
+    COMMAND sed -i '/.SH AUTHORS/I,+2 d' ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1
+)
+
+install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/nominatim.1 DESTINATION share/man/man1 )

diff --git a/manual/create-manpage.tmpl b/manual/create-manpage.tmpl
new file mode 100644 (file)
index 0000000..34f00a8
--- /dev/null
+++ b/manual/create-manpage.tmpl
@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+import sys
+import os
+
+sys.path.append('@PROJECT_SOURCE_DIR@')
+
+from nominatim.cli import get_set_parser
+
+def get_parser():
+    parser = get_set_parser(phpcgi_path='@PHPCGI_BIN@')
+
+    return parser.parser

diff --git a/manual/nominatim.1 b/manual/nominatim.1
new file mode 100644 (file)
index 0000000..c5563bb
--- /dev/null
+++ b/manual/nominatim.1
@@ -0,0 +1,1015 @@
+.TH nominatim "1" Manual
+.SH NAME
+nominatim
+.SH SYNOPSIS
+.B nominatim
+[-h] {import,freeze,replication,special-phrases,add-data,index,refresh,admin,export,serve,search,reverse,lookup,details,status,transition} ...
+.SH DESCRIPTION
+    Command\-line tools for importing, updating, administrating and
+    querying the Nominatim database.
+    
+.SH OPTIONS
+
+
+.SS
+\fBSub-commands\fR
+.TP
+\fBnominatim\fR \fI\,import\/\fR
+    Create a new Nominatim database from an OSM file.
+.TP
+\fBnominatim\fR \fI\,freeze\/\fR
+    Make database read-only.
+.TP
+\fBnominatim\fR \fI\,replication\/\fR
+    Update the database using an online replication service.
+.TP
+\fBnominatim\fR \fI\,special-phrases\/\fR
+    Import special phrases.
+.TP
+\fBnominatim\fR \fI\,add-data\/\fR
+    Add additional data from a file or an online source.
+.TP
+\fBnominatim\fR \fI\,index\/\fR
+    Reindex all new and modified data.
+.TP
+\fBnominatim\fR \fI\,refresh\/\fR
+    Recompute auxiliary data used by the indexing process.
+.TP
+\fBnominatim\fR \fI\,admin\/\fR
+    Analyse and maintain the database.
+.TP
+\fBnominatim\fR \fI\,export\/\fR
+    Export addresses as CSV file from the database.
+.TP
+\fBnominatim\fR \fI\,serve\/\fR
+    Start a simple web server for serving the API.
+.TP
+\fBnominatim\fR \fI\,search\/\fR
+    Execute API search query.
+.TP
+\fBnominatim\fR \fI\,reverse\/\fR
+    Execute API reverse query.
+.TP
+\fBnominatim\fR \fI\,lookup\/\fR
+    Execute API lookup query.
+.TP
+\fBnominatim\fR \fI\,details\/\fR
+    Execute API details query.
+.TP
+\fBnominatim\fR \fI\,status\/\fR
+    Execute API status query.
+.TP
+\fBnominatim\fR \fI\,transition\/\fR
+    Internal functions for code transition. Do not use.
+.SH OPTIONS 'nominatim import'
+usage: nominatim import [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                        (--osm-file FILE | --continue {load-data,indexing,db-postprocess})
+                        [--osm2pgsql-cache SIZE] [--reverse-only]
+                        [--no-partitions] [--no-updates] [--ignore-errors]
+                        [--index-noanalyse]
+
+    Create a new Nominatim database from an OSM file.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-osm\-file\fR FILE
+OSM file to be imported.
+
+.TP
+\fB\-\-continue\fR {load\-data,indexing,db\-postprocess}
+Continue an import that was interrupted
+
+.TP
+\fB\-\-osm2pgsql\-cache\fR SIZE
+Size of cache to be used by osm2pgsql (in MB)
+
+.TP
+\fB\-\-reverse\-only\fR
+Do not create tables and indexes for searching
+
+.TP
+\fB\-\-no\-partitions\fR
+Do not partition search indices (speeds up import of single country extracts)
+
+.TP
+\fB\-\-no\-updates\fR
+Do not keep tables that are only needed for updating the database later
+
+.TP
+\fB\-\-ignore\-errors\fR
+Continue import even when errors in SQL are present
+
+.TP
+\fB\-\-index\-noanalyse\fR
+Do not perform analyse operations during index
+
+.SH OPTIONS 'nominatim freeze'
+usage: nominatim freeze [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+
+    Make database read\-only.
+
+    About half of data in the Nominatim database is kept only to be able to
+    keep the data up\-to\-date with new changes made in OpenStreetMap. This
+    command drops all this data and only keeps the part needed for geocoding
+    itself.
+
+    This command has the same effect as the `\-\-no\-updates` option for imports.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.SH OPTIONS 'nominatim replication'
+usage: nominatim replication [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                             [--init] [--no-update-functions]
+                             [--check-for-updates] [--once] [--no-index]
+                             [--osm2pgsql-cache SIZE]
+                             [--socket-timeout SOCKET_TIMEOUT]
+
+    Update the database using an online replication service.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-init\fR
+Initialise the update process
+
+.TP
+\fB\-\-no\-update\-functions\fR
+Do not update the trigger function to support differential updates.
+
+.TP
+\fB\-\-check\-for\-updates\fR
+Check if new updates are available and exit
+
+.TP
+\fB\-\-once\fR
+Download and apply updates only once. When not set, updates are continuously applied
+
+.TP
+\fB\-\-no\-index\fR
+Do not index the new data. Only applicable together with \-\-once
+
+.TP
+\fB\-\-osm2pgsql\-cache\fR SIZE
+Size of cache to be used by osm2pgsql (in MB)
+
+.TP
+\fB\-\-socket\-timeout\fR \fI\,SOCKET_TIMEOUT\/\fR
+Set timeout for file downloads.
+
+.SH OPTIONS 'nominatim special-phrases'
+usage: nominatim special-phrases [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                                 [--import-from-wiki]
+
+    Import special phrases.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-import\-from\-wiki\fR
+Import special phrases from the OSM wiki to the database.
+
+.SH OPTIONS 'nominatim add-data'
+usage: nominatim add-data [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                          (--file FILE | --diff FILE | --node ID | --way ID | --relation ID | --tiger-data DIR)
+                          [--use-main-api]
+
+    Add additional data from a file or an online source.
+
+    Data is only imported, not indexed. You need to call `nominatim\-update index`
+    to complete the process.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-file\fR FILE
+Import data from an OSM file
+
+.TP
+\fB\-\-diff\fR FILE
+Import data from an OSM diff file
+
+.TP
+\fB\-\-node\fR ID
+Import a single node from the API
+
+.TP
+\fB\-\-way\fR ID
+Import a single way from the API
+
+.TP
+\fB\-\-relation\fR ID
+Import a single relation from the API
+
+.TP
+\fB\-\-tiger\-data\fR DIR
+Add housenumbers from the US TIGER census database.
+
+.TP
+\fB\-\-use\-main\-api\fR
+Use OSM API instead of Overpass to download objects
+
+.SH OPTIONS 'nominatim index'
+usage: nominatim index [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                       [--boundaries-only] [--no-boundaries] [--minrank RANK]
+                       [--maxrank RANK]
+
+    Reindex all new and modified data.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-boundaries\-only\fR
+Index only administrative boundaries.
+
+.TP
+\fB\-\-no\-boundaries\fR
+Index everything except administrative boundaries.
+
+.TP
+\fB\-\-minrank\fR RANK, \fB\-r\fR RANK
+Minimum/starting rank
+
+.TP
+\fB\-\-maxrank\fR RANK, \fB\-R\fR RANK
+Maximum/finishing rank
+
+.SH OPTIONS 'nominatim refresh'
+usage: nominatim refresh [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                         [--postcodes] [--word-counts] [--address-levels]
+                         [--functions] [--wiki-data] [--importance]
+                         [--website] [--no-diff-updates]
+                         [--enable-debug-statements]
+
+    Recompute auxiliary data used by the indexing process.
+
+    These functions must not be run in parallel with other update commands.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-postcodes\fR
+Update postcode centroid table
+
+.TP
+\fB\-\-word\-counts\fR
+Compute frequency of full\-word search terms
+
+.TP
+\fB\-\-address\-levels\fR
+Reimport address level configuration
+
+.TP
+\fB\-\-functions\fR
+Update the PL/pgSQL functions in the database
+
+.TP
+\fB\-\-wiki\-data\fR
+Update Wikipedia/data importance numbers.
+
+.TP
+\fB\-\-importance\fR
+Recompute place importances (expensive!)
+
+.TP
+\fB\-\-website\fR
+Refresh the directory that serves the scripts for the web API
+
+.TP
+\fB\-\-no\-diff\-updates\fR
+Do not enable code for propagating updates
+
+.TP
+\fB\-\-enable\-debug\-statements\fR
+Enable debug warning statements in functions
+
+.SH OPTIONS 'nominatim admin'
+usage: nominatim admin [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                       (--warm | --check-database | --migrate | --analyse-indexing)
+                       [--search-only] [--reverse-only]
+                       [--osm-id OSM_ID | --place-id PLACE_ID]
+
+    Analyse and maintain the database.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-warm\fR
+Warm database caches for search and reverse queries.
+
+.TP
+\fB\-\-check\-database\fR
+Check that the database is complete and operational.
+
+.TP
+\fB\-\-migrate\fR
+Migrate the database to a new software version.
+
+.TP
+\fB\-\-analyse\-indexing\fR
+Print performance analysis of the indexing process.
+
+.TP
+\fB\-\-search\-only\fR
+Only pre\-warm tables for search queries
+
+.TP
+\fB\-\-reverse\-only\fR
+Only pre\-warm tables for reverse queries
+
+.TP
+\fB\-\-osm\-id\fR \fI\,OSM_ID\/\fR
+Analyse indexing of the given OSM object
+
+.TP
+\fB\-\-place\-id\fR \fI\,PLACE_ID\/\fR
+Analyse indexing of the given Nominatim object
+
+.SH OPTIONS 'nominatim export'
+usage: nominatim export [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                        [--output-type {continent,country,state,county,city,suburb,street,path}]
+                        [--output-format OUTPUT_FORMAT]
+                        [--output-all-postcodes] [--language LANGUAGE]
+                        [--restrict-to-country COUNTRY_CODE]
+                        [--restrict-to-osm-node ID] [--restrict-to-osm-way ID]
+                        [--restrict-to-osm-relation ID]
+
+    Export addresses as CSV file from the database.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-output\-type\fR {continent,country,state,county,city,suburb,street,path}
+Type of places to output (default: street)
+
+.TP
+\fB\-\-output\-format\fR \fI\,OUTPUT_FORMAT\/\fR
+Semicolon\-separated list of address types (see \-\-output\-type). Multiple ranks can be merged into one column by simply using a comma\-separated list.
+
+.TP
+\fB\-\-output\-all\-postcodes\fR
+List all postcodes for address instead of just the most likely one
+
+.TP
+\fB\-\-language\fR \fI\,LANGUAGE\/\fR
+Preferred language for output (use local name, if omitted)
+
+.TP
+\fB\-\-restrict\-to\-country\fR COUNTRY_CODE
+Export only objects within country
+
+.TP
+\fB\-\-restrict\-to\-osm\-node\fR ID
+Export only children of this OSM node
+
+.TP
+\fB\-\-restrict\-to\-osm\-way\fR ID
+Export only children of this OSM way
+
+.TP
+\fB\-\-restrict\-to\-osm\-relation\fR ID
+Export only children of this OSM relation
+
+.SH OPTIONS 'nominatim serve'
+usage: nominatim serve [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                       [--server SERVER]
+
+    Start a simple web server for serving the API.
+
+    This command starts the built\-in PHP webserver to serve the website
+    from the current project directory. This webserver is only suitable
+    for testing and develop. Do not use it in production setups!
+
+    By the default, the webserver can be accessed at: http://127.0.0.1:8088
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-server\fR \fI\,SERVER\/\fR
+The address the server will listen to.
+
+.SH OPTIONS 'nominatim search'
+usage: nominatim search [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                        [--query QUERY] [--street STREET] [--city CITY]
+                        [--county COUNTY] [--state STATE] [--country COUNTRY]
+                        [--postalcode POSTALCODE]
+                        [--format {xml,json,jsonv2,geojson,geocodejson}]
+                        [--addressdetails] [--extratags] [--namedetails]
+                        [--lang LANGS]
+                        [--polygon-output {geojson,kml,svg,text}]
+                        [--polygon-threshold TOLERANCE] [--countrycodes CC,..]
+                        [--exclude_place_ids ID,..] [--limit LIMIT]
+                        [--viewbox X1,Y1,X2,Y2] [--bounded] [--no-dedupe]
+
+    Execute API search query.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-query\fR \fI\,QUERY\/\fR
+Free\-form query string
+
+.TP
+\fB\-\-street\fR \fI\,STREET\/\fR
+Structured query: housenumber and street
+
+.TP
+\fB\-\-city\fR \fI\,CITY\/\fR
+Structured query: city, town or village
+
+.TP
+\fB\-\-county\fR \fI\,COUNTY\/\fR
+Structured query: county
+
+.TP
+\fB\-\-state\fR \fI\,STATE\/\fR
+Structured query: state
+
+.TP
+\fB\-\-country\fR \fI\,COUNTRY\/\fR
+Structured query: country
+
+.TP
+\fB\-\-postalcode\fR \fI\,POSTALCODE\/\fR
+Structured query: postcode
+
+.TP
+\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+Format of result
+
+.TP
+\fB\-\-addressdetails\fR
+Include a breakdown of the address into elements.
+
+.TP
+\fB\-\-extratags\fR
+Include additional information if available (e.g. wikipedia link, opening hours).
+
+.TP
+\fB\-\-namedetails\fR
+Include a list of alternative names.
+
+.TP
+\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS
+Preferred language order for presenting search results
+
+.TP
+\fB\-\-polygon\-output\fR {geojson,kml,svg,text}
+Output geometry of results as a GeoJSON, KML, SVG or WKT.
+
+.TP
+\fB\-\-polygon\-threshold\fR TOLERANCE
+Simplify output geometry.Parameter is difference tolerance in degrees.
+
+.TP
+\fB\-\-countrycodes\fR CC,..
+Limit search results to one or more countries.
+
+.TP
+\fB\-\-exclude_place_ids\fR ID,..
+List of search object to be excluded
+
+.TP
+\fB\-\-limit\fR \fI\,LIMIT\/\fR
+Limit the number of returned results
+
+.TP
+\fB\-\-viewbox\fR X1,Y1,X2,Y2
+Preferred area to find search results
+
+.TP
+\fB\-\-bounded\fR
+Strictly restrict results to viewbox area
+
+.TP
+\fB\-\-no\-dedupe\fR
+Do not remove duplicates from the result list
+
+.SH OPTIONS 'nominatim reverse'
+usage: nominatim reverse [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --lat LAT
+                         --lon LON [--zoom ZOOM]
+                         [--format {xml,json,jsonv2,geojson,geocodejson}]
+                         [--addressdetails] [--extratags] [--namedetails]
+                         [--lang LANGS]
+                         [--polygon-output {geojson,kml,svg,text}]
+                         [--polygon-threshold TOLERANCE]
+
+    Execute API reverse query.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-lat\fR \fI\,LAT\/\fR
+Latitude of coordinate to look up (in WGS84)
+
+.TP
+\fB\-\-lon\fR \fI\,LON\/\fR
+Longitude of coordinate to look up (in WGS84)
+
+.TP
+\fB\-\-zoom\fR \fI\,ZOOM\/\fR
+Level of detail required for the address
+
+.TP
+\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+Format of result
+
+.TP
+\fB\-\-addressdetails\fR
+Include a breakdown of the address into elements.
+
+.TP
+\fB\-\-extratags\fR
+Include additional information if available (e.g. wikipedia link, opening hours).
+
+.TP
+\fB\-\-namedetails\fR
+Include a list of alternative names.
+
+.TP
+\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS
+Preferred language order for presenting search results
+
+.TP
+\fB\-\-polygon\-output\fR {geojson,kml,svg,text}
+Output geometry of results as a GeoJSON, KML, SVG or WKT.
+
+.TP
+\fB\-\-polygon\-threshold\fR TOLERANCE
+Simplify output geometry.Parameter is difference tolerance in degrees.
+
+.SH OPTIONS 'nominatim lookup'
+usage: nominatim lookup [-h] [-q] [-v] [--project-dir DIR] [-j NUM] --id OSMID
+                        [--format {xml,json,jsonv2,geojson,geocodejson}]
+                        [--addressdetails] [--extratags] [--namedetails]
+                        [--lang LANGS]
+                        [--polygon-output {geojson,kml,svg,text}]
+                        [--polygon-threshold TOLERANCE]
+
+    Execute API lookup query.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-id\fR OSMID
+OSM id to lookup in format <NRW><id> (may be repeated)
+
+.TP
+\fB\-\-format\fR {xml,json,jsonv2,geojson,geocodejson}
+Format of result
+
+.TP
+\fB\-\-addressdetails\fR
+Include a breakdown of the address into elements.
+
+.TP
+\fB\-\-extratags\fR
+Include additional information if available (e.g. wikipedia link, opening hours).
+
+.TP
+\fB\-\-namedetails\fR
+Include a list of alternative names.
+
+.TP
+\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS
+Preferred language order for presenting search results
+
+.TP
+\fB\-\-polygon\-output\fR {geojson,kml,svg,text}
+Output geometry of results as a GeoJSON, KML, SVG or WKT.
+
+.TP
+\fB\-\-polygon\-threshold\fR TOLERANCE
+Simplify output geometry.Parameter is difference tolerance in degrees.
+
+.SH OPTIONS 'nominatim details'
+usage: nominatim details [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                         (--node NODE | --way WAY | --relation RELATION | --place_id PLACE_ID)
+                         [--class OBJECT_CLASS] [--addressdetails]
+                         [--keywords] [--linkedplaces] [--hierarchy]
+                         [--group_hierarchy] [--polygon_geojson]
+                         [--lang LANGS]
+
+    Execute API details query.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-node\fR \fI\,NODE\/\fR, \fB\-n\fR \fI\,NODE\/\fR
+Look up the OSM node with the given ID.
+
+.TP
+\fB\-\-way\fR \fI\,WAY\/\fR, \fB\-w\fR \fI\,WAY\/\fR
+Look up the OSM way with the given ID.
+
+.TP
+\fB\-\-relation\fR \fI\,RELATION\/\fR, \fB\-r\fR \fI\,RELATION\/\fR
+Look up the OSM relation with the given ID.
+
+.TP
+\fB\-\-place_id\fR \fI\,PLACE_ID\/\fR, \fB\-p\fR \fI\,PLACE_ID\/\fR
+Database internal identifier of the OSM object to look up.
+
+.TP
+\fB\-\-class\fR \fI\,OBJECT_CLASS\/\fR
+Class type to disambiguated multiple entries of the same object.
+
+.TP
+\fB\-\-addressdetails\fR
+Include a breakdown of the address into elements.
+
+.TP
+\fB\-\-keywords\fR
+Include a list of name keywords and address keywords.
+
+.TP
+\fB\-\-linkedplaces\fR
+Include a details of places that are linked with this one.
+
+.TP
+\fB\-\-hierarchy\fR
+Include details of places lower in the address hierarchy.
+
+.TP
+\fB\-\-group_hierarchy\fR
+Group the places by type.
+
+.TP
+\fB\-\-polygon_geojson\fR
+Include geometry of result.
+
+.TP
+\fB\-\-lang\fR LANGS, \fB\-\-accept\-language\fR LANGS
+Preferred language order for presenting search results
+
+.SH OPTIONS 'nominatim status'
+usage: nominatim status [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                        [--format {text,json}]
+
+    Execute API status query.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-format\fR {text,json}
+Format of result
+
+.SH OPTIONS 'nominatim transition'
+usage: nominatim transition [-h] [-q] [-v] [--project-dir DIR] [-j NUM]
+                            [--create-db] [--setup-db] [--import-data]
+                            [--load-data] [--create-tables]
+                            [--create-partition-tables] [--index]
+                            [--create-search-indices] [--create-country-names]
+                            [--no-partitions] [--osm-file FILE] [--drop]
+                            [--osm2pgsql-cache SIZE] [--no-analyse]
+                            [--ignore-errors] [--reverse-only]
+                            [--tiger-data FILE]
+
+    Internal functions for code transition. Do not use.
+    
+
+
+
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Print only error messages
+
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase verboseness of output
+
+.TP
+\fB\-\-project\-dir\fR DIR
+Base directory of the Nominatim installation (default:.)
+
+.TP
+\fB\-j\fR NUM, \fB\-\-threads\fR NUM
+Number of parallel threads to use
+
+.TP
+\fB\-\-create\-db\fR
+Create nominatim db
+
+.TP
+\fB\-\-setup\-db\fR
+Build a blank nominatim db
+
+.TP
+\fB\-\-import\-data\fR
+Import a osm file
+
+.TP
+\fB\-\-load\-data\fR
+Copy data to live tables from import table
+
+.TP
+\fB\-\-create\-tables\fR
+Create main tables
+
+.TP
+\fB\-\-create\-partition\-tables\fR
+Create required partition tables
+
+.TP
+\fB\-\-index\fR
+Index the data
+
+.TP
+\fB\-\-create\-search\-indices\fR
+Create additional indices required for search and update
+
+.TP
+\fB\-\-create\-country\-names\fR
+Create search index for default country names.
+
+.TP
+\fB\-\-no\-partitions\fR
+Do not partition search indices
+
+.TP
+\fB\-\-osm\-file\fR FILE
+File to import
+
+.TP
+\fB\-\-drop\fR
+Drop tables needed for updates, making the database readonly
+
+.TP
+\fB\-\-osm2pgsql\-cache\fR SIZE
+Size of cache to be used by osm2pgsql (in MB)
+
+.TP
+\fB\-\-no\-analyse\fR
+Do not perform analyse operations during index
+
+.TP
+\fB\-\-ignore\-errors\fR
+Ignore certain erros on import.
+
+.TP
+\fB\-\-reverse\-only\fR
+Do not create search tables and indexes
+
+.TP
+\fB\-\-tiger\-data\fR FILE
+File to import
+
+.SH DISTRIBUTION
+The latest version of Nominatim may be downloaded from
+.UR https://nominatim.org
+.UE

diff --git a/nominatim/cli.py b/nominatim/cli.py
index 0876d9a44df960e9589ca8577521e58d9d56cc50..e162d1a65e23a280d11719375a42b93fd421a05e 100644 (file)
--- a/nominatim/cli.py
+++ b/nominatim/cli.py
@@ -179,16 +179,16 @@ class QueryExport:
                            help='Type of places to output (default: street)')
         group.add_argument('--output-format',
                            default='street;suburb;city;county;state;country',
-                           help="""Semicolon-separated list of address types
-                                   (see --output-type). Multiple ranks can be
-                                   merged into one column by simply using a
-                                   comma-separated list.""")
+                           help=("Semicolon-separated list of address types "
+                                 "(see --output-type). Multiple ranks can be "
+                                 "merged into one column by simply using a "
+                                 "comma-separated list."))
         group.add_argument('--output-all-postcodes', action='store_true',
-                           help="""List all postcodes for address instead of
-                                   just the most likely one""")
+                           help=("List all postcodes for address instead of "
+                                 "just the most likely one"))
         group.add_argument('--language',
-                           help="""Preferred language for output
-                                   (use local name, if omitted)""")
+                           help=("Preferred language for output "
+                                 "(use local name, if omitted)"))
         group = parser.add_argument_group('Filter arguments')
         group.add_argument('--restrict-to-country', metavar='COUNTRY_CODE',
                            help='Export only objects within country')
@@ -242,11 +242,10 @@ class AdminServe:
     def run(args):
         run_php_server(args.server, args.project_dir / 'website')
 
-
-def nominatim(**kwargs):
+def get_set_parser(**kwargs):
     """\
-    Command-line tools for importing, updating, administrating and
-    querying the Nominatim database.
+    Initializes the parser and adds various subcommands for
+    nominatim cli.
     """
     parser = CommandlineParser('nominatim', nominatim.__doc__)
 
@@ -276,4 +275,14 @@ def nominatim(**kwargs):
 
     parser.add_subcommand('transition', clicmd.AdminTransition)
 
+    return parser
+
+
+def nominatim(**kwargs):
+    """\
+    Command-line tools for importing, updating, administrating and
+    querying the Nominatim database.
+    """
+    parser = get_set_parser(**kwargs)
+
     return parser.run(**kwargs)

diff --git a/nominatim/clicmd/api.py b/nominatim/clicmd/api.py
index 7185d97c14bf659f406e56d6c1b10e916467a278..c3e869b8aa60441af9b62c7f074f66a885e14ed9 100644 (file)
--- a/nominatim/clicmd/api.py
+++ b/nominatim/clicmd/api.py
@@ -21,8 +21,8 @@ STRUCTURED_QUERY = (
 
 EXTRADATA_PARAMS = (
     ('addressdetails', 'Include a breakdown of the address into elements.'),
-    ('extratags', """Include additional information if available
-                     (e.g. wikipedia link, opening hours)."""),
+    ('extratags', ("Include additional information if available "
+                   "(e.g. wikipedia link, opening hours).")),
     ('namedetails', 'Include a list of alternative names.')
 )
 
@@ -49,8 +49,8 @@ def _add_api_output_arguments(parser):
                        choices=['geojson', 'kml', 'svg', 'text'],
                        help='Output geometry of results as a GeoJSON, KML, SVG or WKT.')
     group.add_argument('--polygon-threshold', type=float, metavar='TOLERANCE',
-                       help="""Simplify output geometry.
-                               Parameter is difference tolerance in degrees.""")
+                       help=("Simplify output geometry."
+                             "Parameter is difference tolerance in degrees."))
 
 
 class APISearch:
@@ -205,8 +205,8 @@ class APIDetails:
         objs.add_argument('--place_id', '-p', type=int,
                           help='Database internal identifier of the OSM object to look up.')
         group.add_argument('--class', dest='object_class',
-                           help="""Class type to disambiguated multiple entries
-                                   of the same object.""")
+                           help=("Class type to disambiguated multiple entries "
+                                 "of the same object."))
 
         group = parser.add_argument_group('Output arguments')
         for name, desc in DETAILS_SWITCHES:

diff --git a/nominatim/clicmd/replication.py b/nominatim/clicmd/replication.py
index fc18945ec854469ac2421117bdc0aea493462c29..f9c5561a5c53edd099bb0855e9a58562335e3514 100644 (file)
--- a/nominatim/clicmd/replication.py
+++ b/nominatim/clicmd/replication.py
@@ -29,17 +29,17 @@ class UpdateReplication:
                            help='Initialise the update process')
         group.add_argument('--no-update-functions', dest='update_functions',
                            action='store_false',
-                           help="""Do not update the trigger function to
-                                   support differential updates.""")
+                           help=("Do not update the trigger function to "
+                                 "support differential updates."))
         group = parser.add_argument_group('Arguments for updates')
         group.add_argument('--check-for-updates', action='store_true',
                            help='Check if new updates are available and exit')
         group.add_argument('--once', action='store_true',
-                           help="""Download and apply updates only once. When
-                                   not set, updates are continuously applied""")
+                           help=("Download and apply updates only once. When "
+                                 "not set, updates are continuously applied"))
         group.add_argument('--no-index', action='store_false', dest='do_index',
-                           help="""Do not index the new data. Only applicable
-                                   together with --once""")
+                           help=("Do not index the new data. Only applicable "
+                                 "together with --once"))
         group.add_argument('--osm2pgsql-cache', metavar='SIZE', type=int,
                            help='Size of cache to be used by osm2pgsql (in MB)')
         group = parser.add_argument_group('Download parameters')

diff --git a/nominatim/clicmd/setup.py b/nominatim/clicmd/setup.py
index 056643aabfbbcd459bd874a307f0a41029fe8750..92d0694359e62ab48a58a255143b4733dfd316f6 100644 (file)
--- a/nominatim/clicmd/setup.py
+++ b/nominatim/clicmd/setup.py
@@ -39,11 +39,11 @@ class SetupAll:
         group.add_argument('--reverse-only', action='store_true',
                            help='Do not create tables and indexes for searching')
         group.add_argument('--no-partitions', action='store_true',
-                           help="""Do not partition search indices
-                                   (speeds up import of single country extracts)""")
+                           help=("Do not partition search indices "
+                                 "(speeds up import of single country extracts)"))
         group.add_argument('--no-updates', action='store_true',
-                           help="""Do not keep tables that are only needed for
-                                   updating the database later""")
+                           help="Do not keep tables that are only needed for "
+                                "updating the database later")
         group = parser.add_argument_group('Expert options')
         group.add_argument('--ignore-errors', action='store_true',
                            help='Continue import even when errors in SQL are present')

diff --git a/test/python/test_tools_import_special_phrases.py b/test/python/test_tools_import_special_phrases.py
index 7a8b832d6b2e84ac3e9ba4838062a34a6c3fae67..b77ae10dc1233f0ede3a3535a2924a22b89251db 100644 (file)
--- a/test/python/test_tools_import_special_phrases.py
+++ b/test/python/test_tools_import_special_phrases.py
@@ -17,16 +17,14 @@ def test_check_sanity_class(special_phrases_importer):
         If a wrong class or type is given, an UsageError should raise.
         If a good class and type are given, nothing special happens.
     """
-    with pytest.raises(UsageError) as wrong_class:
+    with pytest.raises(UsageError):
         special_phrases_importer._check_sanity('en', '', 'type')
     
-    with pytest.raises(UsageError) as wrong_type:
+    with pytest.raises(UsageError):
         special_phrases_importer._check_sanity('en', 'class', '')
 
     special_phrases_importer._check_sanity('en', 'class', 'type')
 
-    assert wrong_class and wrong_type
-
 def test_load_white_and_black_lists(special_phrases_importer):
     """
         Test that _load_white_and_black_lists() well return
@@ -55,12 +53,9 @@ def test_convert_settings_wrong_file(special_phrases_importer):
         Test that _convert_php_settings_if_needed() raise an exception
         if the given file is not a valid file.
     """
-
-    with pytest.raises(UsageError) as exceptioninfos:
+    with pytest.raises(UsageError, match='random_file is not a valid file.'):
         special_phrases_importer._convert_php_settings_if_needed('random_file')
 
-    assert str(exceptioninfos.value) == 'random_file is not a valid file.'
-
 def test_convert_settings_json_already_exist(special_phrases_importer):
     """
         Test that if we give to '_convert_php_settings_if_needed' a php file path
@@ -78,7 +73,7 @@ def test_convert_settings_giving_json(special_phrases_importer):
         Test that if we give to '_convert_php_settings_if_needed' a json file path
         the same path is directly returned
     """
-    json_file = (TEST_BASE_DIR / 'testfiles' / 'phrase-settings.json').resolve()
+    json_file = (TEST_BASE_DIR / 'testfiles' / 'phrase_settings.json').resolve()
     
     returned = special_phrases_importer._convert_php_settings_if_needed(json_file)
 

diff --git a/test/testfiles/phrase-settings.json b/test/testfiles/phrase_settings.json
similarity index 100%
rename from test/testfiles/phrase-settings.json
rename to test/testfiles/phrase_settings.json

diff --git a/vagrant/Install-on-Centos-7.sh b/vagrant/Install-on-Centos-7.sh
index 610bbb04fc2c2c86e5a262cca3a5074e27776206..fae961f1795afd94aac6b7348ff660a4d368e07e 100755 (executable)
--- a/vagrant/Install-on-Centos-7.sh
+++ b/vagrant/Install-on-Centos-7.sh
@@ -42,7 +42,7 @@
                         python3-pip python3-setuptools python3-devel \
                         expat-devel zlib-devel libicu-dev
 
-    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU
+    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage
 
 
 #

diff --git a/vagrant/Install-on-Centos-8.sh b/vagrant/Install-on-Centos-8.sh
index 17d07aec70e5729c07e10b30b935e35b695c6659..ac3a1b6087f08b09cc4877675a327a3071bb4dca 100755 (executable)
--- a/vagrant/Install-on-Centos-8.sh
+++ b/vagrant/Install-on-Centos-8.sh
@@ -35,7 +35,7 @@
                         python3-pip python3-setuptools python3-devel \
                         expat-devel zlib-devel libicu-dev
 
-    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU
+    pip3 install --user psycopg2 python-dotenv psutil Jinja2 PyICU argparse-manpage
 
 
 #

diff --git a/vagrant/Install-on-Ubuntu-18.sh b/vagrant/Install-on-Ubuntu-18.sh
index b90da87195de0509845926688baa4b69c37e92ba..9fda122ee8f969ada75738321053aee0f70d2118 100755 (executable)
--- a/vagrant/Install-on-Ubuntu-18.sh
+++ b/vagrant/Install-on-Ubuntu-18.sh
@@ -30,7 +30,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                         postgresql-server-dev-10 postgresql-10-postgis-2.4 \
                         postgresql-contrib-10 postgresql-10-postgis-scripts \
                         php php-pgsql php-intl libicu-dev python3-pip \
-                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git
+                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \
+                        python3-argparse-manpage
 
 # The python-dotenv package that comes with Ubuntu 18.04 is too old, so
 # install the latest version from pip:

diff --git a/vagrant/Install-on-Ubuntu-20.sh b/vagrant/Install-on-Ubuntu-20.sh
index d04f5796180a19efef59ae84a75b2b20cb23b321..292947d179ec91ecd12a265e852c98be5711a215 100755 (executable)
--- a/vagrant/Install-on-Ubuntu-20.sh
+++ b/vagrant/Install-on-Ubuntu-20.sh
@@ -33,7 +33,8 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                         postgresql-server-dev-12 postgresql-12-postgis-3 \
                         postgresql-contrib-12 postgresql-12-postgis-3-scripts \
                         php php-pgsql php-intl libicu-dev python3-dotenv \
-                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git
+                        python3-psycopg2 python3-psutil python3-jinja2 python3-icu git \
+                        python3-argparse-manpage
 
 #
 # System Configuration