Skip to content

Commit 6f4a9fb

Browse files
peterepetere
committed
Add User's Guide chapters on Data Definition and Data Manipulation.
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.
1 parent 15fe086 commit 6f4a9fb

File tree

11 files changed

+67
-35
lines changed

11 files changed

+67
-35
lines changed

‎doc/src/sgml/Makefile

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
#
99
#
1010
# IDENTIFICATION
11-
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.50 2002/04/14 17:23:20 petere Exp $
11+
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.51 2002/08/05 19:43:30 petere Exp $
1212
#
1313
#----------------------------------------------------------------------------
1414

@@ -58,6 +58,11 @@ ifdef DOCBOOKSTYLE
5858
CATALOG = -c $(DOCBOOKSTYLE)/catalog
5959
endif
6060

61+
# Enable draft mode during development
62+
ifneq (,$(findstring devel, $(VERSION)))
63+
JADEFLAGS += -V draft-mode
64+
endif
65+
6166

6267
##
6368
## Man pages

‎doc/src/sgml/array.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.20 2002/03/17 19:59:57 tgl Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/array.sgml,v 1.21 2002/08/05 19:43:30 petere Exp $ -->
22

3-
<chapter id="arrays">
3+
<sect1 id="arrays">
44
<title>Arrays</title>
55

66
<indexterm>
@@ -325,4 +325,4 @@ INSERT ... VALUES ('{"\\\\","\\""}');
325325
</para>
326326
</tip>
327327

328-
</chapter>
328+
</sect1>

‎doc/src/sgml/book-decl.sgml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,6 @@
88
<!entity % set-of-books "IGNORE">
99
<!entity % single-book "INCLUDE">
1010

11+
<!entity % entities SYSTEM "entities.sgml">
12+
%entities;
1113
]>

‎doc/src/sgml/datatype.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.96 2002/07/16 17:05:46 momjian Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.97 2002/08/05 19:43:30 petere Exp $
33
-->
44

55
<chapter id="datatype">
@@ -3093,6 +3093,8 @@ SELECT SUBSTRING(b FROM 1 FOR 2) FROM test;
30933093

30943094
</sect1>
30953095

3096+
&array;
3097+
30963098
</chapter>
30973099

30983100
<!-- Keep this comment at the end of the file

‎doc/src/sgml/filelist.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.20 2002/07/30 19:36:10 momjian Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
22

33
<!entity history SYSTEM "history.sgml">
44
<!entity info SYSTEM "info.sgml">
@@ -23,10 +23,11 @@
2323
<!entity array SYSTEM "array.sgml">
2424
<!entity datatype SYSTEM "datatype.sgml">
2525
<!entity datetime SYSTEM "datetime.sgml">
26+
<!entity ddl SYSTEM "ddl.sgml">
27+
<!entity dml SYSTEM "dml.sgml">
2628
<!entity features SYSTEM "features.sgml">
2729
<!entity func SYSTEM "func.sgml">
2830
<!entity indices SYSTEM "indices.sgml">
29-
<!entity inherit SYSTEM "inherit.sgml">
3031
<!entity keywords SYSTEM "keywords.sgml">
3132
<!entity manage SYSTEM "manage.sgml">
3233
<!entity mvcc SYSTEM "mvcc.sgml">

‎doc/src/sgml/mvcc.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.25 2002/05/30 20:45:18 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.26 2002/08/05 19:43:31 petere Exp $
33
-->
44

55
<chapter id="mvcc">
6-
<title>Multiversion Concurrency Control</title>
6+
<title>Concurrency Control</title>
77

88
<indexterm>
99
<primary>concurrency</primary>

‎doc/src/sgml/postgres.sgml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.47 2001/11/21 05:53:41 thomas Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.48 2002/08/05 19:43:31 petere Exp $
33
-->
44

55
<!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
1212
<!entity % set-of-books "INCLUDE">
1313
<!entity % single-book "IGNORE">
1414

15+
<!entity % entities SYSTEM "entities.sgml">
16+
%entities;
17+
1518
<!entity admin SYSTEM "admin.sgml">
1619
<!entity developer SYSTEM "developer.sgml">
1720
<!entity programmer SYSTEM "programmer.sgml">

‎doc/src/sgml/queries.sgml

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,22 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.15 2002/04/25 20:14:43 tgl Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v 1.16 2002/08/05 19:43:31 petere Exp $ -->
22

33
<chapter id="queries">
44
<title>Queries</title>
55

6+
<para>
7+
The previous chapters explained how to create tables, how to fill
8+
them with data, and how to manipulate that data. Now we finally
9+
discuss how to retrieve the data out of the database.
10+
</para>
11+
612
<sect1 id="queries-overview">
713
<title>Overview</title>
814

915
<para>
10-
A <firstterm>query</firstterm> is the process of retrieving or the command
11-
to retrieve data from a database. In SQL the <command>SELECT</command>
12-
command is used to specify queries. The general syntax of the
13-
<command>SELECT</command> command is
16+
The process of retrieving or the command to retrieve data from a
17+
database is called a <firstterm>query</firstterm>. In SQL the
18+
<command>SELECT</command> command is used to specify queries. The
19+
general syntax of the <command>SELECT</command> command is
1420
<synopsis>
1521
SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable> <optional><replaceable>sort_specification</replaceable></optional>
1622
</synopsis>
@@ -114,14 +120,14 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
114120
<para>
115121
A joined table is a table derived from two other (real or
116122
derived) tables according to the rules of the particular join
117-
type. INNER, OUTER, and CROSS JOIN are supported.
123+
type. Inner, outer, and cross-joins are available.
118124
</para>
119125

