From 684cf76b83e9dc8aed12aeb9131d2208f61bd31f 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 causes complications when building some output formats, and given 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 | 245 ++++----------------------- 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(+), 255 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 7458ef4de23..128d827c1a6 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 bd371fd1d38..9050559abda 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -190,12 +190,3 @@ - - - - diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index a1bae951457..f4e4fc7c5e2 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,28 +1,25 @@ - <![%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 - - + such as an RPM or Debian package, ignore this chapter and read the packager's instructions instead.) @@ -45,8 +42,7 @@ su - postgres /usr/local/pgsql/bin/psql test The long version is the rest of this - - + chapter. @@ -197,8 +193,7 @@ su - postgres 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 +262,7 @@ su - postgres To build the PostgreSQL documentation, there is a separate set of requirements; see - .]]> - + . @@ -340,7 +333,6 @@ su - postgres - Getting The Source @@ -369,7 +361,6 @@ su - postgres . -]]> Installation Procedure @@ -844,9 +835,8 @@ su - postgres 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 +855,8 @@ su - postgres 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 +901,7 @@ su - postgres - 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 +968,7 @@ su - postgres Use libxslt when building the - - ]]> + module. xml2 relies on this library to perform XSL transformations of XML. @@ -1096,8 +1084,7 @@ su - postgres 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 @@ -1201,8 +1188,8 @@ su - postgres 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. @@ -1262,8 +1249,8 @@ su - postgres Compiles PostgreSQL with support for the dynamic tracing tool DTrace. - - for more information.]]> + See + for more information. @@ -1298,7 +1285,7 @@ su - postgres 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. @@ -1455,9 +1442,7 @@ su - postgres 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. @@ -1584,10 +1569,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. 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. @@ -1599,8 +1581,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. If you are upgrading an existing system be sure to read - - ]]> + , which has instructions about upgrading a cluster. @@ -1858,167 +1839,6 @@ export MANPATH - - - 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 @@ -2076,9 +1896,7 @@ kill `cat /usr/local/pgsql/data/postmaster.pid` 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. @@ -2429,7 +2247,7 @@ ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address 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. @@ -2623,8 +2441,7 @@ PHSS_30849 s700_800 u2comp/be/plugin library Patch 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. @@ -2785,10 +2602,8 @@ LIBOBJS = snprintf.o Using DTrace for Tracing PostgreSQL - Yes, using DTrace is possible. See - ]]> for further - information. + Yes, using DTrace is possible. See for + further information. diff --git a/doc/src/sgml/standalone-install.sgml b/doc/src/sgml/standalone-install.sgml deleted file mode 100644 index 1942f9dc4c9..00000000000 --- 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 00000000000..49d94c51873 --- /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 00000000000..ff464c16545 --- /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 + + +