database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-29 10:41:53 +03:00
Code Activity

Add User's Guide chapters on Data Definition and Data Manipulation.

Browse Source 
Still needs to be filled with more information, but it gives us a
framework to have a User's Guide with complete coverage of the basic
SQL operations.  Move arrays into data type chapter, inheritance into
DDL chapter (for now).

Make <comment>s show up in the output while the version number ends in
"devel".

Allow cross-book references with entities &cite-user; etc.
This commit is contained in:
Peter Eisentraut
2002-08-05 19:43:31 +00:00
parent 15fe086fba
commit 6f4a9fb119
11 changed files with 67 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
doc/src/sgml/Makefile
View File

@ -8,7 +8,7 @@
# #
# #
# IDENTIFICATION # IDENTIFICATION
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.50 2002/04/14 17:23:20 petere Exp $ # $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.51 2002/08/05 19:43:30 petere Exp $
# #
#---------------------------------------------------------------------------- #----------------------------------------------------------------------------
@ -58,6 +58,11 @@ ifdef DOCBOOKSTYLE
CATALOG = -c $(DOCBOOKSTYLE)/catalog CATALOG = -c $(DOCBOOKSTYLE)/catalog
endif endif
# Enable draft mode during development
ifneq (,$(findstring devel, $(VERSION)))
JADEFLAGS += -V draft-mode
endif
## ##
## Man pages ## Man pages

6
doc/src/sgml/array.sgml
View File

@ -1,6 +1,6 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.20 2002/03/17 19:59:57 tgl Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.21 2002/08/05 19:43:30 petere Exp $ -->
<chapter id="arrays"> <sect1 id="arrays">
<title>Arrays</title> <title>Arrays</title>
<indexterm> <indexterm>
@ -325,4 +325,4 @@ INSERT ... VALUES ('{"\\\\","\\""}');
</para> </para>
</tip> </tip>
</chapter> </sect1>

2
doc/src/sgml/book-decl.sgml
View File

@ -8,4 +8,6 @@
<!entity % set-of-books "IGNORE"> <!entity % set-of-books "IGNORE">
<!entity % single-book "INCLUDE"> <!entity % single-book "INCLUDE">
<!entity % entities SYSTEM "entities.sgml">
%entities;
]> ]>

4
doc/src/sgml/datatype.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.96 2002/07/16 17:05:46 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.97 2002/08/05 19:43:30 petere Exp $
--> -->
<chapter id="datatype"> <chapter id="datatype">
@ -3093,6 +3093,8 @@ SELECT SUBSTRING(b FROM 1 FOR 2) FROM test;
</sect1> </sect1>
&array;
</chapter> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file

5
doc/src/sgml/filelist.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.20 2002/07/30 19:36:10 momjian Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
<!entity history SYSTEM "history.sgml"> <!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml"> <!entity info SYSTEM "info.sgml">
@ -23,10 +23,11 @@
<!entity array SYSTEM "array.sgml"> <!entity array SYSTEM "array.sgml">
<!entity datatype SYSTEM "datatype.sgml"> <!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml"> <!entity datetime SYSTEM "datetime.sgml">
<!entity ddl SYSTEM "ddl.sgml">
<!entity dml SYSTEM "dml.sgml">
<!entity features SYSTEM "features.sgml"> <!entity features SYSTEM "features.sgml">
<!entity func SYSTEM "func.sgml"> <!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml"> <!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity keywords SYSTEM "keywords.sgml"> <!entity keywords SYSTEM "keywords.sgml">
<!entity manage SYSTEM "manage.sgml"> <!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml"> <!entity mvcc SYSTEM "mvcc.sgml">

4
doc/src/sgml/mvcc.sgml
View File

@ -1,9 +1,9 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.25 2002/05/30 20:45:18 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.26 2002/08/05 19:43:31 petere Exp $
--> -->
<chapter id="mvcc"> <chapter id="mvcc">
<title>Multiversion Concurrency Control</title> <title>Concurrency Control</title>
<indexterm> <indexterm>
<primary>concurrency</primary> <primary>concurrency</primary>