120126
<variablelist>
121127
<title>Join Types</title>
122128

123129
<varlistentry>
124-
<term>CROSS JOIN</term>
130+
<term>Cross-join</term>
125131

126132
<indexterm>
127133
<primary>joins</primary>
@@ -244,7 +250,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
244250
<para>
245251
First, an INNER JOIN is performed. Then, for each row in T1
246252
that does not satisfy the join condition with any row in
247-
T2, a joined row is returned with NULL values in columns of
253+
T2, a joined row is returned with null values in columns of
248254
T2. Thus, the joined table unconditionally has at least one
249255
row for each row in T1.
250256
</para>
@@ -258,7 +264,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
258264
<para>
259265
First, an INNER JOIN is performed. Then, for each row in T2
260266
that does not satisfy the join condition with any row in
261-
T1, a joined row is returned with NULL values in columns of
267+
T1, a joined row is returned with null values in columns of
262268
T1. This is the converse of a left join: the result table will
263269
unconditionally have a row for each row in T2.
264270
</para>
@@ -460,7 +466,7 @@ WHERE <replaceable>search_condition</replaceable>
460466
After the processing of the FROM clause is done, each row of the
461467
derived table is checked against the search condition. If the
462468
result of the condition is true, the row is kept in the output
463-
table, otherwise (that is, if the result is false or NULL) it is
469+
table, otherwise (that is, if the result is false or null) it is
464470
discarded. The search condition typically references at least some
465471
column in the table generated in the FROM clause; this is not
466472
required, but otherwise the WHERE clause will be fairly useless.
@@ -735,7 +741,7 @@ SELECT DISTINCT <replaceable>select_list</replaceable> ...
735741

736742
<para>
737743
Obviously, two rows are considered distinct if they differ in at
738-
least one column value. NULLs are considered equal in this
744+
least one column value. Null values are considered equal in this
739745
comparison.
740746
</para>
741747

‎doc/src/sgml/stylesheet.dsl

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.20 2002/06/01 20:56:00 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.dsl,v 1.21 2002/08/05 19:43:31 petere Exp $ -->
22
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
33

44
<!-- must turn on one of these with -i on the jade command line -->
@@ -28,6 +28,8 @@
2828

2929
<!-- (applicable to all output formats) -->
3030

31+
(define draft-mode #f)
32+
3133
(define pgsql-docs-list "pgsql-docs@postgresql.org")
3234

3335
;; Don't show manpage volume numbers
@@ -37,9 +39,8 @@
3739
;; it needs extra work.)
3840
(define %callout-graphics% #f)
3941

40-
;; Don't show comments. (We ought to show them, at least during the
41-
;; development stage.)
42-
(define %show-comments% #f)
42+
;; Show comments during the development stage.
43+
(define %show-comments% draft-mode)
4344

4445
;; Don't append period if run-in title ends with any of these
4546
;; characters. We had to add the colon here. This is fixed in
@@ -57,6 +58,7 @@
5758
(element structname ($mono-seq$))
5859
(element symbol ($mono-seq$))
5960
(element type ($mono-seq$))
61+
(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code
6062

6163
;; Indentation of verbatim environments
6264
(define %indent-programlisting-lines% " ")

‎doc/src/sgml/syntax.sgml

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.63 2002/06/15 22:15:03 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.64 2002/08/05 19:43:31 petere Exp $
33
-->
44

55
<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
1010
<secondary>SQL</secondary>
1111
</indexterm>
1212

13-
<abstract>
14-
<para>
15-
This chapter describes the syntax of SQL.
16-
</para>
17-
</abstract>
13+
<para>
14+
This chapter describes the syntax of SQL. It forms the foundation
15+
for understanding the following chapters which will go into detail
16+
about how the SQL commands are applied to define and modify data.
17+
</para>
18+
19+
<para>
20+
We also advise users who are already familiar with SQL to read this
21+
chapter carefully because there are several rules and concepts that
22+
are implemented inconsistently among SQL databases or that are
23+
specific to <productname>PostgreSQL</productname>.
24+
</para>
1825

1926
<sect1 id="sql-syntax-lexical">
2027
<title>Lexical Structure</title>
@@ -798,7 +805,7 @@ SELECT (5 !) - 6;
798805
</sect1>
799806

800807
<sect1 id="sql-naming">
801-
<title>Schemas and naming conventions</title>
808+
<title>Schemas and Naming Conventions</title>
802809

803810
<indexterm>
804811
<primary>schemas</primary>
@@ -831,6 +838,9 @@ SELECT (5 !) - 6;
831838
</para>
832839
</note>
833840

841+
<sect2>
842+
<title>Schema Object Names</title>
843+
834844
<para>
835845
A database contains one or more named <firstterm>schemas</>, which
836846
in turn contain tables. Schemas also contain other kinds of named
@@ -944,6 +954,7 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
944954
place <literal>pg_catalog</> at the end of your search path if you
945955
prefer to have user-defined names override built-in names.
946956
</para>
957+
</sect2>
947958

948959
<sect2 id="sql-reserved-names">
949960
<title>Reserved names</title>

0 commit comments

Comments
 (0)