Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove the obsolete text from the doc #65

Merged
merged 5 commits into from
Sep 29, 2023
Merged

Remove the obsolete text from the doc #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
302c501
Remove the obsolete text from the doc
vitcpp Sep 19, 2023
8ebb3a9
Fix some typos
vitcpp Sep 20, 2023
fea5f0d
Update Installation section
vitcpp Sep 22, 2023
be40da7
Elaborate review comments from @esabol
vitcpp Sep 26, 2023
7195184
Removed unnecessary 'the' article
vitcpp Sep 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions doc/functions.sgm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,9 @@
<para>
The <function>area</function> function returns the area of a
spherical object in square radians. Supported data types are:
<type>scircle</type>, <type>spolygon</type> (if the polygon
is convex), <type>sbox</type>, and <type>smoc</type>.
<type>scircle</type>, <type>spolygon</type>, <type>sbox</type>,
<type>smoc</type>. The polygon should be convex, otherwise the
behaviour is undefined.
</para>
<example>
<title>Area of a spherical circle as a multiple of &pg_pgr;</title>
Expand All @@ -25,6 +26,12 @@
<![CDATA[------]]>
<![CDATA[ 1]]>
<![CDATA[(1 row)]]>
</programlisting>
</example>

<example>
<title>Area of a Multi-Order Coverage (MOC) object</title>
<programlisting>
<![CDATA[sql> SELECT area(smoc '0/1-3');]]>
<![CDATA[ area]]>
<![CDATA[-------------------]]>
Expand Down
201 changes: 89 additions & 112 deletions doc/install.sgm
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,123 +1,100 @@
<chapter id="install">
<title>Installation</title>

<sect1 id="install-download">
<title>
Download
</title>
<para>
<application>pgSphere</application> is not part of the <application>PostgreSQL</application> software.
You can download it from the <application>pgSphere</application> homepage
<ulink url="https://github.com/postgrespro/pgsphere"><citetitle>https://github.com/postgrespro/pgsphere</citetitle></ulink>
</para>
</sect1>
<sect1 id="install-download">
<title>Download</title>

<sect1 id="install-sect2">
<title>
Installation
</title>
<para>
You will need <application>PostgreSQL
9.1</application> or above. We assume that you have
<application>PostgreSQL</application> already compiled and
installed. Please note: Depending on your system configuration mostly you have to be logged in as the system
superuser.
</para>
<para>
There are two ways to compile <application>pgSphere</application>.
The first is to copy the sources into the contribution directory of
<application>PostgreSQL</application>'s source tree
(<filename>POSTGRESQL_SRC/src/contrib</filename>).
Then, change into <filename>POSTGRESQL_SRC/src/contrib</filename>.
If the sources are not yet installed and the directory
<filename>pg_sphere</filename> does not exist, take the
gzipped <application>pgSphere</application> sources ( e. g.,
<filename>pg_sphere_xxx.tgz</filename> ) and run:
</para>
<programlisting>
<![CDATA[shell> tar -xzf path/to/pg_sphere_xxx.tgz]]>
</programlisting>
<para>
Now, change into the <filename>pg_sphere</filename>
directory and run :
</para>
<programlisting>
<para>
&pgsphere; is not the part of the &postgresql; software. You can download
the latest release from the
<ulink url="&pgsphereurl;">&pgsphere; Releases page</ulink>.
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.
</para>
</sect1>

<sect1 id="install-build">
<title>Install</title>
<para>
It is assumed that &postgresql; is already installed. Depending on the
system configuration, superuser (root) access rights may be required to
complete the installation.
</para>

<para>
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:
<programlisting>
<![CDATA[shell> make PG_CONFIG=/path/to/pgconfig ...]]>
</programlisting>
</para>

<para>Unpack the downloaded archive and enter the directory:</para>
<programlisting>
<![CDATA[shell> tar -xzf path/to/pgsphere-X.X.X.tgz]]>
<![CDATA[shell> cd pgsphere-X.X.X]]>
</programlisting>

<para>
Compile the code. By default, &pgsphere; is compiled with &healpix; support.
</para>
<programlisting>
<![CDATA[shell> make]]>
</programlisting>
<para>
and to install <application>pgSphere</application> :
</para>
<programlisting>
</programlisting>
<para>or compile without &healpix; support:</para>
<programlisting>
<![CDATA[shell> make USE_HEALPIX=0]]>
</programlisting>

<para>
Run regression tests optionally. If &pgsphere; was compiled without &healpix;
support, USE_HEALPIX=0 should be specified in make command line.
</para>
<programlisting>
<![CDATA[shell> make test]]>
</programlisting>