5
doc/src/sgml/postgres.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.47 2001/11/21 05:53:41 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.48 2002/08/05 19:43:31 petere Exp $
--> -->
<!doctype set PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!doctype set PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
@ -12,6 +12,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.47 2001/11/21 05:53:41 th
<!entity % set-of-books "INCLUDE"> <!entity % set-of-books "INCLUDE">
<!entity % single-book "IGNORE"> <!entity % single-book "IGNORE">
<!entity % entities SYSTEM "entities.sgml">
%entities;
<!entity admin SYSTEM "admin.sgml"> <!entity admin SYSTEM "admin.sgml">
<!entity developer SYSTEM "developer.sgml"> <!entity developer SYSTEM "developer.sgml">
<!entity programmer SYSTEM "programmer.sgml"> <!entity programmer SYSTEM "programmer.sgml">

28
doc/src/sgml/queries.sgml
View File

@ -1,16 +1,22 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.15 2002/04/25 20:14:43 tgl Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.16 2002/08/05 19:43:31 petere Exp $ -->
<chapter id="queries"> <chapter id="queries">
<title>Queries</title> <title>Queries</title>
<para>
The previous chapters explained how to create tables, how to fill
them with data, and how to manipulate that data. Now we finally
discuss how to retrieve the data out of the database.
</para>
<sect1 id="queries-overview"> <sect1 id="queries-overview">
<title>Overview</title> <title>Overview</title>
<para> <para>
A <firstterm>query</firstterm> is the process of retrieving or the command The process of retrieving or the command to retrieve data from a
to retrieve data from a database. In SQL the <command>SELECT</command> database is called a <firstterm>query</firstterm>. In SQL the
command is used to specify queries. The general syntax of the <command>SELECT</command> command is used to specify queries. The
<command>SELECT</command> command is general syntax of the <command>SELECT</command> command is
<synopsis> <synopsis>
SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional> SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional>
</synopsis> </synopsis>
@ -114,14 +120,14 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
A joined table is a table derived from two other (real or A joined table is a table derived from two other (real or
derived) tables according to the rules of the particular join derived) tables according to the rules of the particular join
type. INNER, OUTER, and CROSS JOIN are supported. type. Inner, outer, and cross-joins are available.
</para> </para>
<variablelist> <variablelist>
<title>Join Types</title> <title>Join Types</title>
<varlistentry> <varlistentry>
<term>CROSS JOIN</term> <term>Cross-join</term>
<indexterm> <indexterm>
<primary>joins</primary> <primary>joins</primary>
@ -244,7 +250,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
First, an INNER JOIN is performed. Then, for each row in T1 First, an INNER JOIN is performed. Then, for each row in T1
that does not satisfy the join condition with any row in that does not satisfy the join condition with any row in
T2, a joined row is returned with NULL values in columns of T2, a joined row is returned with null values in columns of
T2. Thus, the joined table unconditionally has at least one T2. Thus, the joined table unconditionally has at least one
row for each row in T1. row for each row in T1.
</para> </para>
@ -258,7 +264,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
First, an INNER JOIN is performed. Then, for each row in T2 First, an INNER JOIN is performed. Then, for each row in T2
that does not satisfy the join condition with any row in that does not satisfy the join condition with any row in
T1, a joined row is returned with NULL values in columns of T1, a joined row is returned with null values in columns of
T1. This is the converse of a left join: the result table will T1. This is the converse of a left join: the result table will
unconditionally have a row for each row in T2. unconditionally have a row for each row in T2.
</para> </para>
@ -460,7 +466,7 @@ WHERE <replaceable>search_condition</replaceable>
After the processing of the FROM clause is done, each row of the After the processing of the FROM clause is done, each row of the
derived table is checked against the search condition. If the derived table is checked against the search condition. If the
result of the condition is true, the row is kept in the output result of the condition is true, the row is kept in the output
table, otherwise (that is, if the result is false or NULL) it is table, otherwise (that is, if the result is false or null) it is
discarded. The search condition typically references at least some discarded. The search condition typically references at least some
column in the table generated in the FROM clause; this is not column in the table generated in the FROM clause; this is not
required, but otherwise the WHERE clause will be fairly useless. required, but otherwise the WHERE clause will be fairly useless.
@ -735,7 +741,7 @@ SELECT DISTINCT <replaceable>select_list</replaceable> ...
<para> <para>
Obviously, two rows are considered distinct if they differ in at Obviously, two rows are considered distinct if they differ in at
least one column value. NULLs are considered equal in this least one column value. Null values are considered equal in this
comparison. comparison.
</para> </para>

