adapt packaging readmes

packaging/nominatim-api/README.md

@@ -1,21 +1,38 @@
-Nominatim - frontend library
+# Nominatim - Frontend Library
-=========
 
 Nominatim is a tool to search OpenStreetMap data
 by name and address (geocoding) and to generate synthetic addresses of
 OSM points (reverse geocoding).
 
 This module implements the library for searching in a Nominatim database
-imported with the `nominatim-db` package.
+imported with the 'nominatim-db' package.
 
-Documentation
+## Installation
-=============
 
-The documentation of the latest development version is in the
+To install the Nominatim API from pypi, run:
-`docs/` subdirectory. A HTML version can be found at
-https://nominatim.org/release-docs/develop/ .
 
-License
+    pip install nominatim-api
-=======
+
+## Running a Nominatim server
+
+You need falcon or starlette to run Nominatim as a service, as well as
+an ASGI-capable server like uvicorn. To install them from pypi run:
+
+    pip install falcon uvicorn
+
+You need to have a Nominatim database imported with the 'nominatim-db'
+package. Go to the project directory, then run uvicorn as:
+
+    uvicorn --factory nominatim.server.falcon.server:run_wsgi
+
+## Documentation
+
+The full documentation for the Nominatim library can be found at:
+https://nominatim.org/release-docs/develop/library/Getting-Started/
+
+The v1 API of the server is documented at:
+https://nominatim.org/release-docs/develop/api/Overview/
+
+## License
 
 The source code is available under a GPLv3 license.

packaging/nominatim-core/README.md

@@ -6,7 +6,7 @@ by name and address (geocoding) and to generate synthetic addresses of
 OSM points (reverse geocoding).
 
 This is the core pacakage containing resources and code shared by
-Nominatim's frontend `nominatim_api` and backend `nominatim_db`. You
+Nominatim's frontend `nominatim-api` and backend `nominatim-db`. You
 usually don't want to install this package directly.
 
 Documentation
@@ -19,4 +19,6 @@ https://nominatim.org/release-docs/develop/ .
 License
 =======
 
-The source code is available under a GPLv2 license.
+The Python source code is available under a GPL license version 3 or later.
+The Lua configuration files for osm2pgsql are released under the
+Apache License, Version 2.0. All other files are under a GPLv2 license.

packaging/nominatim-db/README.md

@@ -1,5 +1,4 @@
-Nominatim - DB Backend
+# Nominatim - DB Backend
-=========
 
 Nominatim is a tool to search OpenStreetMap data
 by name and address (geocoding) and to generate synthetic addresses of
@@ -8,14 +7,45 @@ OSM points (reverse geocoding).
 This module implements the database backend for Nominatim and the
 command-line tool for importing and maintaining the database.
 
-Documentation
+## Installation
-=============
+
+### Prerequisites
+
+Nominatim requires [osm2pgsql](https://osm2pgsql.org/) (>=1.8) for reading
+OSM data and [PostgreSQL](https://www.postgresql.org/) to store the data.
+
+On Ubuntu (>=23.04) and Debian (using backports), you can install them with:
+
+    sudo apt-get install osm2pgsql postgresql-postgis
+
+### Installation from pypi
+
+To install Nominatim from pypi, run:
+
+    pip install nominatim-db
+
+
+## Quick start
+
+First create a project directory for your new Nominatim database, which
+is the space for additional configuration and customization:
+
+    mkdir planet-project
+
+Download an appropriate data extract, for example from
+[Geofabrik](https://download.geofabrik.de/) and import the file:
+
+    nominatim import --osm-file <downlaoded-osm-data.pbf>
+
+You will need to install the 'nominatim-api' package to query the
+database.
+
+## Documentation
 
 The documentation of the latest development version is in the
 `docs/` subdirectory. A HTML version can be found at
 https://nominatim.org/release-docs/develop/ .
 
-License
+## License
-=======
 
 The source code is available under a GPLv3 license.