From 81d39e0c4ebf66d0a27103d392b115c993650aef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=C3=A1t=C3=A9=20Gy=C3=B6ngy=C3=B6si?=
 <gyongyosimate1@gmail.com>
Date: Thu, 7 Nov 2024 14:32:25 +0100
Subject: [PATCH] Improve install instructions: package name, commands, links &
 formatting (#5040)

* Add command for installing Python libs per PEP 668; correct `yaml` package name

* Update INSTALL.md

* Update INSTALL.md
---
 INSTALL.md | 63 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 40 insertions(+), 23 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md
index 7673bd585..dbc9997a7 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -80,31 +80,48 @@ scripts/get-fonts.sh
 
 ## Dependencies
 
-For development, a style design studio is needed.
-* [Kosmtik](https://github.com/kosmtik/kosmtik) - Kosmtik can be launched with `node index.js serve path/to/openstreetmap-carto/project.mml`
-	* The 0.0.17 release of Kosmtik is not enough because we need up-to-date CartoCSS and Mapnik versions. To install the current master branch of Kosmtik, you can clone the Kosmtik repository and execute `npm install` within it.
-* [TileMill](https://tilemill-project.github.io/tilemill/) is not officially supported, but you may be able to use a recent TileMill version by copying or symlinking the project directly into your Mapbox/project directory.
-
 To display *any* map, a database containing OpenStreetMap data and some utilities are required:
-
 * [PostgreSQL](https://www.postgresql.org/)
 * [PostGIS](https://postgis.net/)
-* [osm2pgsql](https://github.com/openstreetmap/osm2pgsql#installing) (>= 1.8.0) to [import your data](https://switch2osm.org/serving-tiles/updating-as-people-edit/) into a PostGIS database
-* Python 3 with the psycopg2, yaml, and requests libraries (`python3-psycopg2`, `python3-yaml`, `python3-requests` packages on Debian-derived systems)
-* `ogr2ogr` for loading shapefiles into the database (`gdal-bin` on Debian-derived systems)
-
-### Optional development dependencies
-
-Some colours, SVGs and other files are generated with helper scripts. Not all users will need these dependencies
-
-* Python and Ruby to run helper scripts
-* [Color Math](https://github.com/gtaylor/python-colormath) and [numpy](https://numpy.org/) (if running) feature a  `generate_road_colors.py` helper script, which may be obtained with `pip install colormath numpy`)
-
-### Additional deployment dependencies
-
-For deployment, CartoCSS and Mapnik are required.
-
-* [CartoCSS](https://github.com/mapbox/carto) >= 1.2.0 *(we're using YAML)*
-* [Mapnik](https://github.com/mapnik/mapnik/wiki/Mapnik-Installation) >= 3.0.22
+* [`osm2pgsql`](https://github.com/openstreetmap/osm2pgsql#installing)>=`1.8.0` to [import your data](https://switch2osm.org/serving-tiles/updating-as-people-edit-osm2pgsql-replication/) into a PostGIS database
+* [Python 3](https://www.python.org/downloads/) with the `psycopg2`, `pyyaml`, and `requests` libraries (`python3-psycopg2`, `python3-pyyaml`, `python3-requests` packages on Debian-derived systems)
+  ```bash
+  python3 -m pip install --break-system-packages --user pyyaml requests psycopg2
+  ```
+* [`ogr2ogr`](https://gdal.org/en/latest/download.html) for loading shapefiles into the database (`gdal-bin` on Debian-derived systems)
+
+### For development (style design studio)
+
+* [Kosmtik](https://github.com/kosmtik/kosmtik)
+  * Install it:
+      ```bash
+      git clone https://github.com/kosmtik/kosmtik
+      cd kosmtik
+      npm install
+      ```
+    * _The 0.0.17 release of Kosmtik wouldn't be enough because we need up-to-date CartoCSS and Mapnik versions._
+  * Launch it:
+      ```bash
+      node index.js serve path/to/openstreetmap-carto/project.mml
+      ```
+* [TileMill](https://tilemill-project.github.io/tilemill/)
+  * Not officially supported, but you may be able to use a recent TileMill version by copying or symlinking the project directly into your Mapbox/project directory.
+
+#### Optional
+
+Some colours, SVGs and other files are generated with helper scripts. Not all users will need these dependencies.
+
+* [Python](https://www.python.org/downloads/)
+* [`generate_road_colors.py`](./scripts/generate_road_colors.py) and [`generate_unpaved_patterns.py`](./scripts/generate_unpaved_patterns.py) depend on [Color Math](https://github.com/gtaylor/python-colormath) and [`numpy`](https://numpy.org/). To install these, run:
+    ```bash
+    python3 -m pip install --break-system-packages --user colormath numpy
+    ```
+
+### For deployment
+
+CartoCSS and Mapnik are required for deployment.
+
+* [CartoCSS](https://github.com/mapbox/carto) >= `1.2.0` *(we're using YAML)*
+* [Mapnik](https://github.com/mapnik/mapnik/wiki/Mapnik-Installation) >= `3.0.22`
 
 With CartoCSS, these sources are compiled into a Mapnik compatible XML file. When running CartoCSS, specify the Mapnik API version you are using (at least 3.0.22: `carto -a "3.0.22"`).