10
doc/src/sgml/stylesheet.dsl
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.20 2002/06/01 20:56:00 petere Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!-- must turn on one of these with -i on the jade command line --> <!-- must turn on one of these with -i on the jade command line -->
@ -28,6 +28,8 @@
<!-- (applicable to all output formats) --> <!-- (applicable to all output formats) -->
(define draft-mode #f)
(define pgsql-docs-list "pgsql-docs@postgresql.org") (define pgsql-docs-list "pgsql-docs@postgresql.org")
;; Don't show manpage volume numbers ;; Don't show manpage volume numbers
@ -37,9 +39,8 @@
;; it needs extra work.) ;; it needs extra work.)
(define %callout-graphics% #f) (define %callout-graphics% #f)
;; Don't show comments. (We ought to show them, at least during the ;; Show comments during the development stage.
;; development stage.) (define %show-comments% draft-mode)
(define %show-comments% #f)
;; Don't append period if run-in title ends with any of these ;; Don't append period if run-in title ends with any of these
;; characters. We had to add the colon here. This is fixed in ;; characters. We had to add the colon here. This is fixed in
@ -57,6 +58,7 @@
(element structname ($mono-seq$)) (element structname ($mono-seq$))
(element symbol ($mono-seq$)) (element symbol ($mono-seq$))
(element type ($mono-seq$)) (element type ($mono-seq$))
(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code
;; Indentation of verbatim environments ;; Indentation of verbatim environments
(define %indent-programlisting-lines% " ") (define %indent-programlisting-lines% " ")

25
doc/src/sgml/syntax.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.64 2002/08/05 19:43:31 petere Exp $
--> -->
<chapter id="sql-syntax"> <chapter id="sql-syntax">
@ -10,11 +10,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl
<secondary>SQL</secondary> <secondary>SQL</secondary>
</indexterm> </indexterm>
<abstract> <para>
<para> This chapter describes the syntax of SQL. It forms the foundation
This chapter describes the syntax of SQL. for understanding the following chapters which will go into detail
</para> about how the SQL commands are applied to define and modify data.
</abstract> </para>
<para>
We also advise users who are already familiar with SQL to read this
chapter carefully because there are several rules and concepts that
are implemented inconsistently among SQL databases or that are
specific to <productname>PostgreSQL</productname>.
</para>
<sect1 id="sql-syntax-lexical"> <sect1 id="sql-syntax-lexical">
<title>Lexical Structure</title> <title>Lexical Structure</title>
@ -798,7 +805,7 @@ SELECT (5 !) - 6;
</sect1> </sect1>
<sect1 id="sql-naming"> <sect1 id="sql-naming">
<title>Schemas and naming conventions</title> <title>Schemas and Naming Conventions</title>
<indexterm> <indexterm>
<primary>schemas</primary> <primary>schemas</primary>
@ -831,6 +838,9 @@ SELECT (5 !) - 6;
</para> </para>
</note> </note>
<sect2>
<title>Schema Object Names</title>
<para> <para>
A database contains one or more named <firstterm>schemas</>, which A database contains one or more named <firstterm>schemas</>, which
in turn contain tables. Schemas also contain other kinds of named in turn contain tables. Schemas also contain other kinds of named
@ -944,6 +954,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
place <literal>pg_catalog</> at the end of your search path if you place <literal>pg_catalog</> at the end of your search path if you
prefer to have user-defined names override built-in names. prefer to have user-defined names override built-in names.
</para> </para>
</sect2>
<sect2 id="sql-reserved-names"> <sect2 id="sql-reserved-names">
<title>Reserved names</title> <title>Reserved names</title>

6
doc/src/sgml/user.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.30 2002/06/15 02:59:55 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31 petere Exp $
--> -->
<book id="user"> <book id="user">
@ -16,13 +16,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.30 2002/06/15 02:59:55
&intro; &intro;
&syntax; &syntax;
&ddl;
&dml;
&queries; &queries;
&datatype; &datatype;
&func; &func;
&typeconv; &typeconv;
&array;
&indices; &indices;
&inherit;
&mvcc; &mvcc;
&manage; &manage;
&perform; &perform;