Merge pull request #1346 from joto/docs

Various cleanups in man page and README

Author: lonvia

README.md

@@ -1,16 +1,19 @@
-# osm2pgsql #
+# osm2pgsql
 
 https://osm2pgsql.org
 
 osm2pgsql is a tool for loading OpenStreetMap data into a PostgreSQL / PostGIS
 database suitable for applications like rendering into a map, geocoding with
 Nominatim, or general analysis.
 
+See the [documentation](https://osm2pgsql.org/doc/) for instructions on how
+to install and run osm2pgsql.
+
 [![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/7abwls7hfmb83axj/branch/master?svg=true)](https://ci.appveyor.com/project/openstreetmap/osm2pgsql/branch/master)
 [![Github Actions Build Status](https://github.com/openstreetmap/osm2pgsql/workflows/CI/badge.svg?branch=master)](https://github.com/openstreetmap/osm2pgsql/actions)
 [![Packaging Status](https://repology.org/badge/tiny-repos/osm2pgsql.svg)](https://repology.org/project/osm2pgsql/versions)
 
-## Features ##
+## Features
 
 * Converts OSM files to a PostgreSQL DB
 * Conversion of tags to columns is configurable in the style file
@@ -22,24 +25,24 @@ Nominatim, or general analysis.
 * Support for hstore field type to store the complete set of tags in one database
   field if desired
 
-## Installing ##
+## Installing
 
 Most Linux distributions include osm2pgsql. It is also available on macOS with [Homebrew](https://brew.sh/).
 
 Unoffical builds for Windows are available from [AppVeyor](https://ci.appveyor.com/project/openstreetmap/osm2pgsql/history) but you need to find the right build artifacts.
 Builds for releases may also be downloaded from the [OpenStreetMap Dev server](https://lonvia.dev.openstreetmap.org/osm2pgsql-winbuild/releases/).
 
-## Building ##
+## Building
 
 The latest source code is available in the osm2pgsql git repository on GitHub
 and can be downloaded as follows:
 
 ```sh
-$ git clone git://github.com/openstreetmap/osm2pgsql.git
+git clone git://github.com/openstreetmap/osm2pgsql.git
 ```
 
 Osm2pgsql uses the cross-platform [CMake build system](https://cmake.org/)
-to configure and build itself and requires
+to configure and build itself.
 
 Required libraries are
 
@@ -97,7 +100,8 @@ pkg install devel/cmake devel/boost-libs textproc/expat2 \
   databases/postgresql94-client graphics/proj lang/lua52
 ```
 
-Once dependencies are installed, use CMake to build the Makefiles in a separate folder
+Once dependencies are installed, use CMake to build the Makefiles in a separate
+folder:
 
 ```sh
 mkdir build && cd build
@@ -114,76 +118,27 @@ When the Makefiles have been successfully built, compile with
 make
 ```
 
-The compiled files can be installed with
-
-```sh
-sudo make install
-```
-
-By default, the Release build with debug info is created and no tests are compiled.
-You can change that behavior by using additional options like following:
-
-```sh
-cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
-```
-
-## Usage ##
-
-This is only a short introduction. There is extensive documentation available
-on [osm2pgsq.org](https://osm2pgsql.org/doc/).
-
-Osm2pgsql has one program, the executable itself, which has a lot of command
-line options.
-
-Before loading into a database, the database must be created and the PostGIS
-and optional hstore extensions must be loaded. A full guide to PostgreSQL
-setup is beyond the scope of this readme, but with reasonably recent versions
-of PostgreSQL and PostGIS this can be done with
+The man page can be rebuilt with:
 
 ```sh
-createdb gis
-psql -d gis -c 'CREATE EXTENSION postgis; CREATE EXTENSION hstore;'
+make man
 ```
 
-A basic invocation to load the data into the database `gis` for rendering would be
+The compiled files can be installed with
 
 ```sh
-osm2pgsql --create --database gis data.osm.pbf
+sudo make install
 ```
 
-This will load the data from `data.osm.pbf` into the `planet_osm_point`,
-`planet_osm_line`, `planet_osm_roads`, and `planet_osm_polygon` tables.
-
-When importing a large amount of data such as the complete planet, a typical
-command line would be
+By default, the Release build with debug info is created and no tests are
+compiled. You can change that behavior by using additional options like
+following:
 
 ```sh
-osm2pgsql -c -d gis --slim -C <cache size> \
-  --flat-nodes <flat nodes> planet-latest.osm.pbf
+cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
 ```
-where
-* `<cache size>` is about 75% of memory in MiB, to a maximum of about 30000. Additional RAM will not be used.
-* `<flat nodes>` is a location where a 50GiB+ file can be saved.
-
-Many different data files (e.g., .pbf) can be found at [planet.osm.org](https://planet.osm.org/).
-
-The databases from either of these commands can be used immediately by
-[Mapnik](https://mapnik.org/) for rendering maps with standard tools like
-[renderd/mod_tile](https://github.com/openstreetmap/mod_tile),
-[TileMill](https://tilemill-project.github.io/tilemill/), [Nik4](https://github.com/Zverik/Nik4),
-among others.
-
-## Alternate outputs (backends) ##
 
-In addition to the standard pgsql output designed for rendering there is also
-the gazetteer output for geocoding, principally with
-[Nominatim](https://www.nominatim.org/), and the null output for testing.
-
-Also available is the new flex output. It is much more flexible than the other
-outputs. IT IS CURRENTLY EXPERIMENTAL AND SUBJECT TO CHANGE. The flex output is
-only available if you have compiled osm2pgsql with Lua support.
-
-## Projection Support ##
+### Using the PROJ library
 
 Osm2pgsql has builtin support for the Latlong (WGS84, EPSG:4326) and the
 WebMercator (EPSG:3857) projection. If you need other projections you have to
@@ -194,22 +149,24 @@ above) are supported. Usually the CMake configuration will find a suitable
 version and use it automatically, but you can set the `USE_PROJ_LIB` CMake
 cache variable to choose between the following behaviours:
 
-* `4`: Look for PROJ library with API version 4. If it is not found, stop with error.
-* `6`: Look for PROJ library with API version 6. If it is not found, stop with error.
+* `4`: Look for PROJ library with API version 4. If it is not found, stop with
+  error.
+* `6`: Look for PROJ library with API version 6. If it is not found, stop with
+  error.
 * `off`: Build without PROJ library.
 * `auto`: Choose API 4 if available, otherwise API 6. If both are not available
   build without PROJ library. (This is the default.)
 
-## LuaJIT support ##
+## Using LuaJIT
 
-To speed up Lua tag transformations, [LuaJIT](https://luajit.org/) can be optionally
-enabled on supported platforms. Performance measurements have shown about 25%
-runtime reduction for a planet import, with about 40% reduction on parsing time.
+To speed up Lua tag transformations, [LuaJIT](https://luajit.org/) can be
+optionally enabled on supported platforms. This can speed up processing
+considerably.
 
-On a Debian or Ubuntu system, this can be done with:
+On a Debian or Ubuntu system install the LuaJIT library:
 
 ```sh
-sudo apt install libluajit-5.1-dev
+sudo apt-get install libluajit-5.1-dev
 ```
 
 Configuration parameter `WITH_LUAJIT=ON` needs to be added to enable LuaJIT.
@@ -219,23 +176,20 @@ Otherwise make and installation steps are identical to the description above.
 cmake -D WITH_LUAJIT=ON ..
 ```
 
-Use `osm2pgsql --version` to verify that the build includes LuaJIT support:
+Use `osm2pgsql --version` to verify that the build includes LuaJIT support.
+The output should show something like
 
-```sh
-./osm2pgsql --version
-osm2pgsql version 1.2.0
-
-Compiled using the following library versions:
-Libosmium 2.15.6
+```
 Lua 5.1.4 (LuaJIT 2.1.0-beta3)
 ```
 
-## Contributing ##
+## Help/Support
+
+If you have problems with osm2pgsql or want to report a bug, go to
+https://osm2pgsql.org/support/ .
 
-We welcome contributions to osm2pgsql. If you would like to report an issue,
-please use the [issue tracker on GitHub](https://github.com/openstreetmap/osm2pgsql/issues).
+## Contributing
 
-More information can be found in [CONTRIBUTING.md](CONTRIBUTING.md).
+We welcome contributions to osm2pgsql. See [CONTRIBUTING.md](CONTRIBUTING.md)
+and https://osm2pgsql.org/contribute/ for information on how to contribute.
 
-General queries can be sent to the tile-serving@ or dev@
-[mailing lists](https://wiki.openstreetmap.org/wiki/Mailing_lists).

docs/osm2pgsql.1

@@ -4,7 +4,7 @@
 osm2pgsql \- Openstreetmap data to PostgreSQL converter
 .SH SYNOPSIS
 .PP
-\f[B]osm2pgsql\f[] [\f[I]OPTIONS\f[]] OSM\-FILE
+\f[B]osm2pgsql\f[] [\f[I]OPTIONS\f[]] OSM\-FILE\&...
 .SH DESCRIPTION
 .PP
 \f[B]osm2pgsql\f[] imports OpenStreetMap data into a PostgreSQL/PostGIS
@@ -14,6 +14,7 @@ geocoder and other applications processing OSM data.
 .PP
 \f[B]osm2pgsql\f[] can run in either \[lq]create\[rq] mode (the default)
 or in \[lq]append\[rq] mode (option \f[B]\-a, \-\-append\f[]).
+.PP
 In \[lq]create\[rq] mode osm2pgsql will create the database tables
 required by the configuration and import the OSM file(s) specified on
 the command line into those tables.

docs/osm2pgsql.md

@@ -4,7 +4,7 @@ osm2pgsql - Openstreetmap data to PostgreSQL converter
 
 # SYNOPSIS
 
-**osm2pgsql** \[*OPTIONS*\] OSM-FILE
+**osm2pgsql** \[*OPTIONS*\] OSM-FILE...
 
 # DESCRIPTION
 
@@ -13,10 +13,12 @@ is an essential part of many rendering toolchains, the Nominatim geocoder and
 other applications processing OSM data.
 
 **osm2pgsql** can run in either "create" mode (the default) or in "append" mode
-(option **-a, \--append**). In "create" mode osm2pgsql will create the database
-tables required by the configuration and import the OSM file(s) specified on
-the command line into those tables. Note that you also have to use the
-**-s, \--slim** option if you want your database to be updateable.
+(option **-a, \--append**).
+
+In "create" mode osm2pgsql will create the database tables required by the
+configuration and import the OSM file(s) specified on the command line into
+those tables. Note that you also have to use the **-s, \--slim** option if you
+want your database to be updateable.
 
 In "append" mode osm2pgsql will update the database tables with the data from
 OSM change files specified on the command line.