From 302c501af015312f3595327b799b27b1569dd33b Mon Sep 17 00:00:00 2001 From: Vitaly Davydov Date: Tue, 19 Sep 2023 13:03:07 +0300 Subject: [PATCH 1/5] Remove the obsolete text from the doc --- doc/functions.sgm | 11 +++++++++-- doc/install.sgm | 39 +++++++++++++++++++++------------------ doc/pg_sphere.xml | 2 -- 3 files changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/functions.sgm b/doc/functions.sgm index 6093c33..8903c6b 100644 --- a/doc/functions.sgm +++ b/doc/functions.sgm @@ -14,8 +14,9 @@ The area function returns the area of a spherical object in square radians. Supported data types are: - scircle, spolygon (if the polygon - is convex), sbox, and smoc. + scircle, spolygon, sbox, + smoc. The polygon should be convex, otherwise the + behaviour is undefined. Area of a spherical circle as a multiple of &pg_pgr; @@ -25,6 +26,12 @@ + + + + + Area of a moc object + SELECT area(smoc '0/1-3');]]> diff --git a/doc/install.sgm b/doc/install.sgm index f1c4b54..42ff64a 100644 --- a/doc/install.sgm +++ b/doc/install.sgm @@ -7,8 +7,15 @@ pgSphere is not part of the PostgreSQL software. - You can download it from the pgSphere homepage - https://github.com/postgrespro/pgsphere + You can download the latest release sources from the + + pgSphere homepage + (the Releases page). The sources can also be downloaded by + cloning the repository with the appropriate release tag (each release is + marked with a tag). + The master branch is intended for development use + and can contain an intermediate work. + It is not recommented for use in production. @@ -17,8 +24,7 @@ Installation - You will need PostgreSQL - 9.1 or above. We assume that you have + We assume that you have PostgreSQL already compiled and installed. Please note: Depending on your system configuration mostly you have to be logged in as the system superuser. @@ -32,10 +38,11 @@ If the sources are not yet installed and the directory pg_sphere does not exist, take the gzipped pgSphere sources ( e. g., - pg_sphere_xxx.tgz ) and run: + pgsphere-X.X.X.tgz, where X.X.X is the version number) + and run: - tar -xzf path/to/pg_sphere_xxx.tgz]]> + tar -xzf path/to/pgsphere-X.X.X.tgz]]> Now, change into the pg_sphere @@ -58,7 +65,7 @@ First unpack the pgSphere sources: - tar -xzf path_to_pg_sphere_xxx.tgz]]> + tar -xzf path/to/pgsphere-X.X.X.tgz]]> Now, change into the pg_sphere @@ -80,12 +87,6 @@ make installcheck]]> - - The check status will be displayed. Please note, the check gives different results with - different PostgreSQL-versions. Currently, the check should - run without errors with PostgreSQL-version 8.4. Otherwise check - the file regression.diff. - @@ -105,11 +106,13 @@ psql -U postgres -c 'CREATE EXTENSION pg_sphere' datab]]> - Depending on your system, it may be necessary to give more - psql options like port or host name. - Please have a look at the - PostgreSQL documentation for more - details. + It may be necessary to give more + psql options, like port or host name, + depending on your system. + Please take a look at the psql user manual for details. + The psql user manual for the latest postgresql version can be + found at + PostgreSQL site. To get the version of installed pgSphere software, simply diff --git a/doc/pg_sphere.xml b/doc/pg_sphere.xml index 1ca32a7..2c6b373 100644 --- a/doc/pg_sphere.xml +++ b/doc/pg_sphere.xml @@ -11,8 +11,6 @@ - - From 8ebb3a9d75fb0e84155304c0d00b303f6d6b5b03 Mon Sep 17 00:00:00 2001 From: Vitaly Davydov Date: Wed, 20 Sep 2023 08:14:28 +0300 Subject: [PATCH 2/5] Fix some typos --- doc/install.sgm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/install.sgm b/doc/install.sgm index 42ff64a..a9bc5c0 100644 --- a/doc/install.sgm +++ b/doc/install.sgm @@ -14,8 +14,8 @@ cloning the repository with the appropriate release tag (each release is marked with a tag). The master branch is intended for development use - and can contain an intermediate work. - It is not recommented for use in production. + and may contain the code in a transitional state. + It is not recommended for use in production. From fea5f0d83cb56d6865de7d64f024715a85234a22 Mon Sep 17 00:00:00 2001 From: Vitaly Davydov Date: Fri, 22 Sep 2023 12:14:42 +0300 Subject: [PATCH 3/5] Update Installation section --- doc/install.sgm | 200 ++++++++++++++++++++-------------------------- doc/pg_sphere.xml | 4 + 2 files changed, 90 insertions(+), 114 deletions(-) diff --git a/doc/install.sgm b/doc/install.sgm index a9bc5c0..6af9509 100644 --- a/doc/install.sgm +++ b/doc/install.sgm @@ -1,126 +1,98 @@ Installation - - - Download - - - pgSphere is not part of the PostgreSQL software. - You can download the latest release sources from the - - pgSphere homepage - (the Releases page). The sources can also be downloaded by - cloning the repository with the appropriate release tag (each release is - marked with a tag). - The master branch is intended for development use - and may contain the code in a transitional state. - It is not recommended for use in production. - - + + Download - - - Installation - - - We assume that you have - PostgreSQL already compiled and - installed. Please note: Depending on your system configuration mostly you have to be logged in as the system - superuser. - - - There are two ways to compile pgSphere. - The first is to copy the sources into the contribution directory of - PostgreSQL's source tree - (POSTGRESQL_SRC/src/contrib). - Then, change into POSTGRESQL_SRC/src/contrib. - If the sources are not yet installed and the directory - pg_sphere does not exist, take the - gzipped pgSphere sources ( e. g., - pgsphere-X.X.X.tgz, where X.X.X is the version number) - and run: - - + + &pgsphere; is not the part of the &postgresql; software. You can download + the latest release sources from the + &pgsphere; Releases page. + The sources can also be downloaded by cloning the repository with the + appropriate release tag. The master branch is intended for development + use and may contain the code in a transitional state. It is not recommended + for use in production. + + + + + Install + + It is assumed that &postgresql; is already installed. Depending on the + system configuration, superuser (root) access rights may be required to + complete the installation. + + + + The installation script uses &pg_config; utility. Make sure that the + environment variable PATH includes path to &pg_config; utility. The path + to &pg_config; can be also specified in make command: + make PG_CONFIG=/path/to/pgconfig. + + + Unpack the downloaded archive and enter the directory: + tar -xzf path/to/pgsphere-X.X.X.tgz]]> - - - Now, change into the pg_sphere - directory and run : - - + cd pgsphere-X.X.X]]> + + + + Compile the code. By default, &pgsphere; is compiled with the HEALPIX + support. + + make]]> - - - and to install pgSphere : - - + + or compile without HEALPIX support: + + make USE_HEALPIX=0]]> + + + + Run regression tests optionally. If the &pgsphere; was compiled without + HEALPIX support, USE_HEALPIX=0 should be specified in make command line. + + + make test]]> + + + + Install &pgsphere; files to the installation directories. The installation + directories are defined by &pg_config; utility. Superuser (root) access + rights may be required. + + make install]]> - - - The second way does not require the PostgreSQL sources but - the configuration tool pg_config. - - - First unpack the pgSphere sources: - - - tar -xzf path/to/pgsphere-X.X.X.tgz]]> - - - Now, change into the pg_sphere - directory and run: - - - make USE_PGXS=1 PG_CONFIG=/path/to/pg_config]]> - - - To install pgSphere you have to run : - - - make USE_PGXS=1 PG_CONFIG=/path/to/pg_config install]]> - - - To check the installation change into the pg_sphere source - directory again and run: - - - make installcheck]]> - + + + + + + Configure Extension + + + We assume you have already created a database userdb, + where userdb is the name of any database. Assume that + the name of &postgresql;'s superuser is postgres. + + + psql -U postgres -c 'CREATE EXTENSION pg_sphere' userdb]]> + - + + It may be necessary to give more psql options, like port + or host name, depending on your system configuration. Please, take a look at + the psql user manual for details. The psql user manual for the latest + &postgresql; version can be found at + + &postgresql; site + . + - - - Creating a database with <application>pgSphere</application> - - - We assume you have already created a database - datab, where datab - is the name of any database. - Presupposing the name of your - PostgreSQL's superuser is - postgres, type: - - - psql -U postgres -c 'CREATE EXTENSION pg_sphere' datab]]> - - - It may be necessary to give more - psql options, like port or host name, - depending on your system. - Please take a look at the psql user manual for details. - The psql user manual for the latest postgresql version can be - found at - PostgreSQL site. - - - To get the version of installed pgSphere software, simply - call: - - + To get the version of installed pgSphere software: + SELECT pg_sphere_version();]]> - - + + diff --git a/doc/pg_sphere.xml b/doc/pg_sphere.xml index 2c6b373..bd62a6e 100644 --- a/doc/pg_sphere.xml +++ b/doc/pg_sphere.xml @@ -26,6 +26,10 @@ &ohgr;"> &OHgr;"> &pgr;"> +pgSphere"> +PostgreSQL"> +pg_config"> + ]> From be40da703a9bd4b13432ebaecda16d856757724d Mon Sep 17 00:00:00 2001 From: Vitaly Davydov Date: Tue, 26 Sep 2023 10:34:06 +0300 Subject: [PATCH 4/5] Elaborate review comments from @esabol --- doc/functions.sgm | 2 +- doc/install.sgm | 21 ++++++++++++--------- doc/pg_sphere.xml | 1 + 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/functions.sgm b/doc/functions.sgm index 8903c6b..b65f8c0 100644 --- a/doc/functions.sgm +++ b/doc/functions.sgm @@ -30,7 +30,7 @@ - Area of a moc object + Area of a Multi-Order Coverage (MOC) object SELECT area(smoc '0/1-3');]]> diff --git a/doc/install.sgm b/doc/install.sgm index 6af9509..84eacc1 100644 --- a/doc/install.sgm +++ b/doc/install.sgm @@ -6,9 +6,9 @@ &pgsphere; is not the part of the &postgresql; software. You can download - the latest release sources from the + the latest release from the &pgsphere; Releases page. - The sources can also be downloaded by cloning the repository with the + The source code can also be downloaded by cloning the repository with the appropriate release tag. The master branch is intended for development use and may contain the code in a transitional state. It is not recommended for use in production. @@ -27,7 +27,9 @@ The installation script uses &pg_config; utility. Make sure that the environment variable PATH includes path to &pg_config; utility. The path to &pg_config; can be also specified in make command: - make PG_CONFIG=/path/to/pgconfig. + + make PG_CONFIG=/path/to/pgconfig ...]]> + Unpack the downloaded archive and enter the directory: @@ -37,20 +39,20 @@ - Compile the code. By default, &pgsphere; is compiled with the HEALPIX + Compile the code. By default, &pgsphere; is compiled with the &healpix; support. make]]> - or compile without HEALPIX support: + or compile without &healpix; support: make USE_HEALPIX=0]]> - Run regression tests optionally. If the &pgsphere; was compiled without - HEALPIX support, USE_HEALPIX=0 should be specified in make command line. + Run regression tests optionally. If &pgsphere; was compiled without &healpix; + support, USE_HEALPIX=0 should be specified in make command line. make test]]> @@ -59,7 +61,8 @@ Install &pgsphere; files to the installation directories. The installation directories are defined by &pg_config; utility. Superuser (root) access - rights may be required. + rights may be required. If &pgsphere; was compiled without &healpix; support, + USE_HEALPIX=0 should be added after make. make install]]> @@ -89,7 +92,7 @@ . - To get the version of installed pgSphere software: + To get the version of installed &pgsphere; software: SELECT pg_sphere_version();]]> diff --git a/doc/pg_sphere.xml b/doc/pg_sphere.xml index bd62a6e..62cd79d 100644 --- a/doc/pg_sphere.xml +++ b/doc/pg_sphere.xml @@ -26,6 +26,7 @@ &ohgr;"> &OHgr;"> &pgr;"> +HEALPix"> pgSphere"> PostgreSQL"> pg_config"> From 71951845025ddc913cca169dcd219a9166360821 Mon Sep 17 00:00:00 2001 From: Vitaly Davydov Date: Wed, 27 Sep 2023 23:51:31 +0300 Subject: [PATCH 5/5] Removed unnecessary 'the' article --- doc/install.sgm | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/install.sgm b/doc/install.sgm index 84eacc1..ded78fa 100644 --- a/doc/install.sgm +++ b/doc/install.sgm @@ -39,8 +39,7 @@ - Compile the code. By default, &pgsphere; is compiled with the &healpix; - support. + Compile the code. By default, &pgsphere; is compiled with &healpix; support. make]]>