From 9ebfd07205254bb81487d37cbf4ea31b275b9f94 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 15 Sep 2017 10:17:37 -0400 Subject: [PATCH] Get rid of parameterized marked sections in SGML Previously, we created a variant of the installation instructions for producing the plain-text INSTALL file by marking up certain parts of installation.sgml using SGML parameterized marked sections. Marked sections will not work anymore in XML, so before we can convert the documentation to XML, we need a new approach. DocBook provides a "profiling" feature that allows selecting content based on attributes, which would work here. But it imposes a noticeable overhead when building the full documentation, and give that we recently spent a fair amount of effort optimizing the documentation build time, it seems sad to have to accept that. So as an alternative, (1) we create our own mini-profiling layer that adjusts just the text we want, and (2) assemble the pieces of content that we want in the INSTALL file using XInclude. That way, there is no overhead when building the full documentation and most of the "ugly" stuff in installation.sgml can be removed and dealt with out of line. --- doc/src/sgml/Makefile | 5 +- doc/src/sgml/filelist.sgml | 9 -- doc/src/sgml/installation.sgml | 243 +++++------------------------------ doc/src/sgml/standalone-install.sgml | 28 ---- doc/src/sgml/standalone-install.xml | 167 ++++++++++++++++++++++++ doc/src/sgml/standalone-profile.xsl | 81 ++++++++++++ 6 files changed, 280 insertions(+), 253 deletions(-) delete mode 100644 doc/src/sgml/standalone-install.sgml create mode 100644 doc/src/sgml/standalone-install.xml create mode 100644 doc/src/sgml/standalone-profile.xsl diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 7458ef4de2..128d827c1a 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -134,9 +134,8 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ -INSTALL.xml: standalone-install.sgml installation.sgml version.sgml - $(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $(filter-out version.sgml,$^) >$@.tmp - $(call mangle-xml,chapter) +INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.xml + $(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ ## diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index b914086009..bb93448c37 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -191,12 +191,3 @@ - - - - diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 12866b4bf7..17079c5fa4 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,28 +1,26 @@ - <![%standalone-include[<productname>PostgreSQL</>]]> - Installation from Source Code + Installation from Source Code installation - This - describes the installation of + This chapter describes the installation of PostgreSQL using the source code distribution. (If you are installing a pre-packaged distribution, such as an RPM or Debian package, ignore this - - + chapter and read the packager's instructions instead.) @@ -45,8 +43,7 @@ Short Version /usr/local/pgsql/bin/psql test The long version is the rest of this - - + chapter. @@ -197,8 +194,7 @@ Requirements required version is Python 2.4. Python 3 is supported if it's version 3.1 or later; but see - PL/Python documentation]]> - ]]> + when using Python 3. @@ -267,9 +263,7 @@ Requirements To build the PostgreSQL documentation, there is a separate set of requirements; see - .]]> - + . @@ -340,7 +334,6 @@ Requirements - Getting The Source @@ -369,7 +362,6 @@ Getting The Source . -]]> Installation Procedure @@ -844,9 +836,8 @@ Configuration Build with LDAPLDAP support for authentication and connection parameter lookup (see - and - ]]> for more information). On Unix, + and + for more information). On Unix, this requires the OpenLDAP package to be installed. On Windows, the default WinLDAP library is used. configure will check for the required @@ -865,8 +856,8 @@ Configuration for systemdsystemd service notifications. This improves integration if the server binary is started under systemd but has no impact - otherwise for more - information]]>. libsystemd and the + otherwise; see for more + information. libsystemd and the associated header files need to be installed to be able to use this option. @@ -911,8 +902,7 @@ Configuration - Build the - ]]> module + Build the module (which provides functions to generate UUIDs), using the specified UUID library.UUID LIBRARY must be one of: @@ -979,8 +969,7 @@ Configuration Use libxslt when building the - - ]]> + module. xml2 relies on this library to perform XSL transformations of XML. @@ -1110,8 +1099,7 @@ Configuration has no support for strong random numbers on the platform. A source of random numbers is needed for some authentication protocols, as well as some routines in the - - ]]> + module. disables functionality that requires cryptographically strong random numbers, and substitutes a weak pseudo-random-number-generator for the generation of @@ -1215,8 +1203,8 @@ Configuration code coverage testing instrumentation. When run, they generate files in the build directory with code coverage metrics. - - for more information.]]> This option is for use only with GCC + See + for more information. This option is for use only with GCC and when doing development work. @@ -1276,8 +1264,8 @@ Configuration Compiles PostgreSQL with support for the dynamic tracing tool DTrace. - - for more information.]]> + See + for more information. @@ -1312,7 +1300,7 @@ Configuration Enable tests using the Perl TAP tools. This requires a Perl installation and the Perl module IPC::Run. - for more information.]]> + See for more information. @@ -1469,9 +1457,7 @@ Configuration whether Python 2 or 3 is specified here (or otherwise implicitly chosen) determines which variant of the PL/Python language becomes available. See - PL/Python - documentation]]> - ]]> + for more information. @@ -1598,10 +1584,7 @@ Regression Tests make check (This won't work as root; do it as an unprivileged user.) - src/test/regress/README and the - documentation contain]]> - contains]]> + See for detailed information about interpreting the test results. You can repeat this test at any later time by issuing the same command. @@ -1613,8 +1596,7 @@ Installing the Files If you are upgrading an existing system be sure to read - - ]]> + , which has instructions about upgrading a cluster. @@ -1872,167 +1854,6 @@ Environment Variables - - - Getting Started - - - The following is a quick summary of how to get PostgreSQL up and - running once installed. The main documentation contains more information. - - - - - - Create a user account for the PostgreSQL - server. This is the user the server will run as. For production - use you should create a separate, unprivileged account - (postgres is commonly used). If you do not have root - access or just want to play around, your own user account is - enough, but running the server as root is a security risk and - will not work. - -adduser postgres - - - - - - - Create a database installation with the initdb - command. To run initdb you must be logged in to your - PostgreSQL server account. It will not work as - root. - -root# mkdir /usr/local/pgsql/data -root# chown postgres /usr/local/pgsql/data -root# su - postgres -postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data - - - - - The - - - - - At this point, if you did not use the initdb -A - option, you might want to modify pg_hba.conf to control - local access to the server before you start it. The default is to - trust all local users. - - - - - - The previous initdb step should have told you how to - start up the database server. Do so now. The command should look - something like: - -/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data - - This will start the server in the foreground. To put the server - in the background use something like: - -nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \ - </dev/null >>server.log 2>&1 </dev/null & - - - - - To stop a server running in the background you can type: - -kill `cat /usr/local/pgsql/data/postmaster.pid` - - - - - - - Create a database: - -createdb testdb - - Then enter: - -psql testdb - - to connect to that database. At the prompt you can enter SQL - commands and start experimenting. - - - - - - - What Now? - - - - - - The PostgreSQL distribution contains a - comprehensive documentation set, which you should read sometime. - After installation, the documentation can be accessed by - pointing your browser to - /usr/local/pgsql/doc/html/index.html, unless you - changed the installation directories. - - - - The first few chapters of the main documentation are the Tutorial, - which should be your first reading if you are completely new to - SQL databases. If you are familiar with database - concepts then you want to proceed with part on server - administration, which contains information about how to set up - the database server, database users, and authentication. - - - - - - Usually, you will want to modify your computer so that it will - automatically start the database server whenever it boots. Some - suggestions for this are in the documentation. - - - - - - Run the regression tests against the installed server (using - make installcheck). If you didn't run the - tests before installation, you should definitely do it now. This - is also explained in the documentation. - - - - - - By default, PostgreSQL is configured to run on - minimal hardware. This allows it to start up with almost any - hardware configuration. The default configuration is, however, - not designed for optimum performance. To achieve optimum - performance, several server parameters must be adjusted, the two - most common being shared_buffers and - work_mem. - Other parameters mentioned in the documentation also affect - performance. - - - - - -]]> - - Supported Platforms @@ -2090,9 +1911,7 @@ Platform-specific Notes regarding the installation and setup of PostgreSQL. Be sure to read the installation instructions, and in particular as well. Also, - check src/test/regress/README and the documentation]]> - ]]> regarding the + check regarding the interpretation of regression test results. @@ -2443,7 +2262,7 @@ Cygwin PostgreSQL can be built using Cygwin, a Linux-like environment for Windows, but that method is inferior to the native Windows build - )]]> and + (see ) and running a server under Cygwin is no longer recommended. @@ -2641,8 +2460,7 @@ MinGW/Native Windows Microsoft's Visual C++ compiler suite. The MinGW build variant uses the normal build system described in this chapter; the Visual C++ build works completely differently - and is described in ]]>. + and is described in . It is a fully native build and uses no additional software like MinGW. A ready-made installer is available on the main PostgreSQL web site. @@ -2803,9 +2621,8 @@ Compiling for Optimal Performance Using DTrace for Tracing PostgreSQL - Yes, using DTrace is possible. See - ]]> for further + Yes, using DTrace is possible. See + for further information. You can also find more information in this article: . diff --git a/doc/src/sgml/standalone-install.sgml b/doc/src/sgml/standalone-install.sgml deleted file mode 100644 index 1942f9dc4c..0000000000 --- a/doc/src/sgml/standalone-install.sgml +++ /dev/null @@ -1,28 +0,0 @@ - - - - - -%version; - - - - - - - -]> diff --git a/doc/src/sgml/standalone-install.xml b/doc/src/sgml/standalone-install.xml new file mode 100644 index 0000000000..49d94c5187 --- /dev/null +++ b/doc/src/sgml/standalone-install.xml @@ -0,0 +1,167 @@ + + + +
+ <productname>PostgreSQL</productname> Installation from Source Code + + + This document describes the installation of + PostgreSQL using this source code distribution. + + + + + + + + + Getting Started + + + The following is a quick summary of how to get PostgreSQL up and + running once installed. The main documentation contains more information. + + + + + + Create a user account for the PostgreSQL + server. This is the user the server will run as. For production + use you should create a separate, unprivileged account + (postgres is commonly used). If you do not have root + access or just want to play around, your own user account is + enough, but running the server as root is a security risk and + will not work. +adduser postgres + + + + + + Create a database installation with the initdb + command. To run initdb you must be logged in to your + PostgreSQL server account. It will not work as + root. +root# mkdir /usr/local/pgsql/data +root# chown postgres /usr/local/pgsql/data +root# su - postgres +postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data + + + + The option specifies the location where the data + will be stored. You can use any path you want, it does not have + to be under the installation directory. Just make sure that the + server account can write to the directory (or create it, if it + doesn't already exist) before starting initdb, as + illustrated here. + + + + + + At this point, if you did not use the initdb -A + option, you might want to modify pg_hba.conf to control + local access to the server before you start it. The default is to + trust all local users. + + + + + + The previous initdb step should have told you how to + start up the database server. Do so now. The command should look + something like: +/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data + This will start the server in the foreground. To put the server + in the background use something like: +nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \ + </dev/null >>server.log 2>&1 </dev/null & + + + + To stop a server running in the background you can type: +kill `cat /usr/local/pgsql/data/postmaster.pid` + + + + + + Create a database: +createdb testdb + Then enter: +psql testdb + to connect to that database. At the prompt you can enter SQL + commands and start experimenting. + + + + + + + What Now? + + + + + + The PostgreSQL distribution contains a + comprehensive documentation set, which you should read sometime. + After installation, the documentation can be accessed by + pointing your browser to + /usr/local/pgsql/doc/html/index.html, unless you + changed the installation directories. + + + + The first few chapters of the main documentation are the Tutorial, + which should be your first reading if you are completely new to + SQL databases. If you are familiar with database + concepts then you want to proceed with part on server + administration, which contains information about how to set up + the database server, database users, and authentication. + + + + + + Usually, you will want to modify your computer so that it will + automatically start the database server whenever it boots. Some + suggestions for this are in the documentation. + + + + + + Run the regression tests against the installed server (using + make installcheck). If you didn't run the + tests before installation, you should definitely do it now. This + is also explained in the documentation. + + + + + + By default, PostgreSQL is configured to run on + minimal hardware. This allows it to start up with almost any + hardware configuration. The default configuration is, however, + not designed for optimum performance. To achieve optimum + performance, several server parameters must be adjusted, the two + most common being shared_buffers and + work_mem. + Other parameters mentioned in the documentation also affect + performance. + + + + + + + + +
diff --git a/doc/src/sgml/standalone-profile.xsl b/doc/src/sgml/standalone-profile.xsl new file mode 100644 index 0000000000..ff464c1654 --- /dev/null +++ b/doc/src/sgml/standalone-profile.xsl @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + + + + + + + + + document + + + + the documentation about client authentication and libpq + + + + the main documentation's appendix on documentation + + + + the documentation + + + + the documentation + + + + pgcrypto + + + + the PL/Python documentation + + + + the file + src/test/regress/README + and the documentation + + + + the documentation + + + + uuid-ossp + + + + xml2 + + + -- 2.11.0 (Apple Git-81)