<para>
Install &pgsphere; files to the installation directories. The installation
directories are defined by &pg_config; utility. Superuser (root) access
rights may be required. If &pgsphere; was compiled without &healpix; support,
USE_HEALPIX=0 should be added after make.
</para>
<programlisting>
<![CDATA[shell> make install]]>
</programlisting>
<para>
The second way does not require the <application>PostgreSQL</application> sources but
the configuration tool <application>pg_config</application>.
</para>
<para>
First unpack the <application>pgSphere</application> sources:
</para>
<programlisting>
<![CDATA[shell> tar -xzf path_to_pg_sphere_xxx.tgz]]>
</programlisting>
<para>
Now, change into the <filename>pg_sphere</filename>
directory and run:
</para>
<programlisting>
<![CDATA[shell> make USE_PGXS=1 PG_CONFIG=/path/to/pg_config]]>
</programlisting>
<para>
To install <application>pgSphere</application> you have to run :
</para>
<programlisting>
<![CDATA[shell> make USE_PGXS=1 PG_CONFIG=/path/to/pg_config install]]>
</programlisting>
<para>
To check the installation change into the <filename>pg_sphere</filename> source
directory again and run:
</para>
<programlisting>
<![CDATA[shell> make installcheck]]>
</programlisting>
<para>
The check status will be displayed. Please note, the check gives different results with
different <application>PostgreSQL</application>-versions. Currently, the check should
run without errors with <application>PostgreSQL</application>-version 8.4. Otherwise check
the file <filename>regression.diff</filename>.
</para>
</programlisting>

</sect1>

<sect1 id="install-sect3">
<title>Configure Extension</title>

<para>
We assume you have already created a database <database>userdb</database>,
where <database>userdb</database> is the name of any database. Assume that
the name of &postgresql;'s superuser is <parameter>postgres</parameter>.
</para>
<programlisting>
<![CDATA[shell> psql -U postgres -c 'CREATE EXTENSION pg_sphere' userdb]]>
</programlisting>

</sect1>
<para>
It may be necessary to give more <command>psql</command> 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
<ulink url="https://www.postgresql.org/docs/current/app-psql.html">
&postgresql; site
</ulink>.
</para>

<sect1 id="install-sect3">
<title>
Creating a database with <application>pgSphere</application>
</title>
<para>
We assume you have already created a database
<database>datab</database>, where <database>datab</database>
is the name of any database.
Presupposing the name of your
<application>PostgreSQL</application>'s superuser is
<parameter>postgres</parameter>, type:
</para>
<programlisting>
<![CDATA[shell> psql -U postgres -c 'CREATE EXTENSION pg_sphere' datab]]>
</programlisting>
<para>
Depending on your system, it may be necessary to give more
<command>psql</command> options like port or host name.
Please have a look at the
<application>PostgreSQL</application> documentation for more
details.
</para>
<para>
To get the version of installed pgSphere software, simply
call:
</para>
<programlisting>
<para>To get the version of installed &pgsphere; software:</para>
<programlisting>
<![CDATA[pgsql> SELECT pg_sphere_version();]]>
</programlisting>
</sect1>
</programlisting>

</sect1>
</chapter>
7 changes: 5 additions & 2 deletions doc/pg_sphere.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@
<!ENTITY capFunctions SYSTEM "functions.sgm">
<!ENTITY capIndices SYSTEM "indices.sgm">
<!ENTITY capExamples SYSTEM "examples.sgm">
<!ENTITY capFaq SYSTEM "faq.sgm">
<!ENTITY capAppendixes SYSTEM "appendixes.sgm">

<!ENTITY graph1001 "img/spoint.jpg">
<!ENTITY graph1002 "img/scircle.jpg">
Expand All @@ -28,6 +26,11 @@
<!ENTITY pg_ohgr "<symbol role='symbol'>&ohgr;</symbol>">
<!ENTITY pg_OHgr "<symbol role='symbol'>&OHgr;</symbol>">
<!ENTITY pg_pgr "<symbol role='symbol'>&pgr;</symbol>">
<!ENTITY healpix "<application>HEALPix</application>">
<!ENTITY pgsphere "<application>pgSphere</application>">
<!ENTITY postgresql "<application>PostgreSQL</application>">
<!ENTITY pg_config "<application>pg_config</application>">
<!ENTITY pgsphereurl "https://github.com/postgrespro/pgsphere/releases">

<!ENTITY pg_sphere_version SYSTEM "version.xml">
]>
Expand Down