Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eITMR-0006vY-0B for pgsql-docs@arkaria.postgresql.org; Sat, 25 Nov 2017 05:50:43 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eITMQ-0003Bl-AY for pgsql-docs@arkaria.postgresql.org; Sat, 25 Nov 2017 05:50:42 +0000 Received: from makus.postgresql.org ([2001:4800:1501:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1eITMP-0003Bb-SH for pgsql-docs@lists.postgresql.org; Sat, 25 Nov 2017 05:50:42 +0000 Received: from mail-lf0-x241.google.com ([2a00:1450:4010:c07::241]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1eITMK-00049q-3x for pgsql-docs@postgresql.org; Sat, 25 Nov 2017 05:50:40 +0000 Received: by mail-lf0-x241.google.com with SMTP id 73so27371267lfu.10 for ; Fri, 24 Nov 2017 21:50:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language; bh=G/dC69J78jjsDQQdP2jhs/n6hhXegGd+I2Pb5k4HxkA=; b=UV6apaM1dgEwAS/I6n/Mq8OsxHfbp0qATHZv7UrbXIlftIJgw1bHSYzVFMIUctaTrb LyBax/eEffhtGVwzeT/8UayHkuUphj2Ti+GCP0WcWNgyit6T/zbtPM6TXFzWzb+43+b7 hFK6OEc6Mf5lWhJpXNoKrCJpAUCp9nO5fGhZ3K/JUp96foczN8YgcACKvzmxhF3yPd+A JqUfMJ5CWl1/96WBywNC6cUWLGu21xLywQ7O85agjFmIAdluzf4HxPY9ELeReCnvZm+r RAorSqEDMH1wG1UePFqRIotkLBuesZ/tWEEEWmPYmPKrUnWUMOhVmSRwBehmb83D2cmZ 0+aw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language; bh=G/dC69J78jjsDQQdP2jhs/n6hhXegGd+I2Pb5k4HxkA=; b=Ch7N5HHgaQHqC91xrnX0UZRa8sQIBag6e3AXeoR8QtgeAu0qCHUT5HiUCG8OlIK5MK p87KFATKA5HZEDd9A2tJ90wy8MkS4M+dzjpxS2TG9nyj/wpP0SdAgVk0WxxMWdJhvw/+ sGu/wmi1k16tSxTLzSC0hDsSGaIKvugzaktqzQJyl4RkMHl8a/iS5Bc+I+v+zZc7aKLy saw7YvdbZ0kVkk3HYQFXDdxxVw1zFZddM/jzGG7F5JPYGQzNgeMlzTyNOFNpyYIC78gx hx61iRlztpP9cBftRzSxwDQd2vU3vVMkDb35jVYDz8qOn6wXxK9io4jGifz9Bz4tgJ3D utrg== X-Gm-Message-State: AJaThX4u1Uu1fcctoMJDu72SfVh5QYoVXhaZof0L7RB11cmY4vucBHss K2JNj2tMlHsE3cMqO88FzdbvIEqj X-Google-Smtp-Source: AGs4zMbaXI8cxcQBjmY/nf/R9dju2VJxz8xK0tZdialLuFsGwXpeGFNAKoZobsoLpYYsSMcbQ2y6og== X-Received: by 10.25.150.10 with SMTP id y10mr10812028lfd.91.1511589033282; Fri, 24 Nov 2017 21:50:33 -0800 (PST) Received: from [1.0.0.7] ([178.155.4.142]) by smtp.gmail.com with ESMTPSA id 72sm3126785ljz.31.2017.11.24.21.50.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 24 Nov 2017 21:50:32 -0800 (PST) Subject: Re: [DOCS] Docbook 5.x To: Peter Eisentraut , =?UTF-8?Q?J=c3=bcrgen_Purtz?= Cc: pgsql-docs@postgresql.org, Tom Lane References: <57179283.6080704@purtz.de> <4adecfc6-2f2e-2ff2-bfa3-58b7d397227b@gmail.com> <8f227b2a-5093-8d99-85da-ea00e18343f6@gmail.com> <449e34c4-9cc8-d17d-5ebe-be92b4c0a87a@gmail.com> <09b13d85-e259-2464-723a-467210264afe@2ndquadrant.com> <9e8cafe4-7cfd-59be-6856-172c15dc758f@2ndquadrant.com> <11c0be48-6125-bbe1-1d02-6d61e889bd5e@gmail.com> <2162400e-e279-94fc-c47f-bfab18ceb700@gmail.com> <07342223-4eec-6523-2de2-11587f3f0920@2ndquadrant.com> <18ed8940-ae84-09c9-1236-d8a9648b2417@gmail.com> <047254d2-d46c-94af-1933-4551633a909b@2ndquadrant.com> From: Alexander Lakhin Message-ID: <7a6cc69f-c8b9-686b-9c00-0e10866ee163@gmail.com> Date: Sat, 25 Nov 2017 08:50:30 +0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.4.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/mixed; boundary="------------8BBCCEF755DA1DC4CE9EF63C" Content-Language: en-US List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------8BBCCEF755DA1DC4CE9EF63C Content-Type: multipart/alternative; boundary="------------907F167FAD28CB4E6D7D59ED" --------------907F167FAD28CB4E6D7D59ED Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Hello, 23.11.2017 17:53, Peter Eisentraut wrote: > On 11/15/17 16:06, Peter Eisentraut wrote: >> Here is the final patch set for the conversion. > I have committed this. Great! Thank you for your work! And in light of possible need to convert to xml older branches too, maybe we should simplify INSTALL now. Please, consider applying the attached patch. It produces the same INSTALL and is much better in the following aspects. 1. All the INSTALL content is placed in two files (installation.sgml and installation-single.xsl) instead of three (installation.sgml, standalone-install.xml, standalone-profile.xsl). 2. There are no unreadable and untranslatable (in context) constructions such as   the PL/Python documentation (Sometimes translators need to replace larger fragments.) 3. It uses only XSLT (which we use already), no xi:include. 4. It doesn't generate complete postgres.sgml to process only the installation section. I understand that it will take some time to review it, but I think it's justified by the portability and supportability reasons. Best regards, ------ Alexander Lakhin Postgres Professional: http://www.postgrespro.com The Russian Postgres Company --------------907F167FAD28CB4E6D7D59ED Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 8bit
Hello,
23.11.2017 17:53, Peter Eisentraut wrote:
On 11/15/17 16:06, Peter Eisentraut wrote:
Here is the final patch set for the conversion.
I have committed this.
Great! Thank you for your work!
And in light of possible need to convert to xml older branches too, maybe we should simplify INSTALL now.
Please, consider applying the attached patch. It produces the same INSTALL and is much better in the following aspects.

1. All the INSTALL content is placed in two files (installation.sgml and installation-single.xsl) instead of three (installation.sgml, standalone-install.xml, standalone-profile.xsl).
2. There are no unreadable and untranslatable (in context) constructions such as
<xsl:template match="xref[@linkend='plpython-python23']">
  <xsl:text>the </xsl:text><application>PL/Python</application><xsl:text> documentation</xsl:text>
</xsl:template>
(Sometimes translators need to replace larger fragments.)
3. It uses only XSLT (which we use already), no xi:include.
4. It doesn't generate complete postgres.sgml to process only the installation section.

I understand that it will take some time to review it, but I think it's justified by the portability and supportability reasons.

Best regards,

------
Alexander Lakhin
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
--------------907F167FAD28CB4E6D7D59ED-- --------------8BBCCEF755DA1DC4CE9EF63C Content-Type: text/x-patch; name="installation.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="installation.patch" diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index f122b41..0cf3afe 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -111,13 +111,8 @@ LYNX = lynx INSTALL: % : %.html $(PERL) -p -e 's, $@ -INSTALL.html: %.html : stylesheet-text.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ - -INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.sgml $(ALLSGML) - $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ - +INSTALL.html: installation.sgml installation-single.xsl stylesheet-text.xsl + sed -e "s/&version;/$(VERSION)/" $< | $(XSLTPROC) $(XSLTPROCFLAGS) $(word 2,$^) - | $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(word 3,$^) - >$@ ## ## HTML diff --git a/doc/src/sgml/installation-single.xsl b/doc/src/sgml/installation-single.xsl new file mode 100644 index 0000000..d8f45b5 --- /dev/null +++ b/doc/src/sgml/installation-single.xsl @@ -0,0 +1,202 @@ + + +%version; +]> + + + + + + + + + + + + + + + +
+ <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/installation.sgml b/doc/src/sgml/installation.sgml index a922819..1ddf105 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -4,22 +4,24 @@ The standalone version has some portions that are different from the version that is integrated into the full documentation set, in particular as regards links, so that INSTALL.html can be created without links to the main -documentation. See standalone-profile.xsl for details. +documentation. See installation-single.xsl for details. --> - Installation from Source Code + <phrase standalonetext="PostgreSQL"></phrase> + Installation from Source Code installation - This chapter 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 + such as an RPM or Debian package, ignore this + chapter and read the packager's instructions instead.) @@ -42,7 +44,7 @@ su - postgres /usr/local/pgsql/bin/psql test The long version is the rest of this - chapter. + chapter. @@ -193,7 +195,7 @@ su - postgres required version is Python 2.4. Python 3 is supported if it's version 3.1 or later; but see - + when using Python 3. @@ -262,7 +264,8 @@ su - postgres To build the PostgreSQL documentation, there is a separate set of requirements; see - . + . @@ -835,8 +838,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 @@ -855,7 +858,7 @@ su - postgres for systemdsystemd service notifications. This improves integration if the server binary is started under systemd but has no impact - otherwise; see for more + otherwise; see for more information. libsystemd and the associated header files need to be installed to be able to use this option. @@ -901,7 +904,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: @@ -968,7 +971,7 @@ su - postgres Use libxslt when building the - + module. xml2 relies on this library to perform XSL transformations of XML. @@ -1084,7 +1087,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 @@ -1188,7 +1191,7 @@ su - postgres code coverage testing instrumentation. When run, they generate files in the build directory with code coverage metrics. - See + See for more information. This option is for use only with GCC and when doing development work. @@ -1249,7 +1252,7 @@ su - postgres Compiles PostgreSQL with support for the dynamic tracing tool DTrace. - See + See for more information. @@ -1285,7 +1288,7 @@ su - postgres Enable tests using the Perl TAP tools. This requires a Perl installation and the Perl module IPC::Run. - See for more information. + See for more information. @@ -1442,7 +1445,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 - + for more information. @@ -1569,7 +1572,8 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. make check (This won't work as root; do it as an unprivileged user.) - See for + + contains detailed information about interpreting the test results. You can repeat this test at any later time by issuing the same command. @@ -1581,7 +1585,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. @@ -1895,9 +1899,9 @@ export MANPATH This section documents additional platform-specific issues regarding the installation and setup of PostgreSQL. Be sure to read the installation instructions, and in - particular as well. Also, - check regarding the - interpretation of regression test results. + particular as well. Also, check + + regarding the interpretation of regression test results. @@ -2247,7 +2251,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 - (see ) and + (see ) and running a server under Cygwin is no longer recommended. @@ -2441,7 +2445,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. @@ -2602,8 +2606,9 @@ 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/postgres.sgml b/doc/src/sgml/postgres.sgml index 041afdb..8ae4754 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -11,6 +11,7 @@ + ]> diff --git a/doc/src/sgml/standalone-install.xml b/doc/src/sgml/standalone-install.xml deleted file mode 100644 index 62582ef..0000000 --- a/doc/src/sgml/standalone-install.xml +++ /dev/null @@ -1,167 +0,0 @@ - - - -
- <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 deleted file mode 100644 index ff464c1..0000000 --- a/doc/src/sgml/standalone-profile.xsl +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - 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 - - - --------------8BBCCEF755DA1DC4CE9EF63C--