Skip to content

P
Postgres FD Implementation
Commit 684cf76b authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

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.
parent 3709ca1c
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 280 additions and 255 deletions
doc/src/sgml/Makefile
View file @ 684cf76b
......@@ -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,$^) >$@
##
......
doc/src/sgml/filelist.sgml
View file @ 684cf76b
......@@ -190,12 +190,3 @@
<!-- back matter -->
<!ENTITY biblio SYSTEM "biblio.sgml">
<!--
Some parts of the documentation are also source for some plain-text
files used during installation. To selectively ignore or include
some parts (e.g., external xref's) when generating these files we use
these parameter entities. See also standalone-install.sgml.
-->
<!ENTITY % standalone-ignore "INCLUDE">
<!ENTITY % standalone-include "IGNORE">
doc/src/sgml/installation.sgml
View file @ 684cf76b
This diff is collapsed.
doc/src/sgml/standalone-install.sgml deleted 100644 → 0
View file @ 3709ca1c
<!-- doc/src/sgml/standalone-install.sgml -->
<!--
This file helps in generating the INSTALL text file that lives in the
top level directory of the distribution.
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
<!ENTITY % version SYSTEM "version.sgml">
%version;
<!--
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. The following are essentially SGML's
equivalent of C's #ifdef and friends. The other end of this is in
installation.sgml.
-->
<!ENTITY % standalone-ignore "IGNORE">
<!ENTITY % standalone-include "INCLUDE">
<!--
When you're building the full documentation set, you want to flip the
IGNORE and INCLUDE.
-->
]>
doc/src/sgml/standalone-install.xml 0 → 100644
View file @ 684cf76b
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file contains the stand-alone installation instructions that end up in
the INSTALL file. This document stitches together parts of the installation
instructions in the main documentation with some material that only appears
in the stand-alone version.
-->
<article id="installation">
<title><productname>PostgreSQL</productname> Installation from Source Code</title>
<para>
This document describes the installation of
<productname>PostgreSQL</productname> using this source code distribution.
</para>
<xi:include href="postgres.xml" xpointer="install-short" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="postgres.xml" xpointer="install-requirements" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="postgres.xml" xpointer="install-procedure" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="postgres.xml" xpointer="install-post" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<sect1 id="install-getting-started">
<title>Getting Started</title>
<para>
The following is a quick summary of how to get <productname>PostgreSQL</productname> up and
running once installed. The main documentation contains more information.
</para>
<procedure>
<step>
<para>
Create a user account for the <productname>PostgreSQL</productname>
server. This is the user the server will run as. For production
use you should create a separate, unprivileged account
(<quote>postgres</quote> 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.
<screen><userinput>adduser postgres</userinput></screen>
</para>
</step>
<step>
<para>
Create a database installation with the <command>initdb</command>
command. To run <command>initdb</command> you must be logged in to your
<productname>PostgreSQL</productname> server account. It will not work as
root.
<screen>root# <userinput>mkdir /usr/local/pgsql/data</userinput>
root# <userinput>chown postgres /usr/local/pgsql/data</userinput>
root# <userinput>su - postgres</userinput>
postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</userinput></screen>
</para>
<para>
The <option>-D</option> 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 <command>initdb</command>, as
illustrated here.
</para>
</step>
<step>
<para>
At this point, if you did not use the <command>initdb</command> <literal>-A</literal>
option, you might want to modify <filename>pg_hba.conf</filename> to control
local access to the server before you start it. The default is to
trust all local users.
</para>
</step>
<step>
<para>
The previous <command>initdb</command> step should have told you how to
start up the database server. Do so now. The command should look
something like:
<programlisting>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</programlisting>
This will start the server in the foreground. To put the server
in the background use something like:
<programlisting>nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
&lt;/dev/null &gt;&gt;server.log 2&gt;&amp;1 &lt;/dev/null &amp;</programlisting>
</para>
<para>
To stop a server running in the background you can type:
<programlisting>kill `cat /usr/local/pgsql/data/postmaster.pid`</programlisting>
</para>
</step>
<step>
<para>
Create a database:
<screen><userinput>createdb testdb</userinput></screen>
Then enter:
<screen><userinput>psql testdb</userinput></screen>
to connect to that database. At the prompt you can enter SQL
commands and start experimenting.
</para>
</step>
</procedure>
</sect1>
<sect1 id="install-whatnow">
<title>What Now?</title>
<para>
<itemizedlist>
<listitem>
<para>
The <productname>PostgreSQL</productname> distribution contains a
comprehensive documentation set, which you should read sometime.
After installation, the documentation can be accessed by
pointing your browser to
<filename>/usr/local/pgsql/doc/html/index.html</filename>, unless you
changed the installation directories.
</para>
<para>
The first few chapters of the main documentation are the Tutorial,
which should be your first reading if you are completely new to
<acronym>SQL</acronym> 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.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
Run the regression tests against the installed server (using
<command>make installcheck</command>). If you didn't run the
tests before installation, you should definitely do it now. This
is also explained in the documentation.
</para>
</listitem>
<listitem>
<para>
By default, <productname>PostgreSQL</productname> 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 <varname>shared_buffers</varname> and
<varname>work_mem</varname>.
Other parameters mentioned in the documentation also affect
performance.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<xi:include href="postgres.xml" xpointer="supported-platforms" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="postgres.xml" xpointer="installation-platform-notes" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</article>
doc/src/sgml/standalone-profile.xsl 0 → 100644
View file @ 684cf76b
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!--
This is a preprocessing layer to convert the installation instructions into a
variant without links and references to the main documentation.
- To omit something in the stand-alone INSTALL file, give the element a
condition="standalone-ignore" attribute.
- If there is no element that exactly covers what you want to change, wrap it
in a <phrase> element, which otherwise does nothing.
- Otherwise, write a custom rule below.
-->
<xsl:output
doctype-public="-//OASIS//DTD DocBook XML V4.2//EN"
doctype-system="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"/>
<!-- copy everything by default -->
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:apply-templates select="@*|node()" />
</xsl:copy>
</xsl:template>
<!-- particular conversions -->
<xsl:template match="*[@condition='standalone-ignore']">
</xsl:template>
<xsl:template match="phrase/text()['chapter']">
<xsl:text>document</xsl:text>
</xsl:template>
<xsl:template match="phrase[@id='install-ldap-links']">
<xsl:text>the documentation about client authentication and libpq</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='docguide-toolsets']">
<xsl:text>the main documentation's appendix on documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='dynamic-trace']">
<xsl:text>the documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='install-windows']">
<xsl:text>the documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='pgcrypto']">
<xsl:text>pgcrypto</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='plpython-python23']">
<xsl:text>the </xsl:text><application>PL/Python</application><xsl:text> documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='regress']">
<xsl:text>the file </xsl:text>
<filename>src/test/regress/README</filename>
<xsl:text> and the documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='upgrading']">
<xsl:text>the documentation</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='uuid-ossp']">
<xsl:text>uuid-ossp</xsl:text>
</xsl:template>
<xsl:template match="xref[@linkend='xml2']">
<xsl:text>xml2</xsl:text>
</xsl:template>
</xsl:stylesheet>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment