From 375dcf9c889f78e17ae55aeb346f38c6a71d9211 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 19 Nov 2001 05:37:53 +0000 Subject: [PATCH] Fix a few typos, grammatical problems, etc in new tutorial material. Overall a really nice job here, Peter ... --- doc/src/sgml/advanced.sgml | 8 ++++---- doc/src/sgml/query.sgml | 50 ++++++++++++++++++++++++++-------------------- doc/src/sgml/start.sgml | 14 ++++++------- 3 files changed, 39 insertions(+), 33 deletions(-) diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index de0bf86e8b..165f9d1c8e 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -1,5 +1,5 @@ @@ -10,9 +10,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.22 2001/09/02 23:27:49 pe In the previous chapter we have covered the basics of using - SQL to store and access your data in a + SQL to store and access your data in PostgreSQL. We will now discuss some - more advanced features of SQL that simplify the + more advanced features of SQL that simplify management and prevent loss or corruption of your data. Finally, we will look at some PostgreSQL extensions. @@ -82,7 +82,7 @@ SELECT * FROM myview; - Recall the weather and the + Recall the weather and cities tables from . Consider the following problem: You want to make sure that no one can insert rows in the diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index fce22df2ae..7dd39de589 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -1,5 +1,5 @@ @@ -26,7 +26,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.20 2001/11/08 23:34:33 peter - Examples in this manual can also be found in source distribution + Examples in this manual can also be found in the + PostgreSQL source distribution in the directory src/tutorial/. Refer to the README file in that directory for how to use them. To start the tutorial, do the following: @@ -42,7 +43,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.20 2001/11/08 23:34:33 peter The \i command reads in commands from the - specified files. The -s option puts you in + specified file. The -s option puts you in single step mode which pauses before sending a query to the server. The commands used in this section are in the file basics.sql. @@ -126,7 +127,7 @@ CREATE TABLE weather ( differently than above, or even all on one line. Two dashes (--) introduce comments. Whatever follows them is ignored up to the end of the line. SQL - is also case insensitive about key words and identifiers, except + is case insensitive about key words and identifiers, except when identifiers are double-quoted to preserve the case (not done above). @@ -148,7 +149,7 @@ CREATE TABLE weather ( precision, char(N), varchar(N), date, time, timestamp, and - interval as well as other types of general utility + interval, as well as other types of general utility and a rich set of geometric types. PostgreSQL can be customized with an arbitrary number of user-defined data types. Consequently, type @@ -165,7 +166,7 @@ CREATE TABLE cities ( location point ); - The point type is such a + The point type is an example of a PostgreSQL-specific data type. @@ -221,7 +222,7 @@ INSERT INTO cities VALUES ('San Francisco', '(-194.0, 53.0)'); INSERT INTO weather (city, temp_lo, temp_hi, prcp, date) VALUES ('San Francisco', 43, 57, 0.0, '1994-11-29'); - You can also list the columns in a different order if you wish or + You can list the columns in a different order if you wish or even omit some columns, e.g., unknown precipitation: INSERT INTO weather (date, city, temp_hi, temp_lo) @@ -279,7 +280,7 @@ COPY weather FROM '/home/user/weather.txt'; SELECT * FROM weather; - (where * means all columns) and + (here * means all columns) and the output should be: city | temp_lo | temp_hi | prcp | date @@ -373,9 +374,9 @@ SELECT DISTINCT city of the same or different tables at one time is called a join query. As an example, say you wish to list all the weather records together with the location of the - associated city. In effect, we need to compare the city column of + associated city. To do that, we need to compare the city column of each row of the weather table with the name column of all rows in - the cities table. + the cities table, and select the pairs of rows where these values match. This is only a conceptual model. The actual join may @@ -409,7 +410,7 @@ SELECT * There is no result row for the city of Hayward. This is because there is no matching entry in the cities table for Hayward, so the join - cannot process the rows in the weather table. We will see + ignores the unmatched rows in the weather table. We will see shortly how this can be fixed. @@ -478,7 +479,7 @@ SELECT * found we want some empty values to be substituted for the cities table's columns. This kind of query is called an outer join. (The - joins we have seen to far are inner joins.) The command looks + joins we have seen so far are inner joins.) The command looks like this: @@ -493,12 +494,13 @@ SELECT * (3 rows) - In particular, this query is a left outer + This query is called a left outer join because the table mentioned on the left of the join operator will have each of its rows in the output at least once, whereas the table on the right will only have those rows - output that match some row of the left table, and will have empty - values substituted appropriately. + output that match some row of the left table. When outputting a + left-table row for which there is no right-table match, empty (NULL) + values are substituted for the right-table columns. @@ -605,7 +607,11 @@ SELECT city FROM weather WHERE temp_lo = max(temp_lo); WRONG but this will not work since the aggregate max cannot be used in the - WHERE clause. However, as is often the case + WHERE clause. (This restriction exists because + the WHERE clause determines the rows that will + go into the aggregation stage; so it has to be evaluated before + aggregate functions are computed.) + However, as is often the case the query can be restated to accomplish the intended result; here by using a subquery: @@ -697,7 +703,7 @@ SELECT city, max(temp_lo) - Note that we can apply the city name restriction in + Observe that we can apply the city name restriction in WHERE, since it needs no aggregate. This is more efficient than adding the restriction to HAVING, because we avoid doing the grouping and aggregate calculations @@ -718,7 +724,7 @@ SELECT city, max(temp_lo) UPDATE command. Suppose you discover the temperature readings are all off by 2 degrees as of November 28, you may update the - data as follow: + data as follows: UPDATE weather @@ -758,7 +764,7 @@ SELECT * FROM weather; DELETE FROM weather WHERE city = 'Hayward'; - All weather recording belonging to Hayward are removed. + All weather records belonging to Hayward are removed. SELECT * FROM weather; @@ -779,10 +785,10 @@ SELECT * FROM weather; DELETE FROM tablename; - Without a qualification, DELETE will simply - remove all rows from the given table, leaving it + Without a qualification, DELETE will + remove all rows from the given table, leaving it empty. The system will not request confirmation before - doing this. + doing this! diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index 61ca3a69b3..2e6eddefb6 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -1,5 +1,5 @@ @@ -104,8 +104,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.17 2001/09/02 23:27:49 peter server can be on different hosts. In that case they communicate over a TCP/IP network connection. You should keep this in mind, because the files that can be accessed on a client machine might - not be accessible (or might only be accessed using a different - file name) on the database server machine. + not be accessible (or might only be accessible using a different + file path) on the database server machine. @@ -231,7 +231,7 @@ createdb: database creation failed You can also create databases with other names. PostgreSQL allows you to create any number of databases at a given site. Database names must have an - alphabetic first character and are limited to 32 characters in + alphabetic first character and are limited to 31 characters in length. A convenient choice is to create a database with the same name as your current user name. Many tools assume that database name as the default, so it can save you some typing. To create @@ -372,9 +372,9 @@ mydb=# The psql program has a number of internal - commands that are not SQL commands. They begin the backslash + commands that are not SQL commands. They begin with the backslash character, \. Some of these - commands were already listed in the welcome message. For example, + commands were listed in the welcome message. For example, you can get help on the syntax of various PostgreSQL SQL commands by typing: @@ -396,7 +396,7 @@ mydb=# installed correctly you can also type man psql at the operating system shell prompt to see the documentation. In this tutorial we will not use these features explicitly, but you - can use them yourself when you see it fit. + can use them yourself when you see fit. -- 2.11.0