PGDOCS= ../..

SRCDIR= ../../../src

D2MDIR= ../docbook2man

HSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/html

PSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/print

HSTYLE=/opt/sgml/current/docbook/html

PSTYLE=/opt/sgml/current/docbook/print

HDSL=$(HSTYLE)/docbook.dsl

PDSL=$(PSTYLE)/docbook.dsl

PRINTOPTS= -d$(PDSL)

MANSOURCES=$(wildcard ref/*.sgml)

APPLICATIONS= createdb.sgml createuser.sgml\

destroydb.sgml destroyuser.sgml\

initdb.sgml initlocation.sgml\

pg_dump.sgml\

pg_dumpall.sgml\

pg_upgrade.sgml\

pgaccess-ref.sgml\

pgadmin-ref.sgml\

postgres-ref.sgml\

postmaster.sgml\

psql-ref.sgml\

vacuumdb.sgml

COMMANDS= abort.sgml alter_table.sgml alter_user.sgml\

begin.sgml\

close.sgml cluster.sgml commit.sgml copy.sgml\

create_aggregate.sgml create_database.sgml create_function.sgml create_index.sgml\

create_language.sgml create_operator.sgml create_rule.sgml create_sequence.sgml\

create_table.sgml create_table_as.sgml create_trigger.sgml create_type.sgml\

create_user.sgml create_view.sgml\

declare.sgml delete.sgml\

drop_aggregate.sgml drop_database.sgml drop_function.sgml drop_index.sgml\

drop_language.sgml drop_operator.sgml drop_rule.sgml drop_sequence.sgml\

drop_table.sgml drop_trigger.sgml drop_type.sgml drop_user.sgml drop_view.sgml\

explain.sgml fetch.sgml grant.sgml\

insert.sgml listen.sgml load.sgml lock.sgml move.sgml\

notify.sgml\

reset.sgml revoke.sgml rollback.sgml\

select.sgml select_into.sgml set.sgml show.sgml\

unlisten.sgml update.sgml vacuum.sgml

FUNCTIONS= current_date.sgml current_time.sgml current_timestamp.sgml current_user.sgml

APPSOURCES=$(addprefix ref/,$(APPLICATIONS))

SQLSOURCES=$(addprefix ref/,$(COMMANDS))

APPTARGETS=$(APPLICATIONS:.sgml=.1)

SQLTARGETS=$(COMMANDS:.sgml=.l)

.PRECIOUS: postgres.tex postgres.dvi

.PHONY: install all clean distclean

all::

man1:$(APPTARGETS)

$(RM) -rf man1

if [!-d man1 ];then mkdir man1;fi

mv*.1 man1/

manl:$(SQLTARGETS)

$(RM) -rf manl/*

if [!-d manl ];then mkdir manl;fi

mv*.l manl/

clean::

(rm -rf HTML.manifest*.html*.htm)

(rm -rf HTML.manifest*.html*.htm man1 manl manpage*)

distclean::

$(MAKE) clean

%.gz:%

(gzip -f $<)

%.1: ref/%.sgml

nsgmls$<| sgmlspl$(D2MDIR)/docbook2man-spec.pl --defsection 1

%.tar:%.html# %.ps

($(TAR) cf$@$*.html index.html*.htm*.gif)# $*.ps

(rm -rf index.html*.htm)

%.l: ref/%.sgml

nsgmls$<| sgmlspl$(D2MDIR)/docbook2man-spec.pl --defsection l

<note>

<title>Author</title>

<para>

This chapter originally appeared as a part of <xref linkend="SIM98" endterm="SIM98">, Stefan Simkovics'

This chapter originally appeared as a part of

<xref linkend="SIM98" endterm="SIM98">, Stefan Simkovics'

Master's Thesis prepared at Vienna University of Technology under the direction

of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr.

</para>

<para>

A detailed description of <application>yacc</application> or

the grammar rules given

in <filename>gram.y</filename> would bebeyond the scope of this paper. There are

many books anddocuments dealing with <application>lex</application>

and<application>yacc</application>. You

should be familiar with<application>yacc</application> before you start to study the

grammar given in <filename>gram.y</filename> otherwise you won't understand what

happens there.

the grammar rules given in <filename>gram.y</filename> would be

beyond the scope of this paper. There are many books and

documents dealing with <application>lex</application> and

<application>yacc</application>. You should be familiar with

<application>yacc</application> before you start to study the

grammar given in <filename>gram.y</filename> otherwise you won't

understand whathappens there.

</para>

<para>

For a better understanding of the data structures used in <productname>Postgres</productname>

For a better understanding of the data structures used in

<productname>Postgres</productname>

for the processing of a query we use an example to illustrate the

changes made to these data structures in every stage.

</para>

have already been defined.

<programlisting>

select s.sname, se.pno

from supplier s, sells se

where s.sno > 2 and

s.sno = se.sno;

select s.sname, se.pno

from supplier s, sells se

where s.sno > 2 and s.sno = se.sno;

</programlisting>

</para>

</example>

<!--

$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.17 1999/06/23 06:19:36 thomas Exp $

$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.18 1999/07/06 17:19:41 thomas Exp $

Documentation Guide

Thomas Lockhart

</thead>

<tbody>

<row>

<entry><sgmltag>Book</sgmltag></entry>

<entry><sgmltag>book</sgmltag></entry>

<entry>Delimits a Book element</entry>

</row>

<row>

<entry><sgmltag>Chapter</sgmltag></entry>

<entry><sgmltag>chapter</sgmltag></entry>

<entry>Delimits a Chapter element</entry>

</row>

<row>

<entry><sgmltag>Appendix</sgmltag></entry>

<entry><sgmltag>appendix</sgmltag></entry>

<entry><sgmltag>Delimits a Appendix element</sgmltag></entry>

</row>

</tbody>

</sect2>

</sect1>

<sect1>

<title>Building Documentation</title>

<sect1>

<title>Building Documentation</title>

<para>

GNU <application>make</application> is used to build documentation from the DocBook sources.

There are a few environment definitions which may need to be set or modified for your installation.

The <filename>Makefile</filename> looks for

<filename>doc/../src/Makefile</filename>

and (implicitly) for

<filename>doc/../src/Makefile.custom</filename>

to obtain environment information. On my system, the <filename>src/Makefile.custom</filename> looks like

<para>

GNU <application>make</application> is used to build documentation

from the DocBook sources. There are a few environment definitions

which may need to be set or modified for your installation.

The <filename>Makefile</filename> looks for

<filename>doc/../src/Makefile</filename> and (implicitly) for

<filename>doc/../src/Makefile.custom</filename> to obtain

environment information. On my system, the

<filename>src/Makefile.custom</filename> looks like

<programlisting>

<programlisting>

# Makefile.custom

# Thomas Lockhart 1998-03-01

HSTYLE= /home/tgl/SGML/db107.d/docbook/html

PSTYLE= /home/tgl/SGML/db107.d/docbook/print

</programlisting>

</programlisting>

where HSTYLE and PSTYLE determine the path to <filename>docbook.dsl</filename> for <acronym>HTML</acronym>

and hardcopy (print) stylesheets, respectively. These stylesheet file names are for Norm Walsh's

Modular Style Sheets; if other stylesheets are used then one can define HDSL and PDSL as the full path

and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.

On many systems, these stylesheets will be found in packages installed in

<filename>/usr/lib/sgml/</filename>,

<filename>/usr/share/lib/sgml/</filename>,

or

<filename>/usr/local/lib/sgml/</filename>.

</para>

where HSTYLE and PSTYLE determine the path to

<filename>docbook.dsl</filename> for <acronym>HTML</acronym>

and hardcopy (print) stylesheets, respectively. These stylesheet

file names are for Norm Walsh's

<productname>Modular Style Sheets</productname>; if other

stylesheets are used then one can define HDSL and PDSL as the full path

and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.

On many systems, these stylesheets will be found in packages installed in

<filename>/usr/lib/sgml/</filename>,

<filename>/usr/share/lib/sgml/</filename>,

or

<filename>/usr/local/lib/sgml/</filename>.

</para>

<para>

<acronym>HTML</acronym> documentation packages can be generated from the <acronym>SGML</acronym> source by

typing

<programlisting>

<para>

<acronym>HTML</acronym> documentation packages can be generated

from the <acronym>SGML</acronym> source bytyping

<programlisting>

% cd doc/src

% make tutorial.tar.gz

% make user.tar.gz

% make admin.tar.gz

% make programmer.tar.gz

% make postgres.tar.gz

% make install

</programlisting>

</para>

</programlisting>

</para>

<para>

These packages can be installed from the main documentation directory

by typing

<programlisting>

<para>

These packages can be installed from the main documentation directory

by typing

<programlisting>

% cd doc

% make install

</programlisting>

</para></sect1>

</programlisting>

</para>

</sect1>

<sect1>

<title>Manpages</title>

<para>

We use the <application>docbook2man</application> utility to

convert <productname>DocBook</productname>

<sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man

pages. At the time of writing, the utility required patching to

successfully run on the <productname>Postgres</productname> markup,

and we added a small amount of new functionality to allow setting

the man page section in the output file name.

</para>

<para>

<application>docbook2man</application> is written in perl, and

requires the CPAN package <literal>SGMLSpm</literal> to run. Also,

it requires <application>nsgmls</application> to be available,

which is included in the <application>jade</application>

distribution. After installing these packages, then simply run

<programlisting>

$ cd doc/src

$ make man

</programlisting>

which will result in a tar file being generated in the

<filename>doc/src</filename> directory.

</para>

<procedure>

<title>docbook2man Installation Procedure</title>

<step performance="required">

<para>

Install the <application>docbook2man</application> package,

available at

<ulink url="http://shell.ipoline.com/~elmert/comp/docbook2X/">http://shell.ipoline.com/~elmert/comp/docbook2X/</ulink>

</para>

</step>

<step performance="required">

<para>

Install the SGMLSpm perl module, available from CPAN mirrors.

</para>

</step>

<step performance="required">

<para>

Install <application>nsgmls</application> if not already

available from your <application>jade</application> installation.

</para>

</step>

</procedure>

</sect1>

<sect1>

<title>Hardcopy Generation for v6.5</title>

<programlisting>

PgDatabase data;

data.exec("create table foo (a int4, b char16, d float8)");

data.exec("copy foo from stdin");

data.Exec("create table foo (a int4, b char16, d float8)");

data.Exec("copy foo from stdin");

data.putline("3\etHello World\et4.5\en");

data.putline("4\etGoodbye World\et7.11\en");

&amp;...

<tgroup cols="4">

<thead>

<row>

<entry>

</entry>

<entry>

Dirty Read

</entry>