minor doc improvements
От | Neil Conway |
---|---|
Тема | minor doc improvements |
Дата | |
Msg-id | 40465B4B.2080605@samurai.com обсуждение исходный текст |
Ответы |
Re: minor doc improvements
|
Список | pgsql-patches |
I've applied the attached patch to HEAD. It does the following: Add a few more cross-references where appropriate, add more text about the FROM clause and an example to the UPDATE reference page, and make a few other SGML tweaks. Suggestions for further improvement (for example, to the UPDATE ref page) are welcome. -Neil Index: doc/src/sgml/queries.sgml =================================================================== RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/queries.sgml,v retrieving revision 1.28 diff -c -r1.28 queries.sgml *** a/doc/src/sgml/queries.sgml 29 Nov 2003 19:51:37 -0000 1.28 --- b/doc/src/sgml/queries.sgml 3 Mar 2004 21:57:00 -0000 *************** *** 108,115 **** <title>The <literal>FROM</literal> Clause</title> <para> ! The <literal>FROM</> clause derives a table from one or more other ! tables given in a comma-separated table reference list. <synopsis> FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_reference</replaceable> <optional>, ...</optional></optional> </synopsis> --- 108,116 ---- <title>The <literal>FROM</literal> Clause</title> <para> ! The <xref linkend="sql-from" endterm="sql-from-title"> derives a ! table from one or more other tables given in a comma-separated ! table reference list. <synopsis> FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_reference</replaceable> <optional>, ...</optional></optional> </synopsis> *************** *** 677,683 **** </indexterm> <para> ! The syntax of the <literal>WHERE</> clause is <synopsis> WHERE <replaceable>search_condition</replaceable> </synopsis> --- 678,685 ---- </indexterm> <para> ! The syntax of the <xref linkend="sql-where" ! endterm="sql-where-title"> clause is <synopsis> WHERE <replaceable>search_condition</replaceable> </synopsis> *************** *** 783,795 **** </synopsis> <para> ! The <literal>GROUP BY</> clause is used to group together those rows in ! a table that share the same values in all the columns listed. The ! order in which the columns are listed does not matter. The ! purpose is to reduce each group of rows sharing common values into ! one group row that is representative of all rows in the group. ! This is done to eliminate redundancy in the output and/or compute ! aggregates that apply to these groups. For instance: <screen> <prompt>=></> <userinput>SELECT * FROM test1;</> x | y --- 785,798 ---- </synopsis> <para> ! The <xref linkend="sql-groupby" endterm="sql-groupby-title"> is ! used to group together those rows in a table that share the same ! values in all the columns listed. The order in which the columns ! are listed does not matter. The purpose is to reduce each group ! of rows sharing common values into one group row that is ! representative of all rows in the group. This is done to ! eliminate redundancy in the output and/or compute aggregates that ! apply to these groups. For instance: <screen> <prompt>=></> <userinput>SELECT * FROM test1;</> x | y *************** *** 1058,1064 **** <synopsis> SELECT DISTINCT <replaceable>select_list</replaceable> ... </synopsis> ! (Instead of <literal>DISTINCT</> the word <literal>ALL</literal> can be used to select the default behavior of retaining all rows.) </para> --- 1061,1067 ---- <synopsis> SELECT DISTINCT <replaceable>select_list</replaceable> ... </synopsis> ! (Instead of <literal>DISTINCT</> the key word <literal>ALL</literal> can be used to select the default behavior of retaining all rows.) </para> Index: doc/src/sgml/trigger.sgml =================================================================== RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/trigger.sgml,v retrieving revision 1.34 diff -c -r1.34 trigger.sgml *** a/doc/src/sgml/trigger.sgml 22 Jan 2004 19:50:21 -0000 1.34 --- b/doc/src/sgml/trigger.sgml 3 Mar 2004 22:08:16 -0000 *************** *** 449,457 **** <para> The function <function>trigf</> reports the number of rows in the ! table <literal>ttest</> and skips the actual operation if the command attempts to insert a null value into the column ! <literal>x</>. (So the trigger acts as a not-null constraint but doesn't abort the transaction.) </para> --- 449,457 ---- <para> The function <function>trigf</> reports the number of rows in the ! table <structname>ttest</> and skips the actual operation if the command attempts to insert a null value into the column ! <structfield>x</>. (So the trigger acts as a not-null constraint but doesn't abort the transaction.) </para> Index: doc/src/sgml/ref/select.sgml =================================================================== RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/select.sgml,v retrieving revision 1.74 diff -c -r1.74 select.sgml *** a/doc/src/sgml/ref/select.sgml 14 Dec 2003 00:15:03 -0000 1.74 --- b/doc/src/sgml/ref/select.sgml 3 Mar 2004 22:00:04 -0000 *************** *** 174,180 **** </para> <para> ! <literal>FROM</literal>-clause elements can contain: <variablelist> <varlistentry> --- 174,181 ---- </para> <para> ! The <literal>FROM</literal> clause can contain the following ! elements: <variablelist> <varlistentry> *************** *** 289,304 **** A <literal>JOIN</literal> clause combines two <literal>FROM</> items. Use parentheses if necessary to determine the order of nesting. In the absence of parentheses, ! <literal>JOIN</literal>s nest left-to-right. In any case ! <literal>JOIN</literal> binds more tightly than the commas ! separating <literal>FROM</> items. </para> <para> <literal>CROSS JOIN</> and <literal>INNER JOIN</literal> produce a simple Cartesian product, the same result as you get from listing the two items at the top level of <literal>FROM</>, ! but restricted by the join condition (if any). <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON (TRUE)</>, that is, no rows are removed by qualification. These join types are just a notational convenience, since they --- 290,305 ---- A <literal>JOIN</literal> clause combines two <literal>FROM</> items. Use parentheses if necessary to determine the order of nesting. In the absence of parentheses, ! <literal>JOIN</literal>s nest left-to-right. In any case ! <literal>JOIN</literal> binds more tightly than the commas ! separating <literal>FROM</> items. </para> <para> <literal>CROSS JOIN</> and <literal>INNER JOIN</literal> produce a simple Cartesian product, the same result as you get from listing the two items at the top level of <literal>FROM</>, ! but restricted by the join condition (if any). <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON (TRUE)</>, that is, no rows are removed by qualification. These join types are just a notational convenience, since they *************** *** 647,653 **** <literal>INTERSECT</>, or <literal>EXCEPT</> clause may only specify an output column name or number, not an expression. </para> ! <para> If an <literal>ORDER BY</> expression is a simple name that matches both a result column name and an input column name, --- 648,654 ---- <literal>INTERSECT</>, or <literal>EXCEPT</> clause may only specify an output column name or number, not an expression. </para> ! <para> If an <literal>ORDER BY</> expression is a simple name that matches both a result column name and an input column name, Index: doc/src/sgml/ref/update.sgml =================================================================== RCS file: /var/lib/cvs/pgsql-server/doc/src/sgml/ref/update.sgml,v retrieving revision 1.27 diff -c -r1.27 update.sgml *** a/doc/src/sgml/ref/update.sgml 29 Nov 2003 19:51:39 -0000 1.27 --- b/doc/src/sgml/ref/update.sgml 3 Mar 2004 22:20:39 -0000 *************** *** 32,39 **** <para> <command>UPDATE</command> changes the values of the specified columns in all rows that satisfy the condition. Only the columns to ! be modified need be mentioned in the statement; columns not explicitly ! <literal>SET</> retain their previous values. </para> <para> --- 32,39 ---- <para> <command>UPDATE</command> changes the values of the specified columns in all rows that satisfy the condition. Only the columns to ! be modified need be mentioned in the <literal>SET</literal> clause; ! columns not explicitly modified retain their previous values. </para> <para> *************** *** 44,49 **** --- 44,57 ---- </para> <para> + There are two ways to modify a table using information contained in + other tables in the database: using sub-selects, or specifying + additional tables in the <literal>FROM</literal> clause. Which + technique is more appropriate depends on the specific + circumstances. + </para> + + <para> You must have the <literal>UPDATE</literal> privilege on the table to update it, as well as the <literal>SELECT</literal> privilege to any table whose values are read in the *************** *** 99,105 **** <listitem> <para> A list of table expressions, allowing columns from other tables ! to appear in the <literal>WHERE</> condition and the update expressions. </para> </listitem> </varlistentry> --- 107,118 ---- <listitem> <para> A list of table expressions, allowing columns from other tables ! to appear in the <literal>WHERE</> condition and the update ! expressions. This is similar to the list of tables that can be ! specified in the <xref linkend="sql-from" ! endterm="sql-from-title"> of a <command>SELECT</command> ! statement; for example, an alias for the table name can be ! specified. </para> </listitem> </varlistentry> *************** *** 139,145 **** <para> Change the word <literal>Drama</> to <literal>Dramatic</> in the ! column <structfield>kind</> of the table <literal>films</literal>: <programlisting> UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama'; --- 152,158 ---- <para> Change the word <literal>Drama</> to <literal>Dramatic</> in the ! column <structfield>kind</> of the table <structname>films</structname>: <programlisting> UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama'; *************** *** 148,154 **** <para> Adjust temperature entries and reset precipitation to its default ! value in one row of the table <literal>weather</literal>: <programlisting> UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT --- 161,167 ---- <para> Adjust temperature entries and reset precipitation to its default ! value in one row of the table <structname>weather</structname>: <programlisting> UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT *************** *** 156,168 **** </programlisting> </para> </refsect1> <refsect1> <title>Compatibility</title> <para> ! This command conforms to the SQL standard. The <literal>FROM</literal> clause is a <productname>PostgreSQL</productname> extension. </para> --- 169,198 ---- </programlisting> </para> + <para> + Increment the sales count of the salesperson who manages the + account for Acme Corporation, using the <literal>FROM</literal> + clause syntax: + <programlisting> + UPDATE employees SET sales_count = sales_count + 1 FROM accounts + WHERE accounts.name = 'Acme Corporation' + AND employees.id = accounts.sales_person; + </programlisting> + + Perform the same operation, using a sub-select in the + <literal>WHERE</literal> clause: + <programlisting> + UPDATE employees SET sales_count = sales_count + 1 WHERE id = + (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation'); + </programlisting> + </para> </refsect1> <refsect1> <title>Compatibility</title> <para> ! This command conforms to the <acronym>SQL</acronym> standard. The <literal>FROM</literal> clause is a <productname>PostgreSQL</productname> extension. </para>
В списке pgsql-patches по дате отправления: