diff options
| author | Peter Eisentraut | 2017-10-09 01:44:17 +0000 |
|---|---|---|
| committer | Peter Eisentraut | 2017-10-17 19:10:33 +0000 |
| commit | c29c578908dc0271eeb13a4014e54bff07a29c05 (patch) | |
| tree | 1aa03fb6f1864719f2f23d4b0b9d5e2865764082 /doc/src/sgml/ref | |
| parent | 6ecabead4b5993c42745f2802d857b1a79f48bf9 (diff) | |
Don't use SGML empty tags
For DocBook XML compatibility, don't use SGML empty tags (</>) anymore,
replace by the full tag name. Add a warning option to catch future
occurrences.
Alexander Lakhin, Jürgen Purtz
Diffstat (limited to 'doc/src/sgml/ref')
182 files changed, 3770 insertions, 3770 deletions
diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index ed9332c395b..285d0d4ac65 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -63,7 +63,7 @@ ABORT [ WORK | TRANSACTION ] </para> <para> - Issuing <command>ABORT</> outside of a transaction block + Issuing <command>ABORT</command> outside of a transaction block emits a warning and otherwise has no effect. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_aggregate.sgml b/doc/src/sgml/ref/alter_aggregate.sgml index 7b7616ca014..43f0a1609b9 100644 --- a/doc/src/sgml/ref/alter_aggregate.sgml +++ b/doc/src/sgml/ref/alter_aggregate.sgml @@ -43,7 +43,7 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu </para> <para> - You must own the aggregate function to use <command>ALTER AGGREGATE</>. + You must own the aggregate function to use <command>ALTER AGGREGATE</command>. To change the schema of an aggregate function, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -73,8 +73,8 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. </para> </listitem> </varlistentry> @@ -97,10 +97,10 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <listitem> <para> An input data type on which the aggregate function operates. - To reference a zero-argument aggregate function, write <literal>*</> + To reference a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. To reference an ordered-set aggregate function, write - <literal>ORDER BY</> between the direct and aggregated argument + <literal>ORDER BY</literal> between the direct and aggregated argument specifications. </para> </listitem> @@ -140,13 +140,13 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <para> The recommended syntax for referencing an ordered-set aggregate - is to write <literal>ORDER BY</> between the direct and aggregated + is to write <literal>ORDER BY</literal> between the direct and aggregated argument specifications, in the same style as in <xref linkend="sql-createaggregate">. However, it will also work to - omit <literal>ORDER BY</> and just run the direct and aggregated + omit <literal>ORDER BY</literal> and just run the direct and aggregated argument specifications into a single list. In this abbreviated form, - if <literal>VARIADIC "any"</> was used in both the direct and - aggregated argument lists, write <literal>VARIADIC "any"</> only once. + if <literal>VARIADIC "any"</literal> was used in both the direct and + aggregated argument lists, write <literal>VARIADIC "any"</literal> only once. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml index 30e8c756a12..9d77ee5c2c3 100644 --- a/doc/src/sgml/ref/alter_collation.sgml +++ b/doc/src/sgml/ref/alter_collation.sgml @@ -38,7 +38,7 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche </para> <para> - You must own the collation to use <command>ALTER COLLATION</>. + You must own the collation to use <command>ALTER COLLATION</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the collation's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_conversion.sgml b/doc/src/sgml/ref/alter_conversion.sgml index 3514720d03e..83fcbbd5a5d 100644 --- a/doc/src/sgml/ref/alter_conversion.sgml +++ b/doc/src/sgml/ref/alter_conversion.sgml @@ -36,7 +36,7 @@ ALTER CONVERSION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sch </para> <para> - You must own the conversion to use <command>ALTER CONVERSION</>. + You must own the conversion to use <command>ALTER CONVERSION</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the conversion's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml index 59639d37291..35e4123cadd 100644 --- a/doc/src/sgml/ref/alter_database.sgml +++ b/doc/src/sgml/ref/alter_database.sgml @@ -89,7 +89,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL database. Whenever a new session is subsequently started in that database, the specified value becomes the session default value. The database-specific default overrides whatever setting is present - in <filename>postgresql.conf</> or has been received from the + in <filename>postgresql.conf</filename> or has been received from the <command>postgres</command> command line. Only the database owner or a superuser can change the session defaults for a database. Certain variables cannot be set this way, or can only be @@ -183,7 +183,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL database-specific setting is removed, so the system-wide default setting will be inherited in new sessions. Use <literal>RESET ALL</literal> to clear all database-specific settings. - <literal>SET FROM CURRENT</> saves the session's current value of + <literal>SET FROM CURRENT</literal> saves the session's current value of the parameter as the database-specific value. </para> diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml index 09eabda68ac..6c34f2446a7 100644 --- a/doc/src/sgml/ref/alter_default_privileges.sgml +++ b/doc/src/sgml/ref/alter_default_privileges.sgml @@ -88,7 +88,7 @@ REVOKE [ GRANT OPTION FOR ] <title>Description</title> <para> - <command>ALTER DEFAULT PRIVILEGES</> allows you to set the privileges + <command>ALTER DEFAULT PRIVILEGES</command> allows you to set the privileges that will be applied to objects created in the future. (It does not affect privileges assigned to already-existing objects.) Currently, only the privileges for schemas, tables (including views and foreign @@ -109,9 +109,9 @@ REVOKE [ GRANT OPTION FOR ] As explained under <xref linkend="sql-grant">, the default privileges for any object type normally grant all grantable permissions to the object owner, and may grant some privileges to - <literal>PUBLIC</> as well. However, this behavior can be changed by + <literal>PUBLIC</literal> as well. However, this behavior can be changed by altering the global default privileges with - <command>ALTER DEFAULT PRIVILEGES</>. + <command>ALTER DEFAULT PRIVILEGES</command>. </para> <refsect2> @@ -123,7 +123,7 @@ REVOKE [ GRANT OPTION FOR ] <listitem> <para> The name of an existing role of which the current role is a member. - If <literal>FOR ROLE</> is omitted, the current role is assumed. + If <literal>FOR ROLE</literal> is omitted, the current role is assumed. </para> </listitem> </varlistentry> @@ -134,9 +134,9 @@ REVOKE [ GRANT OPTION FOR ] <para> The name of an existing schema. If specified, the default privileges are altered for objects later created in that schema. - If <literal>IN SCHEMA</> is omitted, the global default privileges + If <literal>IN SCHEMA</literal> is omitted, the global default privileges are altered. - <literal>IN SCHEMA</> is not allowed when using <literal>ON SCHEMAS</> + <literal>IN SCHEMA</literal> is not allowed when using <literal>ON SCHEMAS</literal> as schemas can't be nested. </para> </listitem> @@ -148,7 +148,7 @@ REVOKE [ GRANT OPTION FOR ] <para> The name of an existing role to grant or revoke privileges for. This parameter, and all the other parameters in - <replaceable class="parameter">abbreviated_grant_or_revoke</>, + <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>, act as described under <xref linkend="sql-grant"> or <xref linkend="sql-revoke">, @@ -175,7 +175,7 @@ REVOKE [ GRANT OPTION FOR ] <para> If you wish to drop a role for which the default privileges have been altered, it is necessary to reverse the changes in its default privileges - or use <command>DROP OWNED BY</> to get rid of the default privileges entry + or use <command>DROP OWNED BY</command> to get rid of the default privileges entry for the role. </para> </refsect1> @@ -186,7 +186,7 @@ REVOKE [ GRANT OPTION FOR ] <para> Grant SELECT privilege to everyone for all tables (and views) you subsequently create in schema <literal>myschema</literal>, and allow - role <literal>webuser</> to INSERT into them too: + role <literal>webuser</literal> to INSERT into them too: <programlisting> ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLES TO PUBLIC; @@ -206,7 +206,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser <para> Remove the public EXECUTE permission that is normally granted on functions, - for all functions subsequently created by role <literal>admin</>: + for all functions subsequently created by role <literal>admin</literal>: <programlisting> ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC; diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml index 827a1c7d20e..96a7db95ecf 100644 --- a/doc/src/sgml/ref/alter_domain.sgml +++ b/doc/src/sgml/ref/alter_domain.sgml @@ -69,7 +69,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <listitem> <para> These forms change whether a domain is marked to allow NULL - values or to reject NULL values. You can only <literal>SET NOT NULL</> + values or to reject NULL values. You can only <literal>SET NOT NULL</literal> when the columns using the domain contain no null values. </para> </listitem> @@ -88,7 +88,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> valid using <command>ALTER DOMAIN ... VALIDATE CONSTRAINT</command>. Newly inserted or updated rows are always checked against all constraints, even those marked <literal>NOT VALID</literal>. - <literal>NOT VALID</> is only accepted for <literal>CHECK</> constraints. + <literal>NOT VALID</literal> is only accepted for <literal>CHECK</literal> constraints. </para> </listitem> </varlistentry> @@ -118,7 +118,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <listitem> <para> This form validates a constraint previously added as - <literal>NOT VALID</>, that is, verify that all data in columns using the + <literal>NOT VALID</literal>, that is, verify that all data in columns using the domain satisfy the specified constraint. </para> </listitem> @@ -154,7 +154,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> </variablelist> <para> - You must own the domain to use <command>ALTER DOMAIN</>. + You must own the domain to use <command>ALTER DOMAIN</command>. To change the schema of a domain, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -273,8 +273,8 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - Currently, <command>ALTER DOMAIN ADD CONSTRAINT</>, <command>ALTER - DOMAIN VALIDATE CONSTRAINT</>, and <command>ALTER DOMAIN SET NOT NULL</> + Currently, <command>ALTER DOMAIN ADD CONSTRAINT</command>, <command>ALTER + DOMAIN VALIDATE CONSTRAINT</command>, and <command>ALTER DOMAIN SET NOT NULL</command> will fail if the validated named domain or any derived domain is used within a composite-type column of any table in the database. They should eventually be improved to be @@ -330,10 +330,10 @@ ALTER DOMAIN zipcode SET SCHEMA customers; <para> <command>ALTER DOMAIN</command> conforms to the <acronym>SQL</acronym> - standard, except for the <literal>OWNER</>, <literal>RENAME</literal>, <literal>SET SCHEMA</>, and - <literal>VALIDATE CONSTRAINT</> variants, which are - <productname>PostgreSQL</productname> extensions. The <literal>NOT VALID</> - clause of the <literal>ADD CONSTRAINT</> variant is also a + standard, except for the <literal>OWNER</literal>, <literal>RENAME</literal>, <literal>SET SCHEMA</literal>, and + <literal>VALIDATE CONSTRAINT</literal> variants, which are + <productname>PostgreSQL</productname> extensions. The <literal>NOT VALID</literal> + clause of the <literal>ADD CONSTRAINT</literal> variant is also a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml index ae84e98e49a..c6c831fa30a 100644 --- a/doc/src/sgml/ref/alter_extension.sgml +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -89,7 +89,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> This form moves the extension's objects into another schema. The - extension has to be <firstterm>relocatable</> for this command to + extension has to be <firstterm>relocatable</firstterm> for this command to succeed. </para> </listitem> @@ -125,7 +125,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <para> You must own the extension to use <command>ALTER EXTENSION</command>. - The <literal>ADD</>/<literal>DROP</> forms require ownership of the + The <literal>ADD</literal>/<literal>DROP</literal> forms require ownership of the added/dropped object as well. </para> </refsect1> @@ -150,7 +150,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <para> The desired new version of the extension. This can be written as either an identifier or a string literal. If not specified, - <command>ALTER EXTENSION UPDATE</> attempts to update to whatever is + <command>ALTER EXTENSION UPDATE</command> attempts to update to whatever is shown as the default version in the extension's control file. </para> </listitem> @@ -205,14 +205,14 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> The mode of a function or aggregate - argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>ALTER EXTENSION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -246,7 +246,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> The data type(s) of the operator's arguments (optionally - schema-qualified). Write <literal>NONE</> for the missing argument + schema-qualified). Write <literal>NONE</literal> for the missing argument of a prefix or postfix operator. </para> </listitem> @@ -314,7 +314,7 @@ ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore); <title>Compatibility</title> <para> - <command>ALTER EXTENSION</command> is a <productname>PostgreSQL</> + <command>ALTER EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml index 9c5b84fe64d..1c0a26de6ba 100644 --- a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml @@ -93,11 +93,11 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <para> Note that it is possible that pre-existing options of the foreign-data wrapper, or of dependent servers, user mappings, or foreign tables, are - invalid according to the new validator. <productname>PostgreSQL</> does + invalid according to the new validator. <productname>PostgreSQL</productname> does not check for this. It is up to the user to make sure that these options are correct before using the modified foreign-data wrapper. However, any options specified in this <command>ALTER FOREIGN DATA - WRAPPER</> command will be checked using the new validator. + WRAPPER</command> command will be checked using the new validator. </para> </listitem> </varlistentry> @@ -117,8 +117,8 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <listitem> <para> Change options for the foreign-data - wrapper. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + wrapper. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the foreign data wrapper's validator function, if any. @@ -150,16 +150,16 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <title>Examples</title> <para> - Change a foreign-data wrapper <literal>dbi</>, add - option <literal>foo</>, drop <literal>bar</>: + Change a foreign-data wrapper <literal>dbi</literal>, add + option <literal>foo</literal>, drop <literal>bar</literal>: <programlisting> ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP 'bar'); </programlisting> </para> <para> - Change the foreign-data wrapper <literal>dbi</> validator - to <literal>bob.myvalidator</>: + Change the foreign-data wrapper <literal>dbi</literal> validator + to <literal>bob.myvalidator</literal>: <programlisting> ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator; </programlisting></para> @@ -171,7 +171,7 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator; <para> <command>ALTER FOREIGN DATA WRAPPER</command> conforms to ISO/IEC 9075-9 (SQL/MED), except that the <literal>HANDLER</literal>, - <literal>VALIDATOR</>, <literal>OWNER TO</>, and <literal>RENAME</literal> + <literal>VALIDATOR</literal>, <literal>OWNER TO</literal>, and <literal>RENAME</literal> clauses are extensions. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml index cb4e7044fbd..44d981a5bda 100644 --- a/doc/src/sgml/ref/alter_foreign_table.sgml +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -85,7 +85,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> This form drops a column from a foreign table. - You will need to say <literal>CASCADE</> if + You will need to say <literal>CASCADE</literal> if anything outside the table depends on the column; for example, views. If <literal>IF EXISTS</literal> is specified and the column @@ -101,7 +101,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> This form changes the type of a column of a foreign table. Again, this has no effect on any underlying storage: this action simply - changes the type that <productname>PostgreSQL</> believes the column to + changes the type that <productname>PostgreSQL</productname> believes the column to have. </para> </listitem> @@ -113,7 +113,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> These forms set or remove the default value for a column. Default values only apply in subsequent <command>INSERT</command> - or <command>UPDATE</> commands; they do not cause rows already in the + or <command>UPDATE</command> commands; they do not cause rows already in the table to change. </para> </listitem> @@ -174,7 +174,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> This form adds a new constraint to a foreign table, using the same syntax as <xref linkend="SQL-CREATEFOREIGNTABLE">. - Currently only <literal>CHECK</> constraints are supported. + Currently only <literal>CHECK</literal> constraints are supported. </para> <para> @@ -183,7 +183,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab declares that some new condition should be assumed to hold for all rows in the foreign table. (See the discussion in <xref linkend="SQL-CREATEFOREIGNTABLE">.) - If the constraint is marked <literal>NOT VALID</>, then it isn't + If the constraint is marked <literal>NOT VALID</literal>, then it isn't assumed to hold, but is only recorded for possible future use. </para> </listitem> @@ -235,9 +235,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - Note that this is not equivalent to <literal>ADD COLUMN oid oid</>; + Note that this is not equivalent to <literal>ADD COLUMN oid oid</literal>; that would add a normal column that happened to be named - <literal>oid</>, not a system column. + <literal>oid</literal>, not a system column. </para> </listitem> </varlistentry> @@ -292,8 +292,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> Change options for the foreign table or one of its columns. - <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Duplicate option names are not allowed (although it's OK for a table option and a column option to have the same name). Option names and values are also validated using the @@ -325,7 +325,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</> + All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</literal> can be combined into a list of multiple alterations to apply in parallel. For example, it is possible to add several columns and/or alter the type of several @@ -333,13 +333,13 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - If the command is written as <literal>ALTER FOREIGN TABLE IF EXISTS ...</> + If the command is written as <literal>ALTER FOREIGN TABLE IF EXISTS ...</literal> and the foreign table does not exist, no error is thrown. A notice is issued in this case. </para> <para> - You must own the table to use <command>ALTER FOREIGN TABLE</>. + You must own the table to use <command>ALTER FOREIGN TABLE</command>. To change the schema of a foreign table, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -362,10 +362,10 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> The name (possibly schema-qualified) of an existing foreign table to - alter. If <literal>ONLY</> is specified before the table name, only - that table is altered. If <literal>ONLY</> is not specified, the table + alter. If <literal>ONLY</literal> is specified before the table name, only + that table is altered. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are altered. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -518,9 +518,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> Consistency with the foreign server is not checked when a column is added or removed with <literal>ADD COLUMN</literal> or - <literal>DROP COLUMN</literal>, a <literal>NOT NULL</> - or <literal>CHECK</> constraint is added, or a column type is changed - with <literal>SET DATA TYPE</>. It is the user's responsibility to ensure + <literal>DROP COLUMN</literal>, a <literal>NOT NULL</literal> + or <literal>CHECK</literal> constraint is added, or a column type is changed + with <literal>SET DATA TYPE</literal>. It is the user's responsibility to ensure that the table definition matches the remote side. </para> @@ -552,16 +552,16 @@ ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'v <title>Compatibility</title> <para> - The forms <literal>ADD</literal>, <literal>DROP</>, + The forms <literal>ADD</literal>, <literal>DROP</literal>, and <literal>SET DATA TYPE</literal> conform with the SQL standard. The other forms are <productname>PostgreSQL</productname> extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single - <command>ALTER FOREIGN TABLE</> command is an extension. + <command>ALTER FOREIGN TABLE</command> command is an extension. </para> <para> - <command>ALTER FOREIGN TABLE DROP COLUMN</> can be used to drop the only + <command>ALTER FOREIGN TABLE DROP COLUMN</command> can be used to drop the only column of a foreign table, leaving a zero-column table. This is an extension of SQL, which disallows zero-column foreign tables. </para> diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml index 8d9fec6005a..cdecf631b1e 100644 --- a/doc/src/sgml/ref/alter_function.sgml +++ b/doc/src/sgml/ref/alter_function.sgml @@ -56,8 +56,8 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param </para> <para> - You must own the function to use <command>ALTER FUNCTION</>. - To change a function's schema, you must also have <literal>CREATE</> + You must own the function to use <command>ALTER FUNCTION</command>. + To change a function's schema, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on @@ -86,14 +86,14 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>ALTER FUNCTION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -260,8 +260,8 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param setting is removed, so that the function executes with the value present in its environment. Use <literal>RESET ALL</literal> to clear all function-local settings. - <literal>SET FROM CURRENT</> saves the value of the parameter that - is current when <command>ALTER FUNCTION</> is executed as the value + <literal>SET FROM CURRENT</literal> saves the value of the parameter that + is current when <command>ALTER FUNCTION</command> is executed as the value to be applied when the function is entered. </para> @@ -329,7 +329,7 @@ ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp; </para> <para> - To disable automatic setting of <varname>search_path</> for a function: + To disable automatic setting of <varname>search_path</varname> for a function: <programlisting> ALTER FUNCTION check_password(text) RESET search_path; </programlisting> @@ -343,13 +343,13 @@ ALTER FUNCTION check_password(text) RESET search_path; <para> This statement is partially compatible with the <command>ALTER - FUNCTION</> statement in the SQL standard. The standard allows more + FUNCTION</command> statement in the SQL standard. The standard allows more properties of a function to be modified, but does not provide the ability to rename a function, make a function a security definer, attach configuration parameter values to a function, or change the owner, schema, or volatility of a function. The standard also - requires the <literal>RESTRICT</> key word, which is optional in - <productname>PostgreSQL</>. + requires the <literal>RESTRICT</literal> key word, which is optional in + <productname>PostgreSQL</productname>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml index f7136c773a7..a9001458731 100644 --- a/doc/src/sgml/ref/alter_group.sgml +++ b/doc/src/sgml/ref/alter_group.sgml @@ -46,10 +46,10 @@ ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <r <para> The first two variants add users to a group or remove them from a group. - (Any role can play the part of either a <quote>user</> or a - <quote>group</> for this purpose.) These variants are effectively + (Any role can play the part of either a <quote>user</quote> or a + <quote>group</quote> for this purpose.) These variants are effectively equivalent to granting or revoking membership in the role named as the - <quote>group</>; so the preferred way to do this is to use + <quote>group</quote>; so the preferred way to do this is to use <xref linkend="SQL-GRANT"> or <xref linkend="SQL-REVOKE">. </para> @@ -79,7 +79,7 @@ ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <r <listitem> <para> Users (roles) that are to be added to or removed from the group. - The users must already exist; <command>ALTER GROUP</> does not + The users must already exist; <command>ALTER GROUP</command> does not create or drop users. </para> </listitem> diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml index 4c777f86752..30e399e62c8 100644 --- a/doc/src/sgml/ref/alter_index.sgml +++ b/doc/src/sgml/ref/alter_index.sgml @@ -106,7 +106,7 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> <listitem> <para> This form resets one or more index-method-specific storage parameters to - their defaults. As with <literal>SET</>, a <literal>REINDEX</literal> + their defaults. As with <literal>SET</literal>, a <literal>REINDEX</literal> might be needed to update the index entirely. </para> </listitem> @@ -226,12 +226,12 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> <para> These operations are also possible using <xref linkend="SQL-ALTERTABLE">. - <command>ALTER INDEX</> is in fact just an alias for the forms - of <command>ALTER TABLE</> that apply to indexes. + <command>ALTER INDEX</command> is in fact just an alias for the forms + of <command>ALTER TABLE</command> that apply to indexes. </para> <para> - There was formerly an <command>ALTER INDEX OWNER</> variant, but + There was formerly an <command>ALTER INDEX OWNER</command> variant, but this is now ignored (with a warning). An index cannot have an owner different from its table's owner. Changing the table's owner automatically changes the index as well. @@ -280,7 +280,7 @@ ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000; <title>Compatibility</title> <para> - <command>ALTER INDEX</> is a <productname>PostgreSQL</productname> + <command>ALTER INDEX</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_materialized_view.sgml b/doc/src/sgml/ref/alter_materialized_view.sgml index a1cced1581c..eaea819744a 100644 --- a/doc/src/sgml/ref/alter_materialized_view.sgml +++ b/doc/src/sgml/ref/alter_materialized_view.sgml @@ -58,8 +58,8 @@ ALTER MATERIALIZED VIEW ALL IN TABLESPACE <replaceable class="parameter">name</r <para> You must own the materialized view to use <command>ALTER MATERIALIZED - VIEW</>. To change a materialized view's schema, you must also have - <literal>CREATE</> privilege on the new schema. + VIEW</command>. To change a materialized view's schema, you must also have + <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the materialized view's schema. (These restrictions enforce that altering diff --git a/doc/src/sgml/ref/alter_opclass.sgml b/doc/src/sgml/ref/alter_opclass.sgml index 58de603aa46..834f3e4231d 100644 --- a/doc/src/sgml/ref/alter_opclass.sgml +++ b/doc/src/sgml/ref/alter_opclass.sgml @@ -41,7 +41,7 @@ ALTER OPERATOR CLASS <replaceable>name</replaceable> USING <replaceable class="p </para> <para> - You must own the operator class to use <command>ALTER OPERATOR CLASS</>. + You must own the operator class to use <command>ALTER OPERATOR CLASS</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the operator class's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_operator.sgml b/doc/src/sgml/ref/alter_operator.sgml index 9579d00b786..3cc28d5b18a 100644 --- a/doc/src/sgml/ref/alter_operator.sgml +++ b/doc/src/sgml/ref/alter_operator.sgml @@ -43,7 +43,7 @@ ALTER OPERATOR <replaceable>name</replaceable> ( { <replaceable>left_type</repla </para> <para> - You must own the operator to use <command>ALTER OPERATOR</>. + You must own the operator to use <command>ALTER OPERATOR</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the operator's schema. (These restrictions enforce that altering the owner diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml index 0bafe5b8f80..d15fbfceea8 100644 --- a/doc/src/sgml/ref/alter_opfamily.sgml +++ b/doc/src/sgml/ref/alter_opfamily.sgml @@ -57,7 +57,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <para> When operators and support functions are added to a family with <command>ALTER OPERATOR FAMILY</command>, they are not part of any - specific operator class within the family, but are just <quote>loose</> + specific operator class within the family, but are just <quote>loose</quote> within the family. This indicates that these operators and functions are compatible with the family's semantics, but are not required for correct functioning of any specific index. (Operators and functions @@ -74,7 +74,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - You must be a superuser to use <command>ALTER OPERATOR FAMILY</>. + You must be a superuser to use <command>ALTER OPERATOR FAMILY</command>. (This restriction is made because an erroneous operator family definition could confuse or even crash the server.) </para> @@ -139,15 +139,15 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <term><replaceable class="parameter">op_type</replaceable></term> <listitem> <para> - In an <literal>OPERATOR</> clause, - the operand data type(s) of the operator, or <literal>NONE</> to + In an <literal>OPERATOR</literal> clause, + the operand data type(s) of the operator, or <literal>NONE</literal> to signify a left-unary or right-unary operator. Unlike the comparable - syntax in <command>CREATE OPERATOR CLASS</>, the operand data types + syntax in <command>CREATE OPERATOR CLASS</command>, the operand data types must always be specified. </para> <para> - In an <literal>ADD FUNCTION</> clause, the operand data type(s) the + In an <literal>ADD FUNCTION</literal> clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function. For B-tree comparison functions and hash functions it is not necessary to specify <replaceable @@ -159,7 +159,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - In a <literal>DROP FUNCTION</> clause, the operand data type(s) the + In a <literal>DROP FUNCTION</literal> clause, the operand data type(s) the function is intended to support must be specified. </para> </listitem> @@ -175,8 +175,8 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - If neither <literal>FOR SEARCH</> nor <literal>FOR ORDER BY</> is - specified, <literal>FOR SEARCH</> is the default. + If neither <literal>FOR SEARCH</literal> nor <literal>FOR ORDER BY</literal> is + specified, <literal>FOR SEARCH</literal> is the default. </para> </listitem> </varlistentry> @@ -240,7 +240,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </variablelist> <para> - The <literal>OPERATOR</> and <literal>FUNCTION</> + The <literal>OPERATOR</literal> and <literal>FUNCTION</literal> clauses can appear in any order. </para> @@ -250,10 +250,10 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <title>Notes</title> <para> - Notice that the <literal>DROP</> syntax only specifies the <quote>slot</> + Notice that the <literal>DROP</literal> syntax only specifies the <quote>slot</quote> in the operator family, by strategy or support number and input data type(s). The name of the operator or function occupying the slot is not - mentioned. Also, for <literal>DROP FUNCTION</> the type(s) to specify + mentioned. Also, for <literal>DROP FUNCTION</literal> the type(s) to specify are the input data type(s) the function is intended to support; for GiST, SP-GiST and GIN indexes this might have nothing to do with the actual input argument types of the function. @@ -274,9 +274,9 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</> - clause could include a <literal>RECHECK</> option. This is no longer - supported because whether an index operator is <quote>lossy</> is now + Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</literal> + clause could include a <literal>RECHECK</literal> option. This is no longer + supported because whether an index operator is <quote>lossy</quote> is now determined on-the-fly at run time. This allows efficient handling of cases where an operator might or might not be lossy. </para> @@ -288,7 +288,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <para> The following example command adds cross-data-type operators and support functions to an operator family that already contains B-tree - operator classes for data types <type>int4</> and <type>int2</>. + operator classes for data types <type>int4</type> and <type>int2</type>. </para> <programlisting> diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml index 7392e6f3de2..801404e0cf9 100644 --- a/doc/src/sgml/ref/alter_publication.sgml +++ b/doc/src/sgml/ref/alter_publication.sgml @@ -87,10 +87,10 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r <term><replaceable class="parameter">table_name</replaceable></term> <listitem> <para> - Name of an existing table. If <literal>ONLY</> is specified before the - table name, only that table is affected. If <literal>ONLY</> is not + Name of an existing table. If <literal>ONLY</literal> is specified before the + table name, only that table is affected. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are - affected. Optionally, <literal>*</> can be specified after the table + affected. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -147,7 +147,7 @@ ALTER PUBLICATION mypublication ADD TABLE users, departments; <title>Compatibility</title> <para> - <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</> + <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml index 607b25962f0..e30ca104549 100644 --- a/doc/src/sgml/ref/alter_role.sgml +++ b/doc/src/sgml/ref/alter_role.sgml @@ -69,7 +69,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <xref linkend="SQL-REVOKE"> for that.) Attributes not mentioned in the command retain their previous settings. Database superusers can change any of these settings for any role. - Roles having <literal>CREATEROLE</> privilege can change any of these + Roles having <literal>CREATEROLE</literal> privilege can change any of these settings, but only for non-superuser and non-replication roles. Ordinary roles can only change their own password. </para> @@ -77,13 +77,13 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <para> The second variant changes the name of the role. Database superusers can rename any role. - Roles having <literal>CREATEROLE</> privilege can rename non-superuser + Roles having <literal>CREATEROLE</literal> privilege can rename non-superuser roles. The current session user cannot be renamed. (Connect as a different user if you need to do that.) - Because <literal>MD5</>-encrypted passwords use the role name as + Because <literal>MD5</literal>-encrypted passwords use the role name as cryptographic salt, renaming a role clears its password if the - password is <literal>MD5</>-encrypted. + password is <literal>MD5</literal>-encrypted. </para> <para> @@ -100,7 +100,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in - <filename>postgresql.conf</> or has been received from the <command>postgres</command> + <filename>postgresql.conf</filename> or has been received from the <command>postgres</command> command line. This only happens at login time; executing <xref linkend="sql-set-role"> or <xref linkend="sql-set-session-authorization"> does not cause new @@ -112,7 +112,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <para> Superusers can change anyone's session defaults. Roles having - <literal>CREATEROLE</> privilege can change defaults for non-superuser + <literal>CREATEROLE</literal> privilege can change defaults for non-superuser roles. Ordinary roles can only set defaults for themselves. Certain configuration variables cannot be set this way, or can only be set if a superuser issues the command. Only superusers can change a setting @@ -155,8 +155,8 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <varlistentry> <term><literal>SUPERUSER</literal></term> <term><literal>NOSUPERUSER</literal></term> - <term><literal>CREATEDB</></term> - <term><literal>NOCREATEDB</></term> + <term><literal>CREATEDB</literal></term> + <term><literal>NOCREATEDB</literal></term> <term><literal>CREATEROLE</literal></term> <term><literal>NOCREATEROLE</literal></term> <term><literal>INHERIT</literal></term> @@ -168,7 +168,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <term><literal>BYPASSRLS</literal></term> <term><literal>NOBYPASSRLS</literal></term> <term><literal>CONNECTION LIMIT</literal> <replaceable class="parameter">connlimit</replaceable></term> - <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> + <term>[ <literal>ENCRYPTED</literal> ] <literal>PASSWORD</literal> <replaceable class="parameter">password</replaceable></term> <term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term> <listitem> <para> @@ -209,7 +209,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A role-specific variable setting is removed, so the role will inherit the system-wide default setting in new sessions. Use <literal>RESET ALL</literal> to clear all role-specific settings. - <literal>SET FROM CURRENT</> saves the session's current value of + <literal>SET FROM CURRENT</literal> saves the session's current value of the parameter as the role-specific value. If <literal>IN DATABASE</literal> is specified, the configuration parameter is set or removed for the given role and database only. @@ -288,7 +288,7 @@ ALTER ROLE davide WITH PASSWORD NULL; <para> Change a password expiration date, specifying that the password should expire at midday on 4th May 2015 using - the time zone which is one hour ahead of <acronym>UTC</>: + the time zone which is one hour ahead of <acronym>UTC</acronym>: <programlisting> ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1'; </programlisting> diff --git a/doc/src/sgml/ref/alter_schema.sgml b/doc/src/sgml/ref/alter_schema.sgml index dbc5c2d45f5..2ca406b9148 100644 --- a/doc/src/sgml/ref/alter_schema.sgml +++ b/doc/src/sgml/ref/alter_schema.sgml @@ -34,7 +34,7 @@ ALTER SCHEMA <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</ </para> <para> - You must own the schema to use <command>ALTER SCHEMA</>. + You must own the schema to use <command>ALTER SCHEMA</command>. To rename a schema you must also have the <literal>CREATE</literal> privilege for the database. To alter the owner, you must also be a direct or diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml index c505935fcc2..9b8ad365227 100644 --- a/doc/src/sgml/ref/alter_sequence.sgml +++ b/doc/src/sgml/ref/alter_sequence.sgml @@ -47,8 +47,8 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </para> <para> - You must own the sequence to use <command>ALTER SEQUENCE</>. - To change a sequence's schema, you must also have <literal>CREATE</> + You must own the sequence to use <command>ALTER SEQUENCE</command>. + To change a sequence's schema, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on @@ -159,8 +159,8 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S The optional clause <literal>START WITH <replaceable class="parameter">start</replaceable></literal> changes the recorded start value of the sequence. This has no effect on the - <emphasis>current</> sequence value; it simply sets the value - that future <command>ALTER SEQUENCE RESTART</> commands will use. + <emphasis>current</emphasis> sequence value; it simply sets the value + that future <command>ALTER SEQUENCE RESTART</command> commands will use. </para> </listitem> </varlistentry> @@ -172,13 +172,13 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S The optional clause <literal>RESTART [ WITH <replaceable class="parameter">restart</replaceable> ]</literal> changes the current value of the sequence. This is similar to calling the - <function>setval</> function with <literal>is_called</literal> = - <literal>false</>: the specified value will be returned by the - <emphasis>next</> call of <function>nextval</>. - Writing <literal>RESTART</> with no <replaceable - class="parameter">restart</> value is equivalent to supplying - the start value that was recorded by <command>CREATE SEQUENCE</> - or last set by <command>ALTER SEQUENCE START WITH</>. + <function>setval</function> function with <literal>is_called</literal> = + <literal>false</literal>: the specified value will be returned by the + <emphasis>next</emphasis> call of <function>nextval</function>. + Writing <literal>RESTART</literal> with no <replaceable + class="parameter">restart</replaceable> value is equivalent to supplying + the start value that was recorded by <command>CREATE SEQUENCE</command> + or last set by <command>ALTER SEQUENCE START WITH</command>. </para> <para> @@ -186,7 +186,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S a <literal>RESTART</literal> operation on a sequence is transactional and blocks concurrent transactions from obtaining numbers from the same sequence. If that's not the desired mode of - operation, <function>setval</> should be used. + operation, <function>setval</function> should be used. </para> </listitem> </varlistentry> @@ -250,7 +250,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S table must have the same owner and be in the same schema as the sequence. Specifying <literal>OWNED BY NONE</literal> removes any existing - association, making the sequence <quote>free-standing</>. + association, making the sequence <quote>free-standing</quote>. </para> </listitem> </varlistentry> @@ -291,7 +291,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S <para> <command>ALTER SEQUENCE</command> will not immediately affect - <function>nextval</> results in backends, + <function>nextval</function> results in backends, other than the current one, that have preallocated (cached) sequence values. They will use up all cached values prior to noticing the changed sequence generation parameters. The current backend will be affected @@ -299,7 +299,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </para> <para> - <command>ALTER SEQUENCE</command> does not affect the <function>currval</> + <command>ALTER SEQUENCE</command> does not affect the <function>currval</function> status for the sequence. (Before <productname>PostgreSQL</productname> 8.3, it sometimes did.) </para> @@ -332,8 +332,8 @@ ALTER SEQUENCE serial RESTART WITH 105; <para> <command>ALTER SEQUENCE</command> conforms to the <acronym>SQL</acronym> - standard, except for the <literal>AS</literal>, <literal>START WITH</>, - <literal>OWNED BY</>, <literal>OWNER TO</>, <literal>RENAME TO</>, and + standard, except for the <literal>AS</literal>, <literal>START WITH</literal>, + <literal>OWNED BY</literal>, <literal>OWNER TO</literal>, <literal>RENAME TO</literal>, and <literal>SET SCHEMA</literal> clauses, which are <productname>PostgreSQL</productname> extensions. </para> diff --git a/doc/src/sgml/ref/alter_server.sgml b/doc/src/sgml/ref/alter_server.sgml index 7f5def30a40..05e11f5ef28 100644 --- a/doc/src/sgml/ref/alter_server.sgml +++ b/doc/src/sgml/ref/alter_server.sgml @@ -42,7 +42,7 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac To alter the server you must be the owner of the server. Additionally to alter the owner, you must own the server and also be a direct or indirect member of the new owning role, and you must - have <literal>USAGE</> privilege on the server's foreign-data + have <literal>USAGE</literal> privilege on the server's foreign-data wrapper. (Note that superusers satisfy all these criteria automatically.) </para> @@ -75,8 +75,8 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac <listitem> <para> Change options for the - server. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + server. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the server's foreign-data wrapper library. @@ -108,15 +108,15 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac <title>Examples</title> <para> - Alter server <literal>foo</>, add connection options: + Alter server <literal>foo</literal>, add connection options: <programlisting> ALTER SERVER foo OPTIONS (host 'foo', dbname 'foodb'); </programlisting> </para> <para> - Alter server <literal>foo</>, change version, - change <literal>host</> option: + Alter server <literal>foo</literal>, change version, + change <literal>host</literal> option: <programlisting> ALTER SERVER foo VERSION '8.4' OPTIONS (SET host 'baz'); </programlisting></para> diff --git a/doc/src/sgml/ref/alter_statistics.sgml b/doc/src/sgml/ref/alter_statistics.sgml index db4f2f0d523..87acb879b03 100644 --- a/doc/src/sgml/ref/alter_statistics.sgml +++ b/doc/src/sgml/ref/alter_statistics.sgml @@ -39,9 +39,9 @@ ALTER STATISTICS <replaceable class="parameter">name</replaceable> SET SCHEMA <r </para> <para> - You must own the statistics object to use <command>ALTER STATISTICS</>. + You must own the statistics object to use <command>ALTER STATISTICS</command>. To change a statistics object's schema, you must also - have <literal>CREATE</> privilege on the new schema. + have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the statistics object's schema. (These restrictions enforce that altering diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml index 44c0b350692..b76a21f6545 100644 --- a/doc/src/sgml/ref/alter_subscription.sgml +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -42,7 +42,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO < </para> <para> - You must own the subscription to use <command>ALTER SUBSCRIPTION</>. + You must own the subscription to use <command>ALTER SUBSCRIPTION</command>. To alter the owner, you must also be a direct or indirect member of the new owning role. The new owner has to be a superuser. (Currently, all subscription owners must be superusers, so the owner checks @@ -211,7 +211,7 @@ ALTER SUBSCRIPTION mysub DISABLE; <title>Compatibility</title> <para> - <command>ALTER SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>ALTER SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml index e3a4af4041f..b8ef117b7d7 100644 --- a/doc/src/sgml/ref/alter_system.sgml +++ b/doc/src/sgml/ref/alter_system.sgml @@ -50,8 +50,8 @@ ALTER SYSTEM RESET ALL the next server configuration reload, or after the next server restart in the case of parameters that can only be changed at server start. A server configuration reload can be commanded by calling the SQL - function <function>pg_reload_conf()</>, running <literal>pg_ctl reload</>, - or sending a <systemitem>SIGHUP</> signal to the main server process. + function <function>pg_reload_conf()</function>, running <literal>pg_ctl reload</literal>, + or sending a <systemitem>SIGHUP</systemitem> signal to the main server process. </para> <para> @@ -95,8 +95,8 @@ ALTER SYSTEM RESET ALL <para> This command can't be used to set <xref linkend="guc-data-directory">, - nor parameters that are not allowed in <filename>postgresql.conf</> - (e.g., <link linkend="runtime-config-preset">preset options</>). + nor parameters that are not allowed in <filename>postgresql.conf</filename> + (e.g., <link linkend="runtime-config-preset">preset options</link>). </para> <para> @@ -108,7 +108,7 @@ ALTER SYSTEM RESET ALL <title>Examples</title> <para> - Set the <literal>wal_level</>: + Set the <literal>wal_level</literal>: <programlisting> ALTER SYSTEM SET wal_level = replica; </programlisting> @@ -116,7 +116,7 @@ ALTER SYSTEM SET wal_level = replica; <para> Undo that, restoring whatever setting was effective - in <filename>postgresql.conf</>: + in <filename>postgresql.conf</filename>: <programlisting> ALTER SYSTEM RESET wal_level; </programlisting></para> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 0559f80549d..68393d70b41 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -126,7 +126,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> Multivariate statistics referencing the dropped column will also be removed if the removal of the column would cause the statistics to contain data for only a single column. - You will need to say <literal>CASCADE</> if anything outside the table + You will need to say <literal>CASCADE</literal> if anything outside the table depends on the column, for example, foreign key references or views. If <literal>IF EXISTS</literal> is specified and the column does not exist, no error is thrown. In this case a notice @@ -162,7 +162,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> These forms set or remove the default value for a column. Default values only apply in subsequent <command>INSERT</command> - or <command>UPDATE</> commands; they do not cause rows already in the + or <command>UPDATE</command> commands; they do not cause rows already in the table to change. </para> </listitem> @@ -174,7 +174,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> These forms change whether a column is marked to allow null values or to reject null values. You can only use <literal>SET - NOT NULL</> when the column contains no null values. + NOT NULL</literal> when the column contains no null values. </para> <para> @@ -182,7 +182,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> on a column if it is marked <literal>NOT NULL</literal> in the parent table. To drop the <literal>NOT NULL</literal> constraint from all the partitions, perform <literal>DROP NOT NULL</literal> on the parent - table. Even if there is no <literal>NOT NULL</> constraint on the + table. Even if there is no <literal>NOT NULL</literal> constraint on the parent, such a constraint can still be added to individual partitions, if desired; that is, the children can disallow nulls even if the parent allows them, but not the other way around. @@ -249,17 +249,17 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form sets or resets per-attribute options. Currently, the only - defined per-attribute options are <literal>n_distinct</> and - <literal>n_distinct_inherited</>, which override the + defined per-attribute options are <literal>n_distinct</literal> and + <literal>n_distinct_inherited</literal>, which override the number-of-distinct-values estimates made by subsequent <xref linkend="sql-analyze"> - operations. <literal>n_distinct</> affects the statistics for the table - itself, while <literal>n_distinct_inherited</> affects the statistics + operations. <literal>n_distinct</literal> affects the statistics for the table + itself, while <literal>n_distinct_inherited</literal> affects the statistics gathered for the table plus its inheritance children. When set to a - positive value, <command>ANALYZE</> will assume that the column contains + positive value, <command>ANALYZE</command> will assume that the column contains exactly the specified number of distinct nonnull values. When set to a negative value, which must be greater - than or equal to -1, <command>ANALYZE</> will assume that the number of + than or equal to -1, <command>ANALYZE</command> will assume that the number of distinct nonnull values in the column is linear in the size of the table; the exact count is to be computed by multiplying the estimated table size by the absolute value of the given number. For example, @@ -290,7 +290,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form sets the storage mode for a column. This controls whether this - column is held inline or in a secondary <acronym>TOAST</> table, and + column is held inline or in a secondary <acronym>TOAST</acronym> table, and whether the data should be compressed or not. <literal>PLAIN</literal> must be used for fixed-length values such as <type>integer</type> and is @@ -302,7 +302,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> Use of <literal>EXTERNAL</literal> will make substring operations on very large <type>text</type> and <type>bytea</type> values run faster, at the penalty of increased storage space. Note that - <literal>SET STORAGE</> doesn't itself change anything in the table, + <literal>SET STORAGE</literal> doesn't itself change anything in the table, it just sets the strategy to be pursued during future table updates. See <xref linkend="storage-toast"> for more information. </para> @@ -335,7 +335,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <term><literal>ADD <replaceable class="parameter">table_constraint_using_index</replaceable></literal></term> <listitem> <para> - This form adds a new <literal>PRIMARY KEY</> or <literal>UNIQUE</> + This form adds a new <literal>PRIMARY KEY</literal> or <literal>UNIQUE</literal> constraint to a table based on an existing unique index. All the columns of the index will be included in the constraint. </para> @@ -344,14 +344,14 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> The index cannot have expression columns nor be a partial index. Also, it must be a b-tree index with default sort ordering. These restrictions ensure that the index is equivalent to one that would be - built by a regular <literal>ADD PRIMARY KEY</> or <literal>ADD UNIQUE</> + built by a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal> command. </para> <para> - If <literal>PRIMARY KEY</> is specified, and the index's columns are not - already marked <literal>NOT NULL</>, then this command will attempt to - do <literal>ALTER COLUMN SET NOT NULL</> against each such column. + If <literal>PRIMARY KEY</literal> is specified, and the index's columns are not + already marked <literal>NOT NULL</literal>, then this command will attempt to + do <literal>ALTER COLUMN SET NOT NULL</literal> against each such column. That requires a full table scan to verify the column(s) contain no nulls. In all other cases, this is a fast operation. </para> @@ -363,9 +363,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - After this command is executed, the index is <quote>owned</> by the + After this command is executed, the index is <quote>owned</quote> by the constraint, in the same way as if the index had been built by - a regular <literal>ADD PRIMARY KEY</> or <literal>ADD UNIQUE</> + a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal> command. In particular, dropping the constraint will make the index disappear too. </para> @@ -375,7 +375,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> Adding a constraint using an existing index can be helpful in situations where a new constraint needs to be added without blocking table updates for a long time. To do that, create the index using - <command>CREATE INDEX CONCURRENTLY</>, and then install it as an + <command>CREATE INDEX CONCURRENTLY</command>, and then install it as an official constraint using this syntax. See the example below. </para> </note> @@ -447,9 +447,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> triggers are not executed. The trigger firing mechanism is also affected by the configuration variable <xref linkend="guc-session-replication-role">. Simply enabled - triggers will fire when the replication role is <quote>origin</> - (the default) or <quote>local</>. Triggers configured as <literal>ENABLE - REPLICA</literal> will only fire if the session is in <quote>replica</> + triggers will fire when the replication role is <quote>origin</quote> + (the default) or <quote>local</quote>. Triggers configured as <literal>ENABLE + REPLICA</literal> will only fire if the session is in <quote>replica</quote> mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will fire regardless of the current replication mode. </para> @@ -542,9 +542,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - Note that this is not equivalent to <literal>ADD COLUMN oid oid</>; + Note that this is not equivalent to <literal>ADD COLUMN oid oid</literal>; that would add a normal column that happened to be named - <literal>oid</>, not a system column. + <literal>oid</literal>, not a system column. </para> </listitem> </varlistentry> @@ -609,8 +609,8 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> will not be modified immediately by this command; depending on the parameter you might need to rewrite the table to get the desired effects. That can be done with <link linkend="SQL-VACUUM">VACUUM - FULL</>, <xref linkend="SQL-CLUSTER"> or one of the forms - of <command>ALTER TABLE</> that forces a table rewrite. + FULL</link>, <xref linkend="SQL-CLUSTER"> or one of the forms + of <command>ALTER TABLE</command> that forces a table rewrite. For planner related parameters, changes will take effect from the next time the table is locked so currently executing queries will not be affected. @@ -620,18 +620,18 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for fillfactor and autovacuum storage parameters, as well as the following planner related parameters: - <varname>effective_io_concurrency</>, <varname>parallel_workers</>, <varname>seq_page_cost</>, - <varname>random_page_cost</>, <varname>n_distinct</> and <varname>n_distinct_inherited</>. + <varname>effective_io_concurrency</varname>, <varname>parallel_workers</varname>, <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname>, <varname>n_distinct</varname> and <varname>n_distinct_inherited</varname>. </para> <note> <para> - While <command>CREATE TABLE</> allows <literal>OIDS</> to be specified + While <command>CREATE TABLE</command> allows <literal>OIDS</literal> to be specified in the <literal>WITH (<replaceable - class="parameter">storage_parameter</>)</literal> syntax, - <command>ALTER TABLE</> does not treat <literal>OIDS</> as a - storage parameter. Instead use the <literal>SET WITH OIDS</> - and <literal>SET WITHOUT OIDS</> forms to change OID status. + class="parameter">storage_parameter</replaceable>)</literal> syntax, + <command>ALTER TABLE</command> does not treat <literal>OIDS</literal> as a + storage parameter. Instead use the <literal>SET WITH OIDS</literal> + and <literal>SET WITHOUT OIDS</literal> forms to change OID status. </para> </note> </listitem> @@ -642,7 +642,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form resets one or more storage parameters to their - defaults. As with <literal>SET</>, a table rewrite might be + defaults. As with <literal>SET</literal>, a table rewrite might be needed to update the table entirely. </para> </listitem> @@ -693,11 +693,11 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form links the table to a composite type as though <command>CREATE - TABLE OF</> had formed it. The table's list of column names and types + TABLE OF</command> had formed it. The table's list of column names and types must precisely match that of the composite type; the presence of - an <literal>oid</> system column is permitted to differ. The table must + an <literal>oid</literal> system column is permitted to differ. The table must not inherit from any other table. These restrictions ensure - that <command>CREATE TABLE OF</> would permit an equivalent table + that <command>CREATE TABLE OF</command> would permit an equivalent table definition. </para> </listitem> @@ -728,13 +728,13 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> This form changes the information which is written to the write-ahead log to identify rows which are updated or deleted. This option has no effect - except when logical replication is in use. <literal>DEFAULT</> + except when logical replication is in use. <literal>DEFAULT</literal> (the default for non-system tables) records the - old values of the columns of the primary key, if any. <literal>USING INDEX</> + old values of the columns of the primary key, if any. <literal>USING INDEX</literal> records the old values of the columns covered by the named index, which must be unique, not partial, not deferrable, and include only columns marked - <literal>NOT NULL</>. <literal>FULL</> records the old values of all columns - in the row. <literal>NOTHING</> records no information about the old row. + <literal>NOT NULL</literal>. <literal>FULL</literal> records the old values of all columns + in the row. <literal>NOTHING</literal> records no information about the old row. (This is the default for system tables.) In all cases, no old values are logged unless at least one of the columns that would be logged differs between the old and new versions of the row. @@ -853,7 +853,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - You must own the table to use <command>ALTER TABLE</>. + You must own the table to use <command>ALTER TABLE</command>. To change the schema or tablespace of a table, you must also have <literal>CREATE</literal> privilege on the new schema or tablespace. To add the table as a new child of a parent table, you must own the parent @@ -890,10 +890,10 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> The name (optionally schema-qualified) of an existing table to - alter. If <literal>ONLY</> is specified before the table name, only - that table is altered. If <literal>ONLY</> is not specified, the table + alter. If <literal>ONLY</literal> is specified before the table name, only + that table is altered. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are altered. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -1106,28 +1106,28 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> When a column is added with <literal>ADD COLUMN</literal>, all existing rows in the table are initialized with the column's default value - (NULL if no <literal>DEFAULT</> clause is specified). - If there is no <literal>DEFAULT</> clause, this is merely a metadata + (NULL if no <literal>DEFAULT</literal> clause is specified). + If there is no <literal>DEFAULT</literal> clause, this is merely a metadata change and does not require any immediate update of the table's data; the added NULL values are supplied on readout, instead. </para> <para> - Adding a column with a <literal>DEFAULT</> clause or changing the type of + Adding a column with a <literal>DEFAULT</literal> clause or changing the type of an existing column will require the entire table and its indexes to be rewritten. As an exception when changing the type of an existing column, - if the <literal>USING</> clause does not change the column + if the <literal>USING</literal> clause does not change the column contents and the old type is either binary coercible to the new type or an unconstrained domain over the new type, a table rewrite is not needed; but any indexes on the affected columns must still be rebuilt. Adding or - removing a system <literal>oid</> column also requires rewriting the entire + removing a system <literal>oid</literal> column also requires rewriting the entire table. Table and/or index rebuilds may take a significant amount of time for a large table; and will temporarily require as much as double the disk space. </para> <para> - Adding a <literal>CHECK</> or <literal>NOT NULL</> constraint requires + Adding a <literal>CHECK</literal> or <literal>NOT NULL</literal> constraint requires scanning the table to verify that existing rows meet the constraint, but does not require a table rewrite. </para> @@ -1139,7 +1139,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> The main reason for providing the option to specify multiple changes - in a single <command>ALTER TABLE</> is that multiple table scans or + in a single <command>ALTER TABLE</command> is that multiple table scans or rewrites can thereby be combined into a single pass over the table. </para> @@ -1151,37 +1151,37 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> reduce the on-disk size of your table, as the space occupied by the dropped column is not reclaimed. The space will be reclaimed over time as existing rows are updated. (These statements do - not apply when dropping the system <literal>oid</> column; that is done + not apply when dropping the system <literal>oid</literal> column; that is done with an immediate rewrite.) </para> <para> To force immediate reclamation of space occupied by a dropped column, - you can execute one of the forms of <command>ALTER TABLE</> that + you can execute one of the forms of <command>ALTER TABLE</command> that performs a rewrite of the whole table. This results in reconstructing each row with the dropped column replaced by a null value. </para> <para> - The rewriting forms of <command>ALTER TABLE</> are not MVCC-safe. + The rewriting forms of <command>ALTER TABLE</command> are not MVCC-safe. After a table rewrite, the table will appear empty to concurrent transactions, if they are using a snapshot taken before the rewrite occurred. See <xref linkend="mvcc-caveats"> for more details. </para> <para> - The <literal>USING</literal> option of <literal>SET DATA TYPE</> can actually + The <literal>USING</literal> option of <literal>SET DATA TYPE</literal> can actually specify any expression involving the old values of the row; that is, it can refer to other columns as well as the one being converted. This allows - very general conversions to be done with the <literal>SET DATA TYPE</> + very general conversions to be done with the <literal>SET DATA TYPE</literal> syntax. Because of this flexibility, the <literal>USING</literal> expression is not applied to the column's default value (if any); the result might not be a constant expression as required for a default. This means that when there is no implicit or assignment cast from old to - new type, <literal>SET DATA TYPE</> might fail to convert the default even + new type, <literal>SET DATA TYPE</literal> might fail to convert the default even though a <literal>USING</literal> clause is supplied. In such cases, - drop the default with <literal>DROP DEFAULT</>, perform the <literal>ALTER - TYPE</>, and then use <literal>SET DEFAULT</> to add a suitable new + drop the default with <literal>DROP DEFAULT</literal>, perform the <literal>ALTER + TYPE</literal>, and then use <literal>SET DEFAULT</literal> to add a suitable new default. Similar considerations apply to indexes and constraints involving the column. </para> @@ -1216,11 +1216,11 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> The actions for identity columns (<literal>ADD GENERATED</literal>, <literal>SET</literal> etc., <literal>DROP IDENTITY</literal>), as well as the actions - <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>, - and <literal>TABLESPACE</> never recurse to descendant tables; - that is, they always act as though <literal>ONLY</> were specified. - Adding a constraint recurses only for <literal>CHECK</> constraints - that are not marked <literal>NO INHERIT</>. + <literal>TRIGGER</literal>, <literal>CLUSTER</literal>, <literal>OWNER</literal>, + and <literal>TABLESPACE</literal> never recurse to descendant tables; + that is, they always act as though <literal>ONLY</literal> were specified. + Adding a constraint recurses only for <literal>CHECK</literal> constraints + that are not marked <literal>NO INHERIT</literal>. </para> <para> @@ -1434,17 +1434,17 @@ ALTER TABLE measurement <para> The forms <literal>ADD</literal> (without <literal>USING INDEX</literal>), - <literal>DROP [COLUMN]</>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>, - <literal>SET DEFAULT</>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>), + <literal>DROP [COLUMN]</literal>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>, + <literal>SET DEFAULT</literal>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>), <literal>SET GENERATED</literal>, and <literal>SET <replaceable>sequence_option</replaceable></literal> conform with the SQL standard. The other forms are <productname>PostgreSQL</productname> extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single - <command>ALTER TABLE</> command is an extension. + <command>ALTER TABLE</command> command is an extension. </para> <para> - <command>ALTER TABLE DROP COLUMN</> can be used to drop the only + <command>ALTER TABLE DROP COLUMN</command> can be used to drop the only column of a table, leaving a zero-column table. This is an extension of SQL, which disallows zero-column tables. </para> diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml index 4542bd90a21..def554bfb33 100644 --- a/doc/src/sgml/ref/alter_tablespace.sgml +++ b/doc/src/sgml/ref/alter_tablespace.sgml @@ -83,8 +83,8 @@ ALTER TABLESPACE <replaceable>name</replaceable> RESET ( <replaceable class="par <listitem> <para> A tablespace parameter to be set or reset. Currently, the only - available parameters are <varname>seq_page_cost</>, - <varname>random_page_cost</> and <varname>effective_io_concurrency</>. + available parameters are <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname> and <varname>effective_io_concurrency</varname>. Setting either value for a particular tablespace will override the planner's usual estimate of the cost of reading pages from tables in that tablespace, as established by the configuration parameters of the diff --git a/doc/src/sgml/ref/alter_trigger.sgml b/doc/src/sgml/ref/alter_trigger.sgml index 3e48d159e27..2e872cf11f2 100644 --- a/doc/src/sgml/ref/alter_trigger.sgml +++ b/doc/src/sgml/ref/alter_trigger.sgml @@ -91,7 +91,7 @@ ALTER TRIGGER <replaceable class="parameter">name</replaceable> ON <replaceable <para> The ability to temporarily enable or disable a trigger is provided by <xref linkend="SQL-ALTERTABLE">, not by - <command>ALTER TRIGGER</>, because <command>ALTER TRIGGER</> has no + <command>ALTER TRIGGER</command>, because <command>ALTER TRIGGER</command> has no convenient way to express the option of enabling or disabling all of a table's triggers at once. </para> @@ -117,7 +117,7 @@ ALTER TRIGGER emp_stamp ON emp DEPENDS ON EXTENSION emplib; <title>Compatibility</title> <para> - <command>ALTER TRIGGER</command> is a <productname>PostgreSQL</> + <command>ALTER TRIGGER</command> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_tsconfig.sgml b/doc/src/sgml/ref/alter_tsconfig.sgml index 72a719b8629..b44aac9bf58 100644 --- a/doc/src/sgml/ref/alter_tsconfig.sgml +++ b/doc/src/sgml/ref/alter_tsconfig.sgml @@ -49,7 +49,7 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl <para> You must be the owner of the configuration to use - <command>ALTER TEXT SEARCH CONFIGURATION</>. + <command>ALTER TEXT SEARCH CONFIGURATION</command>. </para> </refsect1> @@ -136,20 +136,20 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl </variablelist> <para> - The <literal>ADD MAPPING FOR</> form installs a list of dictionaries to be + The <literal>ADD MAPPING FOR</literal> form installs a list of dictionaries to be consulted for the specified token type(s); it is an error if there is already a mapping for any of the token types. - The <literal>ALTER MAPPING FOR</> form does the same, but first removing + The <literal>ALTER MAPPING FOR</literal> form does the same, but first removing any existing mapping for those token types. - The <literal>ALTER MAPPING REPLACE</> forms substitute <replaceable + The <literal>ALTER MAPPING REPLACE</literal> forms substitute <replaceable class="parameter">new_dictionary</replaceable> for <replaceable class="parameter">old_dictionary</replaceable> anywhere the latter appears. - This is done for only the specified token types when <literal>FOR</> + This is done for only the specified token types when <literal>FOR</literal> appears, or for all mappings of the configuration when it doesn't. - The <literal>DROP MAPPING</> form removes all dictionaries for the + The <literal>DROP MAPPING</literal> form removes all dictionaries for the specified token type(s), causing tokens of those types to be ignored by the text search configuration. It is an error if there is no mapping - for the token types, unless <literal>IF EXISTS</> appears. + for the token types, unless <literal>IF EXISTS</literal> appears. </para> </refsect1> @@ -158,9 +158,9 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl <title>Examples</title> <para> - The following example replaces the <literal>english</> dictionary - with the <literal>swedish</> dictionary anywhere that <literal>english</> - is used within <literal>my_config</>. + The following example replaces the <literal>english</literal> dictionary + with the <literal>swedish</literal> dictionary anywhere that <literal>english</literal> + is used within <literal>my_config</literal>. </para> <programlisting> diff --git a/doc/src/sgml/ref/alter_tsdictionary.sgml b/doc/src/sgml/ref/alter_tsdictionary.sgml index 7cecabea83b..16d76687ab1 100644 --- a/doc/src/sgml/ref/alter_tsdictionary.sgml +++ b/doc/src/sgml/ref/alter_tsdictionary.sgml @@ -41,7 +41,7 @@ ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> SET SCHEMA <replace <para> You must be the owner of the dictionary to use - <command>ALTER TEXT SEARCH DICTIONARY</>. + <command>ALTER TEXT SEARCH DICTIONARY</command>. </para> </refsect1> @@ -126,7 +126,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian ); </programlisting> <para> - The following example command changes the language option to <literal>dutch</>, + The following example command changes the language option to <literal>dutch</literal>, and removes the stopword option entirely. </para> @@ -135,7 +135,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); </programlisting> <para> - The following example command <quote>updates</> the dictionary's + The following example command <quote>updates</quote> the dictionary's definition without actually changing anything. <programlisting> @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (The reason this works is that the option removal code doesn't complain if there is no such option.) This trick is useful when changing - configuration files for the dictionary: the <command>ALTER</> will + configuration files for the dictionary: the <command>ALTER</command> will force existing database sessions to re-read the configuration files, which otherwise they would never do if they had read them earlier. </para> diff --git a/doc/src/sgml/ref/alter_tsparser.sgml b/doc/src/sgml/ref/alter_tsparser.sgml index e2b6060a17a..737a5075657 100644 --- a/doc/src/sgml/ref/alter_tsparser.sgml +++ b/doc/src/sgml/ref/alter_tsparser.sgml @@ -36,7 +36,7 @@ ALTER TEXT SEARCH PARSER <replaceable>name</replaceable> SET SCHEMA <replaceable </para> <para> - You must be a superuser to use <command>ALTER TEXT SEARCH PARSER</>. + You must be a superuser to use <command>ALTER TEXT SEARCH PARSER</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_tstemplate.sgml b/doc/src/sgml/ref/alter_tstemplate.sgml index e7ae91c0a08..d9a753017b5 100644 --- a/doc/src/sgml/ref/alter_tstemplate.sgml +++ b/doc/src/sgml/ref/alter_tstemplate.sgml @@ -36,7 +36,7 @@ ALTER TEXT SEARCH TEMPLATE <replaceable>name</replaceable> SET SCHEMA <replaceab </para> <para> - You must be a superuser to use <command>ALTER TEXT SEARCH TEMPLATE</>. + You must be a superuser to use <command>ALTER TEXT SEARCH TEMPLATE</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml index 6c5201ccb59..75be3187f14 100644 --- a/doc/src/sgml/ref/alter_type.sgml +++ b/doc/src/sgml/ref/alter_type.sgml @@ -147,7 +147,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla </para> <para> - You must own the type to use <command>ALTER TYPE</>. + You must own the type to use <command>ALTER TYPE</command>. To change the schema of a type, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -290,7 +290,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla <title>Notes</title> <para> - <command>ALTER TYPE ... ADD VALUE</> (the form that adds a new value to an + <command>ALTER TYPE ... ADD VALUE</command> (the form that adds a new value to an enum type) cannot be executed inside a transaction block. </para> @@ -301,7 +301,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla is used to set the new value's sort position somewhere other than at the end of the list. However, sometimes it will happen even though the new value is added at the end (this occurs if the OID counter <quote>wrapped - around</> since the original creation of the enum type). The slowdown is + around</quote> since the original creation of the enum type). The slowdown is usually insignificant; but if it matters, optimal performance can be regained by dropping and recreating the enum type, or by dumping and reloading the database. diff --git a/doc/src/sgml/ref/alter_user_mapping.sgml b/doc/src/sgml/ref/alter_user_mapping.sgml index 5cc49210edb..18271d51995 100644 --- a/doc/src/sgml/ref/alter_user_mapping.sgml +++ b/doc/src/sgml/ref/alter_user_mapping.sgml @@ -38,7 +38,7 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <para> The owner of a foreign server can alter user mappings for that server for any user. Also, a user can alter a user mapping for - their own user name if <literal>USAGE</> privilege on the server has + their own user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -51,9 +51,9 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <term><replaceable class="parameter">user_name</replaceable></term> <listitem> <para> - User name of the mapping. <literal>CURRENT_USER</> - and <literal>USER</> match the name of the current - user. <literal>PUBLIC</> is used to match all present and future + User name of the mapping. <literal>CURRENT_USER</literal> + and <literal>USER</literal> match the name of the current + user. <literal>PUBLIC</literal> is used to match all present and future user names in the system. </para> </listitem> @@ -74,8 +74,8 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <para> Change options for the user mapping. The new options override any previously specified - options. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + options. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; options are also validated by the server's foreign-data wrapper. @@ -89,7 +89,7 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <title>Examples</title> <para> - Change the password for user mapping <literal>bob</>, server <literal>foo</>: + Change the password for user mapping <literal>bob</literal>, server <literal>foo</literal>: <programlisting> ALTER USER MAPPING FOR bob SERVER foo OPTIONS (SET password 'public'); </programlisting></para> diff --git a/doc/src/sgml/ref/alter_view.sgml b/doc/src/sgml/ref/alter_view.sgml index 788eda5d58e..e7180b44093 100644 --- a/doc/src/sgml/ref/alter_view.sgml +++ b/doc/src/sgml/ref/alter_view.sgml @@ -37,12 +37,12 @@ ALTER VIEW [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET <para> <command>ALTER VIEW</command> changes various auxiliary properties of a view. (If you want to modify the view's defining query, - use <command>CREATE OR REPLACE VIEW</>.) + use <command>CREATE OR REPLACE VIEW</command>.) </para> <para> - You must own the view to use <command>ALTER VIEW</>. - To change a view's schema, you must also have <literal>CREATE</> + You must own the view to use <command>ALTER VIEW</command>. + To change a view's schema, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on @@ -81,7 +81,7 @@ ALTER VIEW [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET <para> These forms set or remove the default value for a column. A view column's default value is substituted into any - <command>INSERT</> or <command>UPDATE</> command whose target is the + <command>INSERT</command> or <command>UPDATE</command> command whose target is the view, before applying any rules or triggers for the view. The view's default will therefore take precedence over any default values from underlying relations. @@ -185,7 +185,7 @@ INSERT INTO a_view(id) VALUES(2); -- ts will receive the current time <title>Compatibility</title> <para> - <command>ALTER VIEW</command> is a <productname>PostgreSQL</> + <command>ALTER VIEW</command> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> </refsect1> diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index eae7fe92e09..12f2f093372 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -35,7 +35,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> <command>ANALYZE</command> collects statistics about the contents of tables in the database, and stores the results in the <link - linkend="catalog-pg-statistic"><structname>pg_statistic</></> + linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link> system catalog. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries. @@ -93,7 +93,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <title>Outputs</title> <para> - When <literal>VERBOSE</> is specified, <command>ANALYZE</> emits + When <literal>VERBOSE</literal> is specified, <command>ANALYZE</command> emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well. </para> @@ -104,8 +104,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> Foreign tables are analyzed only when explicitly selected. Not all - foreign data wrappers support <command>ANALYZE</>. If the table's - wrapper does not support <command>ANALYZE</>, the command prints a + foreign data wrappers support <command>ANALYZE</command>. If the table's + wrapper does not support <command>ANALYZE</command>, the command prints a warning and does nothing. </para> @@ -172,8 +172,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <literal>pg_statistic</literal>. In particular, setting the statistics target to zero disables collection of statistics for that column. It might be useful to do that for columns that are - never used as part of the <literal>WHERE</>, <literal>GROUP BY</>, - or <literal>ORDER BY</> clauses of queries, since the planner will + never used as part of the <literal>WHERE</literal>, <literal>GROUP BY</literal>, + or <literal>ORDER BY</literal> clauses of queries, since the planner will have no use for statistics on such columns. </para> @@ -191,7 +191,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea with the largest possible statistics target. If this inaccuracy leads to bad query plans, a more accurate value can be determined manually and then installed with - <command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</> + <command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</command> (see <xref linkend="sql-altertable">). </para> @@ -210,7 +210,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> If any of the child tables are foreign tables whose foreign data wrappers - do not support <command>ANALYZE</>, those child tables are ignored while + do not support <command>ANALYZE</command>, those child tables are ignored while gathering inheritance statistics. </para> diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml index c04f1c8064c..fd6f073d18e 100644 --- a/doc/src/sgml/ref/begin.sgml +++ b/doc/src/sgml/ref/begin.sgml @@ -91,7 +91,7 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</ <para> <xref linkend="sql-start-transaction"> has the same functionality - as <command>BEGIN</>. + as <command>BEGIN</command>. </para> <para> @@ -101,7 +101,7 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</ </para> <para> - Issuing <command>BEGIN</> when already inside a transaction block will + Issuing <command>BEGIN</command> when already inside a transaction block will provoke a warning message. The state of the transaction is not affected. To nest transactions within a transaction block, use savepoints (see <xref linkend="sql-savepoint">). diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml index aaa2f89a30f..4d71c45797d 100644 --- a/doc/src/sgml/ref/close.sgml +++ b/doc/src/sgml/ref/close.sgml @@ -90,7 +90,7 @@ CLOSE { <replaceable class="parameter">name</replaceable> | ALL } <para> You can see all available cursors by querying the <link - linkend="view-pg-cursors"><structname>pg_cursors</></> system view. + linkend="view-pg-cursors"><structname>pg_cursors</structname></link> system view. </para> <para> @@ -115,7 +115,7 @@ CLOSE liahona; <para> <command>CLOSE</command> is fully conforming with the SQL - standard. <command>CLOSE ALL</> is a <productname>PostgreSQL</> + standard. <command>CLOSE ALL</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index b55734d35c9..5c5db750771 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -128,7 +128,7 @@ CLUSTER [VERBOSE] </para> <para> - <command>CLUSTER</> can re-sort the table using either an index scan + <command>CLUSTER</command> can re-sort the table using either an index scan on the specified index, or (if the index is a b-tree) a sequential scan followed by sorting. It will attempt to choose the method that will be faster, based on planner cost parameters and available statistical @@ -148,13 +148,13 @@ CLUSTER [VERBOSE] as double the table size, plus the index sizes. This method is often faster than the index scan method, but if the disk space requirement is intolerable, you can disable this choice by temporarily setting <xref - linkend="guc-enable-sort"> to <literal>off</>. + linkend="guc-enable-sort"> to <literal>off</literal>. </para> <para> It is advisable to set <xref linkend="guc-maintenance-work-mem"> to a reasonably large value (but not more than the amount of RAM you can - dedicate to the <command>CLUSTER</> operation) before clustering. + dedicate to the <command>CLUSTER</command> operation) before clustering. </para> <para> @@ -168,7 +168,7 @@ CLUSTER [VERBOSE] Because <command>CLUSTER</command> remembers which indexes are clustered, one can cluster the tables one wants clustered manually the first time, then set up a periodic maintenance script that executes - <command>CLUSTER</> without any parameters, so that the desired tables + <command>CLUSTER</command> without any parameters, so that the desired tables are periodically reclustered. </para> @@ -212,7 +212,7 @@ CLUSTER; <synopsis> CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> </synopsis> - is also supported for compatibility with pre-8.3 <productname>PostgreSQL</> + is also supported for compatibility with pre-8.3 <productname>PostgreSQL</productname> versions. </para> </refsect1> diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml index 67582fd6e69..081bbc5f7a3 100644 --- a/doc/src/sgml/ref/clusterdb.sgml +++ b/doc/src/sgml/ref/clusterdb.sgml @@ -76,8 +76,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-a</></term> - <term><option>--all</></term> + <term><option>-a</option></term> + <term><option>--all</option></term> <listitem> <para> Cluster all databases. @@ -86,8 +86,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term> + <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term> + <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to be clustered. @@ -101,8 +101,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>clusterdb</application> generates @@ -112,8 +112,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-q</></term> - <term><option>--quiet</></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> Do not display progress messages. @@ -122,20 +122,20 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-t <replaceable class="parameter">table</replaceable></></term> - <term><option>--table=<replaceable class="parameter">table</replaceable></></term> + <term><option>-t <replaceable class="parameter">table</replaceable></option></term> + <term><option>--table=<replaceable class="parameter">table</replaceable></option></term> <listitem> <para> Cluster <replaceable class="parameter">table</replaceable> only. Multiple tables can be clustered by writing multiple - <option>-t</> switches. + <option>-t</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Print detailed information during processing. @@ -144,8 +144,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>clusterdb</application> version and exit. @@ -154,8 +154,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>clusterdb</application> command line @@ -173,8 +173,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the server is @@ -185,8 +185,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -197,8 +197,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -207,8 +207,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -222,8 +222,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>clusterdb</application> to prompt for a @@ -236,14 +236,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>clusterdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to discover what other @@ -277,8 +277,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index 059d6f41d81..ab2e09d5218 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -83,16 +83,16 @@ COMMENT ON <para> Only one comment string is stored for each object, so to modify a comment, - issue a new <command>COMMENT</> command for the same object. To remove a + issue a new <command>COMMENT</command> command for the same object. To remove a comment, write <literal>NULL</literal> in place of the text string. Comments are automatically dropped when their object is dropped. </para> <para> For most kinds of object, only the object's owner can set the comment. - Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</> is + Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</literal> is that you must be superuser to comment on a superuser role, or have the - <literal>CREATEROLE</> privilege to comment on non-superuser roles. + <literal>CREATEROLE</literal> privilege to comment on non-superuser roles. Likewise, access methods don't have owners either; you must be superuser to comment on an access method. Of course, a superuser can comment on anything. @@ -103,8 +103,8 @@ COMMENT ON <command>\d</command> family of commands. Other user interfaces to retrieve comments can be built atop the same built-in functions that <application>psql</application> uses, namely - <function>obj_description</>, <function>col_description</>, - and <function>shobj_description</> + <function>obj_description</function>, <function>col_description</function>, + and <function>shobj_description</function> (see <xref linkend="functions-info-comment-table">). </para> </refsect1> @@ -171,14 +171,14 @@ COMMENT ON <listitem> <para> The mode of a function or aggregate - argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>COMMENT</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -219,7 +219,7 @@ COMMENT ON <listitem> <para> The data type(s) of the operator's arguments (optionally - schema-qualified). Write <literal>NONE</> for the missing argument + schema-qualified). Write <literal>NONE</literal> for the missing argument of a prefix or postfix operator. </para> </listitem> @@ -258,7 +258,7 @@ COMMENT ON <term><replaceable class="parameter">text</replaceable></term> <listitem> <para> - The new comment, written as a string literal; or <literal>NULL</> + The new comment, written as a string literal; or <literal>NULL</literal> to drop the comment. </para> </listitem> diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index e93c216849b..8e3f53957ee 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -60,7 +60,7 @@ COMMIT [ WORK | TRANSACTION ] </para> <para> - Issuing <command>COMMIT</> when not inside a transaction does + Issuing <command>COMMIT</command> when not inside a transaction does no harm, but it will provoke a warning message. </para> </refsect1> diff --git a/doc/src/sgml/ref/commit_prepared.sgml b/doc/src/sgml/ref/commit_prepared.sgml index 716aed3ac22..35bbf85af7e 100644 --- a/doc/src/sgml/ref/commit_prepared.sgml +++ b/doc/src/sgml/ref/commit_prepared.sgml @@ -75,7 +75,7 @@ COMMIT PREPARED <replaceable class="parameter">transaction_id</replaceable> <title id="sql-commit-prepared-examples-title">Examples</title> <para> Commit the transaction identified by the transaction - identifier <literal>foobar</>: + identifier <literal>foobar</literal>: <programlisting> COMMIT PREPARED 'foobar'; diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 732efe69e66..8f0974b2569 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -54,10 +54,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <command>COPY</command> moves data between <productname>PostgreSQL</productname> tables and standard file-system files. <command>COPY TO</command> copies the contents of a table - <emphasis>to</> a file, while <command>COPY FROM</command> copies - data <emphasis>from</> a file to a table (appending the data to + <emphasis>to</emphasis> a file, while <command>COPY FROM</command> copies + data <emphasis>from</emphasis> a file to a table (appending the data to whatever is in the table already). <command>COPY TO</command> - can also copy the results of a <command>SELECT</> query. + can also copy the results of a <command>SELECT</command> query. </para> <para> @@ -118,10 +118,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable copied. Note that parentheses are required around the query. </para> <para> - For <command>INSERT</>, <command>UPDATE</> and - <command>DELETE</> queries a RETURNING clause must be provided, + For <command>INSERT</command>, <command>UPDATE</command> and + <command>DELETE</command> queries a RETURNING clause must be provided, and the target relation must not have a conditional rule, nor - an <literal>ALSO</> rule, nor an <literal>INSTEAD</> rule + an <literal>ALSO</literal> rule, nor an <literal>INSTEAD</literal> rule that expands to multiple statements. </para> </listitem> @@ -133,7 +133,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> The path name of the input or output file. An input file name can be an absolute or relative path, but an output file name must be an absolute - path. Windows users might need to use an <literal>E''</> string and + path. Windows users might need to use an <literal>E''</literal> string and double any backslashes used in the path name. </para> </listitem> @@ -144,7 +144,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> A command to execute. In <command>COPY FROM</command>, the input is - read from standard output of the command, and in <command>COPY TO</>, + read from standard output of the command, and in <command>COPY TO</command>, the output is written to the standard input of the command. </para> <para> @@ -181,9 +181,9 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Specifies whether the selected option should be turned on or off. - You can write <literal>TRUE</literal>, <literal>ON</>, or + You can write <literal>TRUE</literal>, <literal>ON</literal>, or <literal>1</literal> to enable the option, and <literal>FALSE</literal>, - <literal>OFF</>, or <literal>0</literal> to disable it. The + <literal>OFF</literal>, or <literal>0</literal> to disable it. The <replaceable class="parameter">boolean</replaceable> value can also be omitted, in which case <literal>TRUE</literal> is assumed. </para> @@ -195,10 +195,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Selects the data format to be read or written: - <literal>text</>, - <literal>csv</> (Comma Separated Values), - or <literal>binary</>. - The default is <literal>text</>. + <literal>text</literal>, + <literal>csv</literal> (Comma Separated Values), + or <literal>binary</literal>. + The default is <literal>text</literal>. </para> </listitem> </varlistentry> @@ -220,7 +220,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Requests copying the data with rows already frozen, just as they - would be after running the <command>VACUUM FREEZE</> command. + would be after running the <command>VACUUM FREEZE</command> command. This is intended as a performance option for initial data loading. Rows will be frozen only if the table being loaded has been created or truncated in the current subtransaction, there are no cursors @@ -241,9 +241,9 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, - a comma in <literal>CSV</> format. + a comma in <literal>CSV</literal> format. This must be a single one-byte character. - This option is not allowed when using <literal>binary</> format. + This option is not allowed when using <literal>binary</literal> format. </para> </listitem> </varlistentry> @@ -254,10 +254,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> Specifies the string that represents a null value. The default is <literal>\N</literal> (backslash-N) in text format, and an unquoted empty - string in <literal>CSV</> format. You might prefer an + string in <literal>CSV</literal> format. You might prefer an empty string even in text format for cases where you don't want to distinguish nulls from empty strings. - This option is not allowed when using <literal>binary</> format. + This option is not allowed when using <literal>binary</literal> format. </para> <note> @@ -279,7 +279,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable Specifies that the file contains a header line with the names of each column in the file. On output, the first line contains the column names from the table, and on input, the first line is ignored. - This option is allowed only when using <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> @@ -291,7 +291,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable Specifies the quoting character to be used when a data value is quoted. The default is double-quote. This must be a single one-byte character. - This option is allowed only when using <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> @@ -301,59 +301,59 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Specifies the character that should appear before a - data character that matches the <literal>QUOTE</> value. - The default is the same as the <literal>QUOTE</> value (so that + data character that matches the <literal>QUOTE</literal> value. + The default is the same as the <literal>QUOTE</literal> value (so that the quoting character is doubled if it appears in the data). This must be a single one-byte character. - This option is allowed only when using <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_QUOTE</></term> + <term><literal>FORCE_QUOTE</literal></term> <listitem> <para> Forces quoting to be - used for all non-<literal>NULL</> values in each specified column. - <literal>NULL</> output is never quoted. If <literal>*</> is specified, - non-<literal>NULL</> values will be quoted in all columns. - This option is allowed only in <command>COPY TO</>, and only when - using <literal>CSV</> format. + used for all non-<literal>NULL</literal> values in each specified column. + <literal>NULL</literal> output is never quoted. If <literal>*</literal> is specified, + non-<literal>NULL</literal> values will be quoted in all columns. + This option is allowed only in <command>COPY TO</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_NOT_NULL</></term> + <term><literal>FORCE_NOT_NULL</literal></term> <listitem> <para> Do not match the specified columns' values against the null string. In the default case where the null string is empty, this means that empty values will be read as zero-length strings rather than nulls, even when they are not quoted. - This option is allowed only in <command>COPY FROM</>, and only when - using <literal>CSV</> format. + This option is allowed only in <command>COPY FROM</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_NULL</></term> + <term><literal>FORCE_NULL</literal></term> <listitem> <para> Match the specified columns' values against the null string, even if it has been quoted, and if a match is found set the value to - <literal>NULL</>. In the default case where the null string is empty, + <literal>NULL</literal>. In the default case where the null string is empty, this converts a quoted empty string into NULL. - This option is allowed only in <command>COPY FROM</>, and only when - using <literal>CSV</> format. + This option is allowed only in <command>COPY FROM</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ENCODING</></term> + <term><literal>ENCODING</literal></term> <listitem> <para> Specifies that the file is encoded in the <replaceable @@ -371,7 +371,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <title>Outputs</title> <para> - On successful completion, a <command>COPY</> command returns a command + On successful completion, a <command>COPY</command> command returns a command tag of the form <screen> COPY <replaceable class="parameter">count</replaceable> @@ -382,10 +382,10 @@ COPY <replaceable class="parameter">count</replaceable> <note> <para> - <application>psql</> will print this command tag only if the command - was not <literal>COPY ... TO STDOUT</>, or the - equivalent <application>psql</> meta-command - <literal>\copy ... to stdout</>. This is to prevent confusing the + <application>psql</application> will print this command tag only if the command + was not <literal>COPY ... TO STDOUT</literal>, or the + equivalent <application>psql</application> meta-command + <literal>\copy ... to stdout</literal>. This is to prevent confusing the command tag with the data that was just printed. </para> </note> @@ -403,16 +403,16 @@ COPY <replaceable class="parameter">count</replaceable> <para> <command>COPY FROM</command> can be used with plain tables and with views - that have <literal>INSTEAD OF INSERT</> triggers. + that have <literal>INSTEAD OF INSERT</literal> triggers. </para> <para> <command>COPY</command> only deals with the specific table named; it does not copy data to or from child tables. Thus for example - <literal>COPY <replaceable class="parameter">table</> TO</literal> + <literal>COPY <replaceable class="parameter">table</replaceable> TO</literal> shows the same data as <literal>SELECT * FROM ONLY <replaceable - class="parameter">table</></literal>. But <literal>COPY - (SELECT * FROM <replaceable class="parameter">table</>) TO ...</literal> + class="parameter">table</replaceable></literal>. But <literal>COPY + (SELECT * FROM <replaceable class="parameter">table</replaceable>) TO ...</literal> can be used to dump all of the data in an inheritance hierarchy. </para> @@ -427,7 +427,7 @@ COPY <replaceable class="parameter">count</replaceable> <para> If row-level security is enabled for the table, the relevant <command>SELECT</command> policies will apply to <literal>COPY - <replaceable class="parameter">table</> TO</literal> statements. + <replaceable class="parameter">table</replaceable> TO</literal> statements. Currently, <command>COPY FROM</command> is not supported for tables with row-level security. Use equivalent <command>INSERT</command> statements instead. @@ -491,10 +491,10 @@ COPY <replaceable class="parameter">count</replaceable> <varname>DateStyle</varname>. To ensure portability to other <productname>PostgreSQL</productname> installations that might use non-default <varname>DateStyle</varname> settings, - <varname>DateStyle</varname> should be set to <literal>ISO</> before - using <command>COPY TO</>. It is also a good idea to avoid dumping + <varname>DateStyle</varname> should be set to <literal>ISO</literal> before + using <command>COPY TO</command>. It is also a good idea to avoid dumping data with <varname>IntervalStyle</varname> set to - <literal>sql_standard</>, because negative interval values might be + <literal>sql_standard</literal>, because negative interval values might be misinterpreted by a server that has a different setting for <varname>IntervalStyle</varname>. </para> @@ -519,7 +519,7 @@ COPY <replaceable class="parameter">count</replaceable> </para> <para> - <literal>FORCE_NULL</> and <literal>FORCE_NOT_NULL</> can be used + <literal>FORCE_NULL</literal> and <literal>FORCE_NOT_NULL</literal> can be used simultaneously on the same column. This results in converting quoted null strings to null values and unquoted null strings to empty strings. </para> @@ -533,7 +533,7 @@ COPY <replaceable class="parameter">count</replaceable> <title>Text Format</title> <para> - When the <literal>text</> format is used, + When the <literal>text</literal> format is used, the data read or written is a text file with one line per table row. Columns in a row are separated by the delimiter character. The column values themselves are strings generated by the @@ -548,17 +548,17 @@ COPY <replaceable class="parameter">count</replaceable> <para> End of data can be represented by a single line containing just - backslash-period (<literal>\.</>). An end-of-data marker is + backslash-period (<literal>\.</literal>). An end-of-data marker is not necessary when reading from a file, since the end of file serves perfectly well; it is needed only when copying data to or from client applications using pre-3.0 client protocol. </para> <para> - Backslash characters (<literal>\</>) can be used in the + Backslash characters (<literal>\</literal>) can be used in the <command>COPY</command> data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the - following characters <emphasis>must</> be preceded by a backslash if + following characters <emphasis>must</emphasis> be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character. </para> @@ -587,37 +587,37 @@ COPY <replaceable class="parameter">count</replaceable> <tbody> <row> - <entry><literal>\b</></entry> + <entry><literal>\b</literal></entry> <entry>Backspace (ASCII 8)</entry> </row> <row> - <entry><literal>\f</></entry> + <entry><literal>\f</literal></entry> <entry>Form feed (ASCII 12)</entry> </row> <row> - <entry><literal>\n</></entry> + <entry><literal>\n</literal></entry> <entry>Newline (ASCII 10)</entry> </row> <row> - <entry><literal>\r</></entry> + <entry><literal>\r</literal></entry> <entry>Carriage return (ASCII 13)</entry> </row> <row> - <entry><literal>\t</></entry> + <entry><literal>\t</literal></entry> <entry>Tab (ASCII 9)</entry> </row> <row> - <entry><literal>\v</></entry> + <entry><literal>\v</literal></entry> <entry>Vertical tab (ASCII 11)</entry> </row> <row> - <entry><literal>\</><replaceable>digits</></entry> + <entry><literal>\</literal><replaceable>digits</replaceable></entry> <entry>Backslash followed by one to three octal digits specifies the character with that numeric code</entry> </row> <row> - <entry><literal>\x</><replaceable>digits</></entry> - <entry>Backslash <literal>x</> followed by one or two hex digits specifies + <entry><literal>\x</literal><replaceable>digits</replaceable></entry> + <entry>Backslash <literal>x</literal> followed by one or two hex digits specifies the character with that numeric code</entry> </row> </tbody> @@ -633,15 +633,15 @@ COPY <replaceable class="parameter">count</replaceable> Any other backslashed character that is not mentioned in the above table will be taken to represent itself. However, beware of adding backslashes unnecessarily, since that might accidentally produce a string matching the - end-of-data marker (<literal>\.</>) or the null string (<literal>\N</> by + end-of-data marker (<literal>\.</literal>) or the null string (<literal>\N</literal> by default). These strings will be recognized before any other backslash processing is done. </para> <para> It is strongly recommended that applications generating <command>COPY</command> data convert - data newlines and carriage returns to the <literal>\n</> and - <literal>\r</> sequences respectively. At present it is + data newlines and carriage returns to the <literal>\n</literal> and + <literal>\r</literal> sequences respectively. At present it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline. However, these representations might not be accepted in future releases. @@ -652,10 +652,10 @@ COPY <replaceable class="parameter">count</replaceable> <para> <command>COPY TO</command> will terminate each row with a Unix-style - newline (<quote><literal>\n</></>). Servers running on Microsoft Windows instead - output carriage return/newline (<quote><literal>\r\n</></>), but only for - <command>COPY</> to a server file; for consistency across platforms, - <command>COPY TO STDOUT</> always sends <quote><literal>\n</></> + newline (<quote><literal>\n</literal></quote>). Servers running on Microsoft Windows instead + output carriage return/newline (<quote><literal>\r\n</literal></quote>), but only for + <command>COPY</command> to a server file; for consistency across platforms, + <command>COPY TO STDOUT</command> always sends <quote><literal>\n</literal></quote> regardless of server platform. <command>COPY FROM</command> can handle lines ending with newlines, carriage returns, or carriage return/newlines. To reduce the risk of @@ -670,62 +670,62 @@ COPY <replaceable class="parameter">count</replaceable> <para> This format option is used for importing and exporting the Comma - Separated Value (<literal>CSV</>) file format used by many other + Separated Value (<literal>CSV</literal>) file format used by many other programs, such as spreadsheets. Instead of the escaping rules used by <productname>PostgreSQL</productname>'s standard text format, it produces and recognizes the common CSV escaping mechanism. </para> <para> - The values in each record are separated by the <literal>DELIMITER</> + The values in each record are separated by the <literal>DELIMITER</literal> character. If the value contains the delimiter character, the - <literal>QUOTE</> character, the <literal>NULL</> string, a carriage + <literal>QUOTE</literal> character, the <literal>NULL</literal> string, a carriage return, or line feed character, then the whole value is prefixed and - suffixed by the <literal>QUOTE</> character, and any occurrence - within the value of a <literal>QUOTE</> character or the - <literal>ESCAPE</> character is preceded by the escape character. - You can also use <literal>FORCE_QUOTE</> to force quotes when outputting - non-<literal>NULL</> values in specific columns. + suffixed by the <literal>QUOTE</literal> character, and any occurrence + within the value of a <literal>QUOTE</literal> character or the + <literal>ESCAPE</literal> character is preceded by the escape character. + You can also use <literal>FORCE_QUOTE</literal> to force quotes when outputting + non-<literal>NULL</literal> values in specific columns. </para> <para> - The <literal>CSV</> format has no standard way to distinguish a - <literal>NULL</> value from an empty string. - <productname>PostgreSQL</>'s <command>COPY</> handles this by quoting. - A <literal>NULL</> is output as the <literal>NULL</> parameter string - and is not quoted, while a non-<literal>NULL</> value matching the - <literal>NULL</> parameter string is quoted. For example, with the - default settings, a <literal>NULL</> is written as an unquoted empty + The <literal>CSV</literal> format has no standard way to distinguish a + <literal>NULL</literal> value from an empty string. + <productname>PostgreSQL</productname>'s <command>COPY</command> handles this by quoting. + A <literal>NULL</literal> is output as the <literal>NULL</literal> parameter string + and is not quoted, while a non-<literal>NULL</literal> value matching the + <literal>NULL</literal> parameter string is quoted. For example, with the + default settings, a <literal>NULL</literal> is written as an unquoted empty string, while an empty string data value is written with double quotes - (<literal>""</>). Reading values follows similar rules. You can - use <literal>FORCE_NOT_NULL</> to prevent <literal>NULL</> input + (<literal>""</literal>). Reading values follows similar rules. You can + use <literal>FORCE_NOT_NULL</literal> to prevent <literal>NULL</literal> input comparisons for specific columns. You can also use - <literal>FORCE_NULL</> to convert quoted null string data values to - <literal>NULL</>. + <literal>FORCE_NULL</literal> to convert quoted null string data values to + <literal>NULL</literal>. </para> <para> - Because backslash is not a special character in the <literal>CSV</> - format, <literal>\.</>, the end-of-data marker, could also appear - as a data value. To avoid any misinterpretation, a <literal>\.</> + Because backslash is not a special character in the <literal>CSV</literal> + format, <literal>\.</literal>, the end-of-data marker, could also appear + as a data value. To avoid any misinterpretation, a <literal>\.</literal> data value appearing as a lone entry on a line is automatically quoted on output, and on input, if quoted, is not interpreted as the end-of-data marker. If you are loading a file created by another application that has a single unquoted column and might have a - value of <literal>\.</>, you might need to quote that value in the + value of <literal>\.</literal>, you might need to quote that value in the input file. </para> <note> <para> - In <literal>CSV</> format, all characters are significant. A quoted value + In <literal>CSV</literal> format, all characters are significant. A quoted value surrounded by white space, or any characters other than - <literal>DELIMITER</>, will include those characters. This can cause - errors if you import data from a system that pads <literal>CSV</> + <literal>DELIMITER</literal>, will include those characters. This can cause + errors if you import data from a system that pads <literal>CSV</literal> lines with white space out to some fixed width. If such a situation - arises you might need to preprocess the <literal>CSV</> file to remove + arises you might need to preprocess the <literal>CSV</literal> file to remove the trailing white space, before importing the data into - <productname>PostgreSQL</>. + <productname>PostgreSQL</productname>. </para> </note> @@ -743,7 +743,7 @@ COPY <replaceable class="parameter">count</replaceable> Many programs produce strange and occasionally perverse CSV files, so the file format is more a convention than a standard. Thus you might encounter some files that cannot be imported using this - mechanism, and <command>COPY</> might produce files that other + mechanism, and <command>COPY</command> might produce files that other programs cannot process. </para> </note> @@ -756,17 +756,17 @@ COPY <replaceable class="parameter">count</replaceable> <para> The <literal>binary</literal> format option causes all data to be stored/read as binary format rather than as text. It is - somewhat faster than the text and <literal>CSV</> formats, + somewhat faster than the text and <literal>CSV</literal> formats, but a binary-format file is less portable across machine architectures and <productname>PostgreSQL</productname> versions. Also, the binary format is very data type specific; for example - it will not work to output binary data from a <type>smallint</> column - and read it into an <type>integer</> column, even though that would work + it will not work to output binary data from a <type>smallint</type> column + and read it into an <type>integer</type> column, even though that would work fine in text format. </para> <para> - The <literal>binary</> file format consists + The <literal>binary</literal> file format consists of a file header, zero or more tuples containing the row data, and a file trailer. Headers and data are in network byte order. </para> @@ -790,7 +790,7 @@ COPY <replaceable class="parameter">count</replaceable> <term>Signature</term> <listitem> <para> -11-byte sequence <literal>PGCOPY\n\377\r\n\0</> — note that the zero byte +11-byte sequence <literal>PGCOPY\n\377\r\n\0</literal> — note that the zero byte is a required part of the signature. (The signature is designed to allow easy identification of files that have been munged by a non-8-bit-clean transfer. This signature will be changed by end-of-line-translation @@ -804,7 +804,7 @@ filters, dropped zero bytes, dropped high bits, or parity changes.) <listitem> <para> 32-bit integer bit mask to denote important aspects of the file format. Bits -are numbered from 0 (<acronym>LSB</>) to 31 (<acronym>MSB</>). Note that +are numbered from 0 (<acronym>LSB</acronym>) to 31 (<acronym>MSB</acronym>). Note that this field is stored in network byte order (most significant byte first), as are all the integer fields used in the file format. Bits 16-31 are reserved to denote critical file format issues; a reader @@ -880,7 +880,7 @@ to be specified. <para> To determine the appropriate binary format for the actual tuple data you should consult the <productname>PostgreSQL</productname> source, in -particular the <function>*send</> and <function>*recv</> functions for +particular the <function>*send</function> and <function>*recv</function> functions for each column's data type (typically these functions are found in the <filename>src/backend/utils/adt/</filename> directory of the source distribution). @@ -924,7 +924,7 @@ COPY country TO STDOUT (DELIMITER '|'); </para> <para> - To copy data from a file into the <literal>country</> table: + To copy data from a file into the <literal>country</literal> table: <programlisting> COPY country FROM '/usr1/proj/bray/sql/country_data'; </programlisting> @@ -986,7 +986,7 @@ ZW ZIMBABWE </para> <para> - The following syntax was used before <productname>PostgreSQL</> + The following syntax was used before <productname>PostgreSQL</productname> version 9.0 and is still supported: <synopsis> @@ -1015,13 +1015,13 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable [ FORCE QUOTE { <replaceable class="parameter">column_name</replaceable> [, ...] | * } ] ] ] </synopsis> - Note that in this syntax, <literal>BINARY</> and <literal>CSV</> are - treated as independent keywords, not as arguments of a <literal>FORMAT</> + Note that in this syntax, <literal>BINARY</literal> and <literal>CSV</literal> are + treated as independent keywords, not as arguments of a <literal>FORMAT</literal> option. </para> <para> - The following syntax was used before <productname>PostgreSQL</> + The following syntax was used before <productname>PostgreSQL</productname> version 7.3 and is still supported: <synopsis> diff --git a/doc/src/sgml/ref/create_access_method.sgml b/doc/src/sgml/ref/create_access_method.sgml index 891926dba54..1bb1a79bd23 100644 --- a/doc/src/sgml/ref/create_access_method.sgml +++ b/doc/src/sgml/ref/create_access_method.sgml @@ -73,7 +73,7 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> <replaceable class="parameter">handler_function</replaceable> is the name (possibly schema-qualified) of a previously registered function that represents the access method. The handler function must be - declared to take a single argument of type <type>internal</>, + declared to take a single argument of type <type>internal</type>, and its return type depends on the type of access method; for <literal>INDEX</literal> access methods, it must be <type>index_am_handler</type>. The C-level API that the handler @@ -89,8 +89,8 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> <title>Examples</title> <para> - Create an index access method <literal>heptree</> with - handler function <literal>heptree_handler</>: + Create an index access method <literal>heptree</literal> with + handler function <literal>heptree_handler</literal>: <programlisting> CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; </programlisting></para> @@ -101,7 +101,7 @@ CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; <para> <command>CREATE ACCESS METHOD</command> is a - <productname>PostgreSQL</> extension. + <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index ee79c90df2b..3de30fa5808 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -98,7 +98,7 @@ CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( <para> If a schema name is given (for example, <literal>CREATE AGGREGATE - myschema.myagg ...</>) then the aggregate function is created in the + myschema.myagg ...</literal>) then the aggregate function is created in the specified schema. Otherwise it is created in the current schema. </para> @@ -191,57 +191,57 @@ CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( is polymorphic and the state value's data type would be inadequate to pin down the result type. These extra parameters are always passed as NULL (and so the final function must not be strict when - the <literal>FINALFUNC_EXTRA</> option is used), but nonetheless they + the <literal>FINALFUNC_EXTRA</literal> option is used), but nonetheless they are valid parameters. The final function could for example make use - of <function>get_fn_expr_argtype</> to identify the actual argument type + of <function>get_fn_expr_argtype</function> to identify the actual argument type in the current call. </para> <para> - An aggregate can optionally support <firstterm>moving-aggregate mode</>, + An aggregate can optionally support <firstterm>moving-aggregate mode</firstterm>, as described in <xref linkend="xaggr-moving-aggregates">. This requires - specifying the <literal>MSFUNC</>, <literal>MINVFUNC</>, - and <literal>MSTYPE</> parameters, and optionally - the <literal>MSPACE</>, <literal>MFINALFUNC</>, - <literal>MFINALFUNC_EXTRA</>, <literal>MFINALFUNC_MODIFY</>, - and <literal>MINITCOND</> parameters. Except for <literal>MINVFUNC</>, + specifying the <literal>MSFUNC</literal>, <literal>MINVFUNC</literal>, + and <literal>MSTYPE</literal> parameters, and optionally + the <literal>MSPACE</literal>, <literal>MFINALFUNC</literal>, + <literal>MFINALFUNC_EXTRA</literal>, <literal>MFINALFUNC_MODIFY</literal>, + and <literal>MINITCOND</literal> parameters. Except for <literal>MINVFUNC</literal>, these parameters work like the corresponding simple-aggregate parameters - without <literal>M</>; they define a separate implementation of the + without <literal>M</literal>; they define a separate implementation of the aggregate that includes an inverse transition function. </para> <para> The syntax with <literal>ORDER BY</literal> in the parameter list creates a special type of aggregate called an <firstterm>ordered-set - aggregate</firstterm>; or if <literal>HYPOTHETICAL</> is specified, then + aggregate</firstterm>; or if <literal>HYPOTHETICAL</literal> is specified, then a <firstterm>hypothetical-set aggregate</firstterm> is created. These aggregates operate over groups of sorted values in order-dependent ways, so that specification of an input sort order is an essential part of a - call. Also, they can have <firstterm>direct</> arguments, which are + call. Also, they can have <firstterm>direct</firstterm> arguments, which are arguments that are evaluated only once per aggregation rather than once per input row. Hypothetical-set aggregates are a subclass of ordered-set aggregates in which some of the direct arguments are required to match, in number and data types, the aggregated argument columns. This allows the values of those direct arguments to be added to the collection of - aggregate-input rows as an additional <quote>hypothetical</> row. + aggregate-input rows as an additional <quote>hypothetical</quote> row. </para> <para> - An aggregate can optionally support <firstterm>partial aggregation</>, + An aggregate can optionally support <firstterm>partial aggregation</firstterm>, as described in <xref linkend="xaggr-partial-aggregates">. - This requires specifying the <literal>COMBINEFUNC</> parameter. + This requires specifying the <literal>COMBINEFUNC</literal> parameter. If the <replaceable class="parameter">state_data_type</replaceable> - is <type>internal</>, it's usually also appropriate to provide the - <literal>SERIALFUNC</> and <literal>DESERIALFUNC</> parameters so that + is <type>internal</type>, it's usually also appropriate to provide the + <literal>SERIALFUNC</literal> and <literal>DESERIALFUNC</literal> parameters so that parallel aggregation is possible. Note that the aggregate must also be - marked <literal>PARALLEL SAFE</> to enable parallel aggregation. + marked <literal>PARALLEL SAFE</literal> to enable parallel aggregation. </para> <para> - Aggregates that behave like <function>MIN</> or <function>MAX</> can + Aggregates that behave like <function>MIN</function> or <function>MAX</function> can sometimes be optimized by looking into an index instead of scanning every input row. If this aggregate can be so optimized, indicate it by - specifying a <firstterm>sort operator</>. The basic requirement is that + specifying a <firstterm>sort operator</firstterm>. The basic requirement is that the aggregate must yield the first element in the sort ordering induced by the operator; in other words: <programlisting> @@ -253,9 +253,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </programlisting> Further assumptions are that the aggregate ignores null inputs, and that it delivers a null result if and only if there were no non-null inputs. - Ordinarily, a data type's <literal><</> operator is the proper sort - operator for <function>MIN</>, and <literal>></> is the proper sort - operator for <function>MAX</>. Note that the optimization will never + Ordinarily, a data type's <literal><</literal> operator is the proper sort + operator for <function>MIN</function>, and <literal>></literal> is the proper sort + operator for <function>MAX</function>. Note that the optimization will never actually take effect unless the specified operator is the <quote>less than</quote> or <quote>greater than</quote> strategy member of a B-tree index operator class. @@ -288,10 +288,10 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - (Aggregate functions do not support <literal>OUT</> arguments.) - If omitted, the default is <literal>IN</>. Only the last argument - can be marked <literal>VARIADIC</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + (Aggregate functions do not support <literal>OUT</literal> arguments.) + If omitted, the default is <literal>IN</literal>. Only the last argument + can be marked <literal>VARIADIC</literal>. </para> </listitem> </varlistentry> @@ -312,7 +312,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> An input data type on which this aggregate function operates. - To create a zero-argument aggregate function, write <literal>*</> + To create a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. (An example of such an aggregate is <function>count(*)</function>.) </para> @@ -323,12 +323,12 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <term><replaceable class="parameter">base_type</replaceable></term> <listitem> <para> - In the old syntax for <command>CREATE AGGREGATE</>, the input data type - is specified by a <literal>basetype</> parameter rather than being + In the old syntax for <command>CREATE AGGREGATE</command>, the input data type + is specified by a <literal>basetype</literal> parameter rather than being written next to the aggregate name. Note that this syntax allows only one input parameter. To define a zero-argument aggregate function - with this syntax, specify the <literal>basetype</> as - <literal>"ANY"</> (not <literal>*</>). + with this syntax, specify the <literal>basetype</literal> as + <literal>"ANY"</literal> (not <literal>*</literal>). Ordered-set aggregates cannot be defined with the old syntax. </para> </listitem> @@ -339,9 +339,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> The name of the state transition function to be called for each - input row. For a normal <replaceable class="parameter">N</>-argument - aggregate function, the <replaceable class="parameter">sfunc</> - must take <replaceable class="parameter">N</>+1 arguments, + input row. For a normal <replaceable class="parameter">N</replaceable>-argument + aggregate function, the <replaceable class="parameter">sfunc</replaceable> + must take <replaceable class="parameter">N</replaceable>+1 arguments, the first being of type <replaceable class="parameter">state_data_type</replaceable> and the rest matching the declared input data type(s) of the aggregate. @@ -375,7 +375,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The approximate average size (in bytes) of the aggregate's state value. If this parameter is omitted or is zero, a default estimate is used - based on the <replaceable>state_data_type</>. + based on the <replaceable>state_data_type</replaceable>. The planner uses this value to estimate the memory required for a grouped aggregate query. The planner will consider using hash aggregation for such a query only if the hash table is estimated to fit @@ -408,7 +408,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </para> <para> - If <literal>FINALFUNC_EXTRA</> is specified, then in addition to the + If <literal>FINALFUNC_EXTRA</literal> is specified, then in addition to the final state value and any direct arguments, the final function receives extra NULL values corresponding to the aggregate's regular (aggregated) arguments. This is mainly useful to allow correct @@ -419,16 +419,16 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> - <term><literal>FINALFUNC_MODIFY</> = { <literal>READ_ONLY</> | <literal>SHARABLE</> | <literal>READ_WRITE</> }</term> + <term><literal>FINALFUNC_MODIFY</literal> = { <literal>READ_ONLY</literal> | <literal>SHARABLE</literal> | <literal>READ_WRITE</literal> }</term> <listitem> <para> This option specifies whether the final function is a pure function - that does not modify its arguments. <literal>READ_ONLY</> indicates + that does not modify its arguments. <literal>READ_ONLY</literal> indicates it does not; the other two values indicate that it may change the transition state value. See <xref linkend="sql-createaggregate-notes" endterm="sql-createaggregate-notes-title"> below for more detail. The - default is <literal>READ_ONLY</>, except for ordered-set aggregates, - for which the default is <literal>READ_WRITE</>. + default is <literal>READ_ONLY</literal>, except for ordered-set aggregates, + for which the default is <literal>READ_WRITE</literal>. </para> </listitem> </varlistentry> @@ -482,11 +482,11 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> An aggregate function whose <replaceable class="parameter">state_data_type</replaceable> - is <type>internal</> can participate in parallel aggregation only if it + is <type>internal</type> can participate in parallel aggregation only if it has a <replaceable class="parameter">serialfunc</replaceable> function, - which must serialize the aggregate state into a <type>bytea</> value for + which must serialize the aggregate state into a <type>bytea</type> value for transmission to another process. This function must take a single - argument of type <type>internal</> and return type <type>bytea</>. A + argument of type <type>internal</type> and return type <type>bytea</type>. A corresponding <replaceable class="parameter">deserialfunc</replaceable> is also required. </para> @@ -499,9 +499,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Deserialize a previously serialized aggregate state back into <replaceable class="parameter">state_data_type</replaceable>. This - function must take two arguments of types <type>bytea</> - and <type>internal</>, and produce a result of type <type>internal</>. - (Note: the second, <type>internal</> argument is unused, but is required + function must take two arguments of types <type>bytea</type> + and <type>internal</type>, and produce a result of type <type>internal</type>. + (Note: the second, <type>internal</type> argument is unused, but is required for type safety reasons.) </para> </listitem> @@ -526,8 +526,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; The name of the forward state transition function to be called for each input row in moving-aggregate mode. This is exactly like the regular transition function, except that its first argument and result are of - type <replaceable>mstate_data_type</>, which might be different - from <replaceable>state_data_type</>. + type <replaceable>mstate_data_type</replaceable>, which might be different + from <replaceable>state_data_type</replaceable>. </para> </listitem> </varlistentry> @@ -538,7 +538,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The name of the inverse state transition function to be used in moving-aggregate mode. This function has the same argument and - result types as <replaceable>msfunc</>, but it is used to remove + result types as <replaceable>msfunc</replaceable>, but it is used to remove a value from the current aggregate state, rather than add a value to it. The inverse transition function must have the same strictness attribute as the forward state transition function. @@ -562,7 +562,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The approximate average size (in bytes) of the aggregate's state value, when using moving-aggregate mode. This works the same as - <replaceable>state_data_size</>. + <replaceable>state_data_size</replaceable>. </para> </listitem> </varlistentry> @@ -573,22 +573,22 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The name of the final function called to compute the aggregate's result after all input rows have been traversed, when using - moving-aggregate mode. This works the same as <replaceable>ffunc</>, + moving-aggregate mode. This works the same as <replaceable>ffunc</replaceable>, except that its first argument's type - is <replaceable>mstate_data_type</> and extra dummy arguments are - specified by writing <literal>MFINALFUNC_EXTRA</>. - The aggregate result type determined by <replaceable>mffunc</> - or <replaceable>mstate_data_type</> must match that determined by the + is <replaceable>mstate_data_type</replaceable> and extra dummy arguments are + specified by writing <literal>MFINALFUNC_EXTRA</literal>. + The aggregate result type determined by <replaceable>mffunc</replaceable> + or <replaceable>mstate_data_type</replaceable> must match that determined by the aggregate's regular implementation. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>MFINALFUNC_MODIFY</> = { <literal>READ_ONLY</> | <literal>SHARABLE</> | <literal>READ_WRITE</> }</term> + <term><literal>MFINALFUNC_MODIFY</literal> = { <literal>READ_ONLY</literal> | <literal>SHARABLE</literal> | <literal>READ_WRITE</literal> }</term> <listitem> <para> - This option is like <literal>FINALFUNC_MODIFY</>, but it describes + This option is like <literal>FINALFUNC_MODIFY</literal>, but it describes the behavior of the moving-aggregate final function. </para> </listitem> @@ -599,7 +599,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> The initial setting for the state value, when using moving-aggregate - mode. This works the same as <replaceable>initial_condition</>. + mode. This works the same as <replaceable>initial_condition</replaceable>. </para> </listitem> </varlistentry> @@ -608,8 +608,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <term><replaceable class="parameter">sort_operator</replaceable></term> <listitem> <para> - The associated sort operator for a <function>MIN</>- or - <function>MAX</>-like aggregate. + The associated sort operator for a <function>MIN</function>- or + <function>MAX</function>-like aggregate. This is just an operator name (possibly schema-qualified). The operator is assumed to have the same input data types as the aggregate (which must be a single-argument normal aggregate). @@ -618,14 +618,14 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> - <term><literal>PARALLEL =</> { <literal>SAFE</> | <literal>RESTRICTED</> | <literal>UNSAFE</> }</term> + <term><literal>PARALLEL =</literal> { <literal>SAFE</literal> | <literal>RESTRICTED</literal> | <literal>UNSAFE</literal> }</term> <listitem> <para> - The meanings of <literal>PARALLEL SAFE</>, <literal>PARALLEL - RESTRICTED</>, and <literal>PARALLEL UNSAFE</> are the same as + The meanings of <literal>PARALLEL SAFE</literal>, <literal>PARALLEL + RESTRICTED</literal>, and <literal>PARALLEL UNSAFE</literal> are the same as in <xref linkend="sql-createfunction">. An aggregate will not be considered for parallelization if it is marked <literal>PARALLEL - UNSAFE</> (which is the default!) or <literal>PARALLEL RESTRICTED</>. + UNSAFE</literal> (which is the default!) or <literal>PARALLEL RESTRICTED</literal>. Note that the parallel-safety markings of the aggregate's support functions are not consulted by the planner, only the marking of the aggregate itself. @@ -640,7 +640,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; For ordered-set aggregates only, this flag specifies that the aggregate arguments are to be processed according to the requirements for hypothetical-set aggregates: that is, the last few direct arguments must - match the data types of the aggregated (<literal>WITHIN GROUP</>) + match the data types of the aggregated (<literal>WITHIN GROUP</literal>) arguments. The <literal>HYPOTHETICAL</literal> flag has no effect on run-time behavior, only on parse-time resolution of the data types and collations of the aggregate's arguments. @@ -660,7 +660,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> In parameters that specify support function names, you can write - a schema name if needed, for example <literal>SFUNC = public.sum</>. + a schema name if needed, for example <literal>SFUNC = public.sum</literal>. Do not write argument types there, however — the argument types of the support functions are determined from other parameters. </para> @@ -668,7 +668,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Ordinarily, PostgreSQL functions are expected to be true functions that do not modify their input values. However, an aggregate transition - function, <emphasis>when used in the context of an aggregate</>, + function, <emphasis>when used in the context of an aggregate</emphasis>, is allowed to cheat and modify its transition-state argument in place. This can provide substantial performance benefits compared to making a fresh copy of the transition state each time. @@ -678,26 +678,26 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; Likewise, while an aggregate final function is normally expected not to modify its input values, sometimes it is impractical to avoid modifying the transition-state argument. Such behavior must be declared using - the <literal>FINALFUNC_MODIFY</> parameter. The <literal>READ_WRITE</> + the <literal>FINALFUNC_MODIFY</literal> parameter. The <literal>READ_WRITE</literal> value indicates that the final function modifies the transition state in unspecified ways. This value prevents use of the aggregate as a window function, and it also prevents merging of transition states for aggregate calls that share the same input values and transition functions. - The <literal>SHARABLE</> value indicates that the transition function + The <literal>SHARABLE</literal> value indicates that the transition function cannot be applied after the final function, but multiple final-function calls can be performed on the ending transition state value. This value prevents use of the aggregate as a window function, but it allows merging of transition states. (That is, the optimization of interest here is not applying the same final function repeatedly, but applying different final functions to the same ending transition state value. This is allowed as - long as none of the final functions are marked <literal>READ_WRITE</>.) + long as none of the final functions are marked <literal>READ_WRITE</literal>.) </para> <para> If an aggregate supports moving-aggregate mode, it will improve calculation efficiency when the aggregate is used as a window function for a window with moving frame start (that is, a frame start mode other - than <literal>UNBOUNDED PRECEDING</>). Conceptually, the forward + than <literal>UNBOUNDED PRECEDING</literal>). Conceptually, the forward transition function adds input values to the aggregate's state when they enter the window frame from the bottom, and the inverse transition function removes them again when they leave the frame at the top. So, @@ -738,20 +738,20 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </para> <para> - The syntax for ordered-set aggregates allows <literal>VARIADIC</> + The syntax for ordered-set aggregates allows <literal>VARIADIC</literal> to be specified for both the last direct parameter and the last - aggregated (<literal>WITHIN GROUP</>) parameter. However, the - current implementation restricts use of <literal>VARIADIC</> + aggregated (<literal>WITHIN GROUP</literal>) parameter. However, the + current implementation restricts use of <literal>VARIADIC</literal> in two ways. First, ordered-set aggregates can only use - <literal>VARIADIC "any"</>, not other variadic array types. - Second, if the last direct parameter is <literal>VARIADIC "any"</>, + <literal>VARIADIC "any"</literal>, not other variadic array types. + Second, if the last direct parameter is <literal>VARIADIC "any"</literal>, then there can be only one aggregated parameter and it must also - be <literal>VARIADIC "any"</>. (In the representation used in the + be <literal>VARIADIC "any"</literal>. (In the representation used in the system catalogs, these two parameters are merged into a single - <literal>VARIADIC "any"</> item, since <structname>pg_proc</> cannot - represent functions with more than one <literal>VARIADIC</> parameter.) + <literal>VARIADIC "any"</literal> item, since <structname>pg_proc</structname> cannot + represent functions with more than one <literal>VARIADIC</literal> parameter.) If the aggregate is a hypothetical-set aggregate, the direct arguments - that match the <literal>VARIADIC "any"</> parameter are the hypothetical + that match the <literal>VARIADIC "any"</literal> parameter are the hypothetical ones; any preceding parameters represent additional direct arguments that are not constrained to match the aggregated arguments. </para> @@ -764,7 +764,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Partial (including parallel) aggregation is currently not supported for ordered-set aggregates. Also, it will never be used for aggregate calls - that include <literal>DISTINCT</> or <literal>ORDER BY</> clauses, since + that include <literal>DISTINCT</literal> or <literal>ORDER BY</literal> clauses, since those semantics cannot be supported during partial aggregation. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml index a7d13edc22b..89af1e50519 100644 --- a/doc/src/sgml/ref/create_cast.sgml +++ b/doc/src/sgml/ref/create_cast.sgml @@ -44,7 +44,7 @@ SELECT CAST(42 AS float8); </programlisting> converts the integer constant 42 to type <type>float8</type> by invoking a previously specified function, in this case - <literal>float8(int4)</>. (If no suitable cast has been defined, the + <literal>float8(int4)</literal>. (If no suitable cast has been defined, the conversion fails.) </para> @@ -64,7 +64,7 @@ SELECT CAST(42 AS float8); </para> <para> - You can define a cast as an <firstterm>I/O conversion cast</> by using + You can define a cast as an <firstterm>I/O conversion cast</firstterm> by using the <literal>WITH INOUT</literal> syntax. An I/O conversion cast is performed by invoking the output function of the source data type, and passing the resulting string to the input function of the target data type. @@ -75,14 +75,14 @@ SELECT CAST(42 AS float8); <para> By default, a cast can be invoked only by an explicit cast request, - that is an explicit <literal>CAST(<replaceable>x</> AS - <replaceable>typename</>)</literal> or - <replaceable>x</><literal>::</><replaceable>typename</> + that is an explicit <literal>CAST(<replaceable>x</replaceable> AS + <replaceable>typename</replaceable>)</literal> or + <replaceable>x</replaceable><literal>::</literal><replaceable>typename</replaceable> construct. </para> <para> - If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked + If the cast is marked <literal>AS ASSIGNMENT</literal> then it can be invoked implicitly when assigning a value to a column of the target data type. For example, supposing that <literal>foo.f1</literal> is a column of type <type>text</type>, then: @@ -90,13 +90,13 @@ SELECT CAST(42 AS float8); INSERT INTO foo (f1) VALUES (42); </programlisting> will be allowed if the cast from type <type>integer</type> to type - <type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise not. + <type>text</type> is marked <literal>AS ASSIGNMENT</literal>, otherwise not. (We generally use the term <firstterm>assignment cast</firstterm> to describe this kind of cast.) </para> <para> - If the cast is marked <literal>AS IMPLICIT</> then it can be invoked + If the cast is marked <literal>AS IMPLICIT</literal> then it can be invoked implicitly in any context, whether assignment or internally in an expression. (We generally use the term <firstterm>implicit cast</firstterm> to describe this kind of cast.) @@ -104,12 +104,12 @@ INSERT INTO foo (f1) VALUES (42); <programlisting> SELECT 2 + 4.0; </programlisting> - The parser initially marks the constants as being of type <type>integer</> - and <type>numeric</> respectively. There is no <type>integer</> - <literal>+</> <type>numeric</> operator in the system catalogs, - but there is a <type>numeric</> <literal>+</> <type>numeric</> operator. - The query will therefore succeed if a cast from <type>integer</> to - <type>numeric</> is available and is marked <literal>AS IMPLICIT</> — + The parser initially marks the constants as being of type <type>integer</type> + and <type>numeric</type> respectively. There is no <type>integer</type> + <literal>+</literal> <type>numeric</type> operator in the system catalogs, + but there is a <type>numeric</type> <literal>+</literal> <type>numeric</type> operator. + The query will therefore succeed if a cast from <type>integer</type> to + <type>numeric</type> is available and is marked <literal>AS IMPLICIT</literal> — which in fact it is. The parser will apply the implicit cast and resolve the query as if it had been written <programlisting> @@ -118,17 +118,17 @@ SELECT CAST ( 2 AS numeric ) + 4.0; </para> <para> - Now, the catalogs also provide a cast from <type>numeric</> to - <type>integer</>. If that cast were marked <literal>AS IMPLICIT</> — + Now, the catalogs also provide a cast from <type>numeric</type> to + <type>integer</type>. If that cast were marked <literal>AS IMPLICIT</literal> — which it is not — then the parser would be faced with choosing between the above interpretation and the alternative of casting the - <type>numeric</> constant to <type>integer</> and applying the - <type>integer</> <literal>+</> <type>integer</> operator. Lacking any + <type>numeric</type> constant to <type>integer</type> and applying the + <type>integer</type> <literal>+</literal> <type>integer</type> operator. Lacking any knowledge of which choice to prefer, it would give up and declare the query ambiguous. The fact that only one of the two casts is implicit is the way in which we teach the parser to prefer resolution - of a mixed <type>numeric</>-and-<type>integer</> expression as - <type>numeric</>; there is no built-in knowledge about that. + of a mixed <type>numeric</type>-and-<type>integer</type> expression as + <type>numeric</type>; there is no built-in knowledge about that. </para> <para> @@ -142,8 +142,8 @@ SELECT CAST ( 2 AS numeric ) + 4.0; general type category. For example, the cast from <type>int2</type> to <type>int4</type> can reasonably be implicit, but the cast from <type>float8</type> to <type>int4</type> should probably be - assignment-only. Cross-type-category casts, such as <type>text</> - to <type>int4</>, are best made explicit-only. + assignment-only. Cross-type-category casts, such as <type>text</type> + to <type>int4</type>, are best made explicit-only. </para> <note> @@ -151,8 +151,8 @@ SELECT CAST ( 2 AS numeric ) + 4.0; Sometimes it is necessary for usability or standards-compliance reasons to provide multiple implicit casts among a set of types, resulting in ambiguity that cannot be avoided as above. The parser has a fallback - heuristic based on <firstterm>type categories</> and <firstterm>preferred - types</> that can help to provide desired behavior in such cases. See + heuristic based on <firstterm>type categories</firstterm> and <firstterm>preferred + types</firstterm> that can help to provide desired behavior in such cases. See <xref linkend="sql-createtype"> for more information. </para> @@ -255,11 +255,11 @@ SELECT CAST ( 2 AS numeric ) + 4.0; Cast implementation functions can have one to three arguments. The first argument type must be identical to or binary-coercible from the cast's source type. The second argument, - if present, must be type <type>integer</>; it receives the type - modifier associated with the destination type, or <literal>-1</> + if present, must be type <type>integer</type>; it receives the type + modifier associated with the destination type, or <literal>-1</literal> if there is none. The third argument, - if present, must be type <type>boolean</>; it receives <literal>true</> - if the cast is an explicit cast, <literal>false</> otherwise. + if present, must be type <type>boolean</type>; it receives <literal>true</literal> + if the cast is an explicit cast, <literal>false</literal> otherwise. (Bizarrely, the SQL standard demands different behaviors for explicit and implicit casts in some cases. This argument is supplied for functions that must implement such casts. It is not recommended that you design @@ -316,9 +316,9 @@ SELECT CAST ( 2 AS numeric ) + 4.0; <para> It is normally not necessary to create casts between user-defined types - and the standard string types (<type>text</>, <type>varchar</>, and - <type>char(<replaceable>n</>)</type>, as well as user-defined types that - are defined to be in the string category). <productname>PostgreSQL</> + and the standard string types (<type>text</type>, <type>varchar</type>, and + <type>char(<replaceable>n</replaceable>)</type>, as well as user-defined types that + are defined to be in the string category). <productname>PostgreSQL</productname> provides automatic I/O conversion casts for that. The automatic casts to string types are treated as assignment casts, while the automatic casts from string types are @@ -338,11 +338,11 @@ SELECT CAST ( 2 AS numeric ) + 4.0; convention of naming cast implementation functions after the target data type. Many users are used to being able to cast data types using a function-style notation, that is - <replaceable>typename</>(<replaceable>x</>). This notation is in fact + <replaceable>typename</replaceable>(<replaceable>x</replaceable>). This notation is in fact nothing more nor less than a call of the cast implementation function; it is not specially treated as a cast. If your conversion functions are not named to support this convention then you will have surprised users. - Since <productname>PostgreSQL</> allows overloading of the same function + Since <productname>PostgreSQL</productname> allows overloading of the same function name with different argument types, there is no difficulty in having multiple conversion functions from different types that all use the target type's name. @@ -353,14 +353,14 @@ SELECT CAST ( 2 AS numeric ) + 4.0; Actually the preceding paragraph is an oversimplification: there are two cases in which a function-call construct will be treated as a cast request without having matched it to an actual function. - If a function call <replaceable>name</>(<replaceable>x</>) does not - exactly match any existing function, but <replaceable>name</> is the name - of a data type and <structname>pg_cast</> provides a binary-coercible cast - to this type from the type of <replaceable>x</>, then the call will be + If a function call <replaceable>name</replaceable>(<replaceable>x</replaceable>) does not + exactly match any existing function, but <replaceable>name</replaceable> is the name + of a data type and <structname>pg_cast</structname> provides a binary-coercible cast + to this type from the type of <replaceable>x</replaceable>, then the call will be construed as a binary-coercible cast. This exception is made so that binary-coercible casts can be invoked using functional syntax, even though they lack any function. Likewise, if there is no - <structname>pg_cast</> entry but the cast would be to or from a string + <structname>pg_cast</structname> entry but the cast would be to or from a string type, the call will be construed as an I/O conversion cast. This exception allows I/O conversion casts to be invoked using functional syntax. @@ -372,7 +372,7 @@ SELECT CAST ( 2 AS numeric ) + 4.0; There is also an exception to the exception: I/O conversion casts from composite types to string types cannot be invoked using functional syntax, but must be written in explicit cast syntax (either - <literal>CAST</> or <literal>::</> notation). This exception was added + <literal>CAST</literal> or <literal>::</literal> notation). This exception was added because after the introduction of automatically-provided I/O conversion casts, it was found too easy to accidentally invoke such a cast when a function or column reference was intended. @@ -402,7 +402,7 @@ CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT; <acronym>SQL</acronym> standard, except that SQL does not make provisions for binary-coercible types or extra arguments to implementation functions. - <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname> + <literal>AS IMPLICIT</literal> is a <productname>PostgreSQL</productname> extension, too. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml index f88758095f2..d4e99e925f0 100644 --- a/doc/src/sgml/ref/create_collation.sgml +++ b/doc/src/sgml/ref/create_collation.sgml @@ -116,7 +116,7 @@ CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replace <para> Specifies the provider to use for locale services associated with this collation. Possible values - are: <literal>icu</literal>,<indexterm><primary>ICU</></> + are: <literal>icu</literal>,<indexterm><primary>ICU</primary></indexterm> <literal>libc</literal>. <literal>libc</literal> is the default. The available choices depend on the operating system and build options. diff --git a/doc/src/sgml/ref/create_conversion.sgml b/doc/src/sgml/ref/create_conversion.sgml index d2e2c010ef3..03e0315eef7 100644 --- a/doc/src/sgml/ref/create_conversion.sgml +++ b/doc/src/sgml/ref/create_conversion.sgml @@ -29,7 +29,7 @@ CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> <para> <command>CREATE CONVERSION</command> defines a new conversion between character set encodings. Also, conversions that - are marked <literal>DEFAULT</> can be used for automatic encoding + are marked <literal>DEFAULT</literal> can be used for automatic encoding conversion between client and server. For this purpose, two conversions, from encoding A to B <emphasis>and</emphasis> from encoding B to A, must be defined. @@ -51,7 +51,7 @@ CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> <listitem> <para> - The <literal>DEFAULT</> clause indicates that this conversion + The <literal>DEFAULT</literal> clause indicates that this conversion is the default for this particular source to destination encoding. There should be only one default encoding in a schema for the encoding pair. @@ -137,7 +137,7 @@ conv_proc( <para> To create a conversion from encoding <literal>UTF8</literal> to - <literal>LATIN1</literal> using <function>myfunc</>: + <literal>LATIN1</literal> using <function>myfunc</function>: <programlisting> CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc; </programlisting></para> diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 8e2a73402f4..8adfa3a37bf 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -44,21 +44,21 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> To create a database, you must be a superuser or have the special - <literal>CREATEDB</> privilege. + <literal>CREATEDB</literal> privilege. See <xref linkend="SQL-CREATEUSER">. </para> <para> By default, the new database will be created by cloning the standard - system database <literal>template1</>. A different template can be + system database <literal>template1</literal>. A different template can be specified by writing <literal>TEMPLATE <replaceable class="parameter">name</replaceable></literal>. In particular, - by writing <literal>TEMPLATE template0</>, you can create a virgin + by writing <literal>TEMPLATE template0</literal>, you can create a virgin database containing only the standard objects predefined by your version of <productname>PostgreSQL</productname>. This is useful if you wish to avoid copying any installation-local objects that might have been added to - <literal>template1</>. + <literal>template1</literal>. </para> </refsect1> @@ -115,7 +115,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <term><replaceable class="parameter">lc_collate</replaceable></term> <listitem> <para> - Collation order (<literal>LC_COLLATE</>) to use in the new database. + Collation order (<literal>LC_COLLATE</literal>) to use in the new database. This affects the sort order applied to strings, e.g. in queries with ORDER BY, as well as the order used in indexes on text columns. The default is to use the collation order of the template database. @@ -127,7 +127,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <term><replaceable class="parameter">lc_ctype</replaceable></term> <listitem> <para> - Character classification (<literal>LC_CTYPE</>) to use in the new + Character classification (<literal>LC_CTYPE</literal>) to use in the new database. This affects the categorization of characters, e.g. lower, upper and digit. The default is to use the character classification of the template database. See below for additional restrictions. @@ -155,7 +155,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> If false then no one can connect to this database. The default is true, allowing connections (except as restricted by other mechanisms, - such as <literal>GRANT</>/<literal>REVOKE CONNECT</>). + such as <literal>GRANT</literal>/<literal>REVOKE CONNECT</literal>). </para> </listitem> </varlistentry> @@ -192,12 +192,12 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>CREATE DATABASE</> cannot be executed inside a transaction + <command>CREATE DATABASE</command> cannot be executed inside a transaction block. </para> <para> - Errors along the line of <quote>could not initialize database directory</> + Errors along the line of <quote>could not initialize database directory</quote> are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems. </para> @@ -218,26 +218,26 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> </para> <para> - Although it is possible to copy a database other than <literal>template1</> + Although it is possible to copy a database other than <literal>template1</literal> by specifying its name as the template, this is not (yet) intended as a general-purpose <quote><command>COPY DATABASE</command></quote> facility. The principal limitation is that no other sessions can be connected to the template database while it is being copied. <command>CREATE - DATABASE</> will fail if any other connection exists when it starts; + DATABASE</command> will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out - until <command>CREATE DATABASE</> completes. + until <command>CREATE DATABASE</command> completes. See <xref linkend="manage-ag-templatedbs"> for more information. </para> <para> The character set encoding specified for the new database must be - compatible with the chosen locale settings (<literal>LC_COLLATE</> and - <literal>LC_CTYPE</>). If the locale is <literal>C</> (or equivalently - <literal>POSIX</>), then all encodings are allowed, but for other + compatible with the chosen locale settings (<literal>LC_COLLATE</literal> and + <literal>LC_CTYPE</literal>). If the locale is <literal>C</literal> (or equivalently + <literal>POSIX</literal>), then all encodings are allowed, but for other locale settings there is only one encoding that will work properly. (On Windows, however, UTF-8 encoding can be used with any locale.) - <command>CREATE DATABASE</> will allow superusers to specify - <literal>SQL_ASCII</> encoding regardless of the locale settings, + <command>CREATE DATABASE</command> will allow superusers to specify + <literal>SQL_ASCII</literal> encoding regardless of the locale settings, but this choice is deprecated and may result in misbehavior of character-string functions if data that is not encoding-compatible with the locale is stored in the database. @@ -245,19 +245,19 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> The encoding and locale settings must match those of the template database, - except when <literal>template0</> is used as template. This is because + except when <literal>template0</literal> is used as template. This is because other databases might contain data that does not match the specified encoding, or might contain indexes whose sort ordering is affected by - <literal>LC_COLLATE</> and <literal>LC_CTYPE</>. Copying such data would + <literal>LC_COLLATE</literal> and <literal>LC_CTYPE</literal>. Copying such data would result in a database that is corrupt according to the new settings. <literal>template0</literal>, however, is known to not contain any data or indexes that would be affected. </para> <para> - The <literal>CONNECTION LIMIT</> option is only enforced approximately; + The <literal>CONNECTION LIMIT</literal> option is only enforced approximately; if two new sessions start at about the same time when just one - connection <quote>slot</> remains for the database, it is possible that + connection <quote>slot</quote> remains for the database, it is possible that both will fail. Also, the limit is not enforced against superusers or background worker processes. </para> @@ -275,8 +275,8 @@ CREATE DATABASE lusiadas; </para> <para> - To create a database <literal>sales</> owned by user <literal>salesapp</> - with a default tablespace of <literal>salesspace</>: + To create a database <literal>sales</literal> owned by user <literal>salesapp</literal> + with a default tablespace of <literal>salesspace</literal>: <programlisting> CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; @@ -284,19 +284,19 @@ CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; </para> <para> - To create a database <literal>music</> with a different locale: + To create a database <literal>music</literal> with a different locale: <programlisting> CREATE DATABASE music LC_COLLATE 'sv_SE.utf8' LC_CTYPE 'sv_SE.utf8' TEMPLATE template0; </programlisting> - In this example, the <literal>TEMPLATE template0</> clause is required if - the specified locale is different from the one in <literal>template1</>. + In this example, the <literal>TEMPLATE template0</literal> clause is required if + the specified locale is different from the one in <literal>template1</literal>. (If it is not, then specifying the locale explicitly is redundant.) </para> <para> - To create a database <literal>music2</> with a different locale and a + To create a database <literal>music2</literal> with a different locale and a different character set encoding: <programlisting> CREATE DATABASE music2 diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml index 85ed57dd088..705ff55c49f 100644 --- a/doc/src/sgml/ref/create_domain.sgml +++ b/doc/src/sgml/ref/create_domain.sgml @@ -45,7 +45,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> If a schema name is given (for example, <literal>CREATE DOMAIN - myschema.mydomain ...</>) then the domain is created in the + myschema.mydomain ...</literal>) then the domain is created in the specified schema. Otherwise it is created in the current schema. The domain name must be unique among the types and domains existing in its schema. @@ -95,7 +95,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> An optional collation for the domain. If no collation is specified, the underlying data type's default collation is used. - The underlying type must be collatable if <literal>COLLATE</> + The underlying type must be collatable if <literal>COLLATE</literal> is specified. </para> </listitem> @@ -106,7 +106,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <listitem> <para> - The <literal>DEFAULT</> clause specifies a default value for + The <literal>DEFAULT</literal> clause specifies a default value for columns of the domain data type. The value is any variable-free expression (but subqueries are not allowed). The data type of the default expression must match the data @@ -136,7 +136,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> Values of this domain are prevented from being null @@ -146,7 +146,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> Values of this domain are allowed to be null. This is the default. @@ -163,10 +163,10 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <varlistentry> <term><literal>CHECK (<replaceable class="parameter">expression</replaceable>)</literal></term> <listitem> - <para><literal>CHECK</> clauses specify integrity constraints or tests + <para><literal>CHECK</literal> clauses specify integrity constraints or tests which values of the domain must satisfy. Each constraint must be an expression - producing a Boolean result. It should use the key word <literal>VALUE</> + producing a Boolean result. It should use the key word <literal>VALUE</literal> to refer to the value being tested. Expressions evaluating to TRUE or UNKNOWN succeed. If the expression produces a FALSE result, an error is reported and the value is not allowed to be converted @@ -175,13 +175,13 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> Currently, <literal>CHECK</literal> expressions cannot contain - subqueries nor refer to variables other than <literal>VALUE</>. + subqueries nor refer to variables other than <literal>VALUE</literal>. </para> <para> When a domain has multiple <literal>CHECK</literal> constraints, they will be tested in alphabetical order by name. - (<productname>PostgreSQL</> versions before 9.5 did not honor any + (<productname>PostgreSQL</productname> versions before 9.5 did not honor any particular firing order for <literal>CHECK</literal> constraints.) </para> </listitem> @@ -193,7 +193,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <title>Notes</title> <para> - Domain constraints, particularly <literal>NOT NULL</>, are checked when + Domain constraints, particularly <literal>NOT NULL</literal>, are checked when converting a value to the domain type. It is possible for a column that is nominally of the domain type to read as null despite there being such a constraint. For example, this can happen in an outer-join query, if @@ -211,7 +211,7 @@ INSERT INTO tab (domcol) VALUES ((SELECT domcol FROM tab WHERE false)); It is very difficult to avoid such problems, because of SQL's general assumption that a null value is a valid value of every data type. Best practice therefore is to design a domain's constraints so that a null value is allowed, - and then to apply column <literal>NOT NULL</> constraints to columns of + and then to apply column <literal>NOT NULL</literal> constraints to columns of the domain type as needed, rather than directly to the domain type. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_event_trigger.sgml b/doc/src/sgml/ref/create_event_trigger.sgml index 7decfbb983c..9652f024121 100644 --- a/doc/src/sgml/ref/create_event_trigger.sgml +++ b/doc/src/sgml/ref/create_event_trigger.sgml @@ -33,7 +33,7 @@ CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable> <para> <command>CREATE EVENT TRIGGER</command> creates a new event trigger. - Whenever the designated event occurs and the <literal>WHEN</> condition + Whenever the designated event occurs and the <literal>WHEN</literal> condition associated with the trigger, if any, is satisfied, the trigger function will be executed. For a general introduction to event triggers, see <xref linkend="event-triggers">. The user who creates an event trigger @@ -85,8 +85,8 @@ CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable> <para> A list of values for the associated <replaceable class="parameter">filter_variable</replaceable> - for which the trigger should fire. For <literal>TAG</>, this means a - list of command tags (e.g. <literal>'DROP FUNCTION'</>). + for which the trigger should fire. For <literal>TAG</literal>, this means a + list of command tags (e.g. <literal>'DROP FUNCTION'</literal>). </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml index 14e910115ab..a3a7892812a 100644 --- a/doc/src/sgml/ref/create_extension.sgml +++ b/doc/src/sgml/ref/create_extension.sgml @@ -39,7 +39,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <para> Loading an extension essentially amounts to running the extension's script - file. The script will typically create new <acronym>SQL</> objects such as + file. The script will typically create new <acronym>SQL</acronym> objects such as functions, data types, operators and index support methods. <command>CREATE EXTENSION</command> additionally records the identities of all the created objects, so that they can be dropped again if @@ -62,7 +62,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if an extension with the same name already @@ -97,17 +97,17 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name </para> <para> - If the extension specifies a <literal>schema</> parameter in its + If the extension specifies a <literal>schema</literal> parameter in its control file, then that schema cannot be overridden with - a <literal>SCHEMA</> clause. Normally, an error will be raised if - a <literal>SCHEMA</> clause is given and it conflicts with the - extension's <literal>schema</> parameter. However, if - the <literal>CASCADE</> clause is also given, + a <literal>SCHEMA</literal> clause. Normally, an error will be raised if + a <literal>SCHEMA</literal> clause is given and it conflicts with the + extension's <literal>schema</literal> parameter. However, if + the <literal>CASCADE</literal> clause is also given, then <replaceable class="parameter">schema_name</replaceable> is ignored when it conflicts. The given <replaceable class="parameter">schema_name</replaceable> will be used for installation of any needed extensions that do not - specify <literal>schema</> in their control files. + specify <literal>schema</literal> in their control files. </para> <para> @@ -134,13 +134,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <term><replaceable class="parameter">old_version</replaceable></term> <listitem> <para> - <literal>FROM</> <replaceable class="parameter">old_version</> + <literal>FROM</literal> <replaceable class="parameter">old_version</replaceable> must be specified when, and only when, you are attempting to install - an extension that replaces an <quote>old style</> module that is just + an extension that replaces an <quote>old style</quote> module that is just a collection of objects not packaged into an extension. This option - causes <command>CREATE EXTENSION</> to run an alternative installation + causes <command>CREATE EXTENSION</command> to run an alternative installation script that absorbs the existing objects into the extension, instead - of creating new objects. Be careful that <literal>SCHEMA</> specifies + of creating new objects. Be careful that <literal>SCHEMA</literal> specifies the schema containing these pre-existing objects. </para> @@ -150,7 +150,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name extension's author, and might vary if there is more than one version of the old-style module that can be upgraded into an extension. For the standard additional modules supplied with pre-9.1 - <productname>PostgreSQL</productname>, use <literal>unpackaged</> + <productname>PostgreSQL</productname>, use <literal>unpackaged</literal> for <replaceable class="parameter">old_version</replaceable> when updating a module to extension style. </para> @@ -158,12 +158,12 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name </varlistentry> <varlistentry> - <term><literal>CASCADE</></term> + <term><literal>CASCADE</literal></term> <listitem> <para> Automatically install any extensions that this extension depends on that are not already installed. Their dependencies are likewise - automatically installed, recursively. The <literal>SCHEMA</> clause, + automatically installed, recursively. The <literal>SCHEMA</literal> clause, if given, applies to all extensions that get installed this way. Other options of the statement are not applied to automatically-installed extensions; in particular, their default @@ -178,7 +178,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <title>Notes</title> <para> - Before you can use <command>CREATE EXTENSION</> to load an extension + Before you can use <command>CREATE EXTENSION</command> to load an extension into a database, the extension's supporting files must be installed. Information about installing the extensions supplied with <productname>PostgreSQL</productname> can be found in @@ -211,13 +211,13 @@ CREATE EXTENSION hstore; </para> <para> - Update a pre-9.1 installation of <literal>hstore</> into + Update a pre-9.1 installation of <literal>hstore</literal> into extension style: <programlisting> CREATE EXTENSION hstore SCHEMA public FROM unpackaged; </programlisting> Be careful to specify the schema in which you installed the existing - <literal>hstore</> objects. + <literal>hstore</literal> objects. </para> </refsect1> @@ -225,7 +225,7 @@ CREATE EXTENSION hstore SCHEMA public FROM unpackaged; <title>Compatibility</title> <para> - <command>CREATE EXTENSION</command> is a <productname>PostgreSQL</> + <command>CREATE EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml index 1161e05d1c6..87403a55e3b 100644 --- a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml @@ -117,7 +117,7 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <productname>PostgreSQL</>'s foreign-data functionality is still under + <productname>PostgreSQL</productname>'s foreign-data functionality is still under active development. Optimization of queries is primitive (and mostly left to the wrapper, too). Thus, there is considerable room for future performance improvements. @@ -128,22 +128,22 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> <title>Examples</title> <para> - Create a useless foreign-data wrapper <literal>dummy</>: + Create a useless foreign-data wrapper <literal>dummy</literal>: <programlisting> CREATE FOREIGN DATA WRAPPER dummy; </programlisting> </para> <para> - Create a foreign-data wrapper <literal>file</> with - handler function <literal>file_fdw_handler</>: + Create a foreign-data wrapper <literal>file</literal> with + handler function <literal>file_fdw_handler</literal>: <programlisting> CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler; </programlisting> </para> <para> - Create a foreign-data wrapper <literal>mywrapper</> with some + Create a foreign-data wrapper <literal>mywrapper</literal> with some options: <programlisting> CREATE FOREIGN DATA WRAPPER mywrapper @@ -159,7 +159,7 @@ CREATE FOREIGN DATA WRAPPER mywrapper 9075-9 (SQL/MED), with the exception that the <literal>HANDLER</literal> and <literal>VALIDATOR</literal> clauses are extensions and the standard clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal> - are not implemented in <productname>PostgreSQL</>. + are not implemented in <productname>PostgreSQL</productname>. </para> <para> diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml index f514b2d59f3..47705fd187e 100644 --- a/doc/src/sgml/ref/create_foreign_table.sgml +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -62,7 +62,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <para> If a schema name is given (for example, <literal>CREATE FOREIGN TABLE - myschema.mytable ...</>) then the table is created in the specified + myschema.mytable ...</literal>) then the table is created in the specified schema. Otherwise it is created in the current schema. The name of the foreign table must be distinct from the name of any other foreign table, table, sequence, index, @@ -95,7 +95,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -140,7 +140,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>COLLATE <replaceable>collation</replaceable></literal></term> <listitem> <para> - The <literal>COLLATE</> clause assigns a collation to + The <literal>COLLATE</literal> clause assigns a collation to the column (which must be of a collatable data type). If not specified, the column data type's default collation is used. </para> @@ -151,7 +151,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term> <listitem> <para> - The optional <literal>INHERITS</> clause specifies a list of + The optional <literal>INHERITS</literal> clause specifies a list of tables from which the new foreign table automatically inherits all columns. Parent tables can be plain tables or foreign tables. See the similar form of @@ -166,7 +166,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <para> An optional name for a column or table constraint. If the constraint is violated, the constraint name is present in error messages, - so constraint names like <literal>col must be positive</> can be used + so constraint names like <literal>col must be positive</literal> can be used to communicate helpful constraint information to client applications. (Double-quotes are needed to specify constraint names that contain spaces.) If a constraint name is not specified, the system generates a name. @@ -175,7 +175,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> The column is not allowed to contain null values. @@ -184,7 +184,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> The column is allowed to contain null values. This is the default. @@ -202,7 +202,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </literal></term> <listitem> <para> - The <literal>CHECK</> clause specifies an expression producing a + The <literal>CHECK</literal> clause specifies an expression producing a Boolean result which each row in the foreign table is expected to satisfy; that is, the expression should produce TRUE or UNKNOWN, never FALSE, for all rows in the foreign table. @@ -219,7 +219,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </para> <para> - A constraint marked with <literal>NO INHERIT</> will not propagate to + A constraint marked with <literal>NO INHERIT</literal> will not propagate to child tables. </para> </listitem> @@ -230,7 +230,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <replaceable>default_expr</replaceable></literal></term> <listitem> <para> - The <literal>DEFAULT</> clause assigns a default data value for + The <literal>DEFAULT</literal> clause assigns a default data value for the column whose column definition it appears within. The value is any variable-free expression (subqueries and cross-references to other columns in the current table are not allowed). The @@ -279,9 +279,9 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <title>Notes</title> <para> - Constraints on foreign tables (such as <literal>CHECK</> - or <literal>NOT NULL</> clauses) are not enforced by the - core <productname>PostgreSQL</> system, and most foreign data wrappers + Constraints on foreign tables (such as <literal>CHECK</literal> + or <literal>NOT NULL</literal> clauses) are not enforced by the + core <productname>PostgreSQL</productname> system, and most foreign data wrappers do not attempt to enforce them either; that is, the constraint is simply assumed to hold true. There would be little point in such enforcement since it would only apply to rows inserted or updated via @@ -300,7 +300,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </para> <para> - Although <productname>PostgreSQL</> does not attempt to enforce + Although <productname>PostgreSQL</productname> does not attempt to enforce constraints on foreign tables, it does assume that they are correct for purposes of query optimization. If there are rows visible in the foreign table that do not satisfy a declared constraint, queries on @@ -314,8 +314,8 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <title>Examples</title> <para> - Create foreign table <structname>films</>, which will be accessed through - the server <structname>film_server</>: + Create foreign table <structname>films</structname>, which will be accessed through + the server <structname>film_server</structname>: <programlisting> CREATE FOREIGN TABLE films ( @@ -330,9 +330,9 @@ SERVER film_server; </programlisting></para> <para> - Create foreign table <structname>measurement_y2016m07</>, which will be - accessed through the server <structname>server_07</>, as a partition - of the range partitioned table <structname>measurement</>: + Create foreign table <structname>measurement_y2016m07</structname>, which will be + accessed through the server <structname>server_07</structname>, as a partition + of the range partitioned table <structname>measurement</structname>: <programlisting> CREATE FOREIGN TABLE measurement_y2016m07 @@ -348,10 +348,10 @@ CREATE FOREIGN TABLE measurement_y2016m07 <para> The <command>CREATE FOREIGN TABLE</command> command largely conforms to the <acronym>SQL</acronym> standard; however, much as with - <link linkend="sql-createtable"><command>CREATE TABLE</></link>, - <literal>NULL</> constraints and zero-column foreign tables are permitted. + <link linkend="sql-createtable"><command>CREATE TABLE</command></link>, + <literal>NULL</literal> constraints and zero-column foreign tables are permitted. The ability to specify column default values is also - a <productname>PostgreSQL</> extension. Table inheritance, in the form + a <productname>PostgreSQL</productname> extension. Table inheritance, in the form defined by <productname>PostgreSQL</productname>, is nonstandard. </para> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 072e033687b..97cb9b7fc8a 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -58,7 +58,7 @@ CREATE [ OR REPLACE ] FUNCTION The name of the new function must not match any existing function with the same input argument types in the same schema. However, functions of different argument types can share a name (this is - called <firstterm>overloading</>). + called <firstterm>overloading</firstterm>). </para> <para> @@ -68,13 +68,13 @@ CREATE [ OR REPLACE ] FUNCTION tried, you would actually be creating a new, distinct function). Also, <command>CREATE OR REPLACE FUNCTION</command> will not let you change the return type of an existing function. To do that, - you must drop and recreate the function. (When using <literal>OUT</> + you must drop and recreate the function. (When using <literal>OUT</literal> parameters, that means you cannot change the types of any - <literal>OUT</> parameters except by dropping the function.) + <literal>OUT</literal> parameters except by dropping the function.) </para> <para> - When <command>CREATE OR REPLACE FUNCTION</> is used to replace an + When <command>CREATE OR REPLACE FUNCTION</command> is used to replace an existing function, the ownership and permissions of the function do not change. All other function properties are assigned the values specified or implied in the command. You must own the function @@ -87,7 +87,7 @@ CREATE [ OR REPLACE ] FUNCTION triggers, etc. that refer to the old function. Use <command>CREATE OR REPLACE FUNCTION</command> to change a function definition without breaking objects that refer to the function. - Also, <command>ALTER FUNCTION</> can be used to change most of the + Also, <command>ALTER FUNCTION</command> can be used to change most of the auxiliary properties of an existing function. </para> @@ -121,12 +121,12 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. - Only <literal>OUT</> arguments can follow a <literal>VARIADIC</> one. - Also, <literal>OUT</> and <literal>INOUT</> arguments cannot be used - together with the <literal>RETURNS TABLE</> notation. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. + Only <literal>OUT</literal> arguments can follow a <literal>VARIADIC</literal> one. + Also, <literal>OUT</literal> and <literal>INOUT</literal> arguments cannot be used + together with the <literal>RETURNS TABLE</literal> notation. </para> </listitem> </varlistentry> @@ -160,7 +160,7 @@ CREATE [ OR REPLACE ] FUNCTION </para> <para> Depending on the implementation language it might also be allowed - to specify <quote>pseudo-types</> such as <type>cstring</>. + to specify <quote>pseudo-types</quote> such as <type>cstring</type>. Pseudo-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types. </para> @@ -183,7 +183,7 @@ CREATE [ OR REPLACE ] FUNCTION An expression to be used as default value if the parameter is not specified. The expression has to be coercible to the argument type of the parameter. - Only input (including <literal>INOUT</>) parameters can have a default + Only input (including <literal>INOUT</literal>) parameters can have a default value. All input parameters following a parameter with a default value must have default values as well. </para> @@ -199,15 +199,15 @@ CREATE [ OR REPLACE ] FUNCTION can be a base, composite, or domain type, or can reference the type of a table column. Depending on the implementation language it might also be allowed - to specify <quote>pseudo-types</> such as <type>cstring</>. + to specify <quote>pseudo-types</quote> such as <type>cstring</type>. If the function is not supposed to return a value, specify - <type>void</> as the return type. + <type>void</type> as the return type. </para> <para> - When there are <literal>OUT</> or <literal>INOUT</> parameters, - the <literal>RETURNS</> clause can be omitted. If present, it + When there are <literal>OUT</literal> or <literal>INOUT</literal> parameters, + the <literal>RETURNS</literal> clause can be omitted. If present, it must agree with the result type implied by the output parameters: - <literal>RECORD</> if there are multiple output parameters, or + <literal>RECORD</literal> if there are multiple output parameters, or the same type as the single output parameter. </para> <para> @@ -229,10 +229,10 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The name of an output column in the <literal>RETURNS TABLE</> + The name of an output column in the <literal>RETURNS TABLE</literal> syntax. This is effectively another way of declaring a named - <literal>OUT</> parameter, except that <literal>RETURNS TABLE</> - also implies <literal>RETURNS SETOF</>. + <literal>OUT</literal> parameter, except that <literal>RETURNS TABLE</literal> + also implies <literal>RETURNS SETOF</literal>. </para> </listitem> </varlistentry> @@ -242,7 +242,7 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The data type of an output column in the <literal>RETURNS TABLE</> + The data type of an output column in the <literal>RETURNS TABLE</literal> syntax. </para> </listitem> @@ -284,9 +284,9 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para><literal>WINDOW</literal> indicates that the function is a - <firstterm>window function</> rather than a plain function. + <firstterm>window function</firstterm> rather than a plain function. This is currently only useful for functions written in C. - The <literal>WINDOW</> attribute cannot be changed when + The <literal>WINDOW</literal> attribute cannot be changed when replacing an existing function definition. </para> </listitem> @@ -321,20 +321,20 @@ CREATE [ OR REPLACE ] FUNCTION result could change across SQL statements. This is the appropriate selection for functions whose results depend on database lookups, parameter variables (such as the current time zone), etc. (It is - inappropriate for <literal>AFTER</> triggers that wish to + inappropriate for <literal>AFTER</literal> triggers that wish to query rows modified by the current command.) Also note - that the <function>current_timestamp</> family of functions qualify + that the <function>current_timestamp</function> family of functions qualify as stable, since their values do not change within a transaction. </para> <para><literal>VOLATILE</literal> indicates that the function value can change even within a single table scan, so no optimizations can be made. Relatively few database functions are volatile in this sense; - some examples are <literal>random()</>, <literal>currval()</>, - <literal>timeofday()</>. But note that any function that has + some examples are <literal>random()</literal>, <literal>currval()</literal>, + <literal>timeofday()</literal>. But note that any function that has side-effects must be classified volatile, even if its result is quite predictable, to prevent calls from being optimized away; an example is - <literal>setval()</>. + <literal>setval()</literal>. </para> <para> @@ -430,11 +430,11 @@ CREATE [ OR REPLACE ] FUNCTION Functions should be labeled parallel unsafe if they modify any database state, or if they make changes to the transaction such as using sub-transactions, or if they access sequences or attempt to make - persistent changes to settings (e.g. <literal>setval</>). They should + persistent changes to settings (e.g. <literal>setval</literal>). They should be labeled as parallel restricted if they access temporary tables, client connection state, cursors, prepared statements, or miscellaneous backend-local state which the system cannot synchronize in parallel mode - (e.g. <literal>setseed</> cannot be executed other than by the group + (e.g. <literal>setseed</literal> cannot be executed other than by the group leader because a change made by another process would not be reflected in the leader). In general, if a function is labeled as being safe when it is restricted or unsafe, or if it is labeled as being restricted when @@ -443,7 +443,7 @@ CREATE [ OR REPLACE ] FUNCTION exhibit totally undefined behavior if mislabeled, since there is no way for the system to protect itself against arbitrary C code, but in most likely cases the result will be no worse than for any other function. - If in doubt, functions should be labeled as <literal>UNSAFE</>, which is + If in doubt, functions should be labeled as <literal>UNSAFE</literal>, which is the default. </para> </listitem> @@ -483,23 +483,23 @@ CREATE [ OR REPLACE ] FUNCTION <term><replaceable>value</replaceable></term> <listitem> <para> - The <literal>SET</> clause causes the specified configuration + The <literal>SET</literal> clause causes the specified configuration parameter to be set to the specified value when the function is entered, and then restored to its prior value when the function exits. - <literal>SET FROM CURRENT</> saves the value of the parameter that - is current when <command>CREATE FUNCTION</> is executed as the value + <literal>SET FROM CURRENT</literal> saves the value of the parameter that + is current when <command>CREATE FUNCTION</command> is executed as the value to be applied when the function is entered. </para> <para> - If a <literal>SET</> clause is attached to a function, then - the effects of a <command>SET LOCAL</> command executed inside the + If a <literal>SET</literal> clause is attached to a function, then + the effects of a <command>SET LOCAL</command> command executed inside the function for the same variable are restricted to the function: the configuration parameter's prior value is still restored at function exit. However, an ordinary - <command>SET</> command (without <literal>LOCAL</>) overrides the - <literal>SET</> clause, much as it would do for a previous <command>SET - LOCAL</> command: the effects of such a command will persist after + <command>SET</command> command (without <literal>LOCAL</literal>) overrides the + <literal>SET</literal> clause, much as it would do for a previous <command>SET + LOCAL</command> command: the effects of such a command will persist after function exit, unless the current transaction is rolled back. </para> @@ -570,7 +570,7 @@ CREATE [ OR REPLACE ] FUNCTION <variablelist> <varlistentry> - <term><literal>isStrict</></term> + <term><literal>isStrict</literal></term> <listitem> <para> Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>. @@ -579,7 +579,7 @@ CREATE [ OR REPLACE ] FUNCTION </varlistentry> <varlistentry> - <term><literal>isCachable</></term> + <term><literal>isCachable</literal></term> <listitem> <para><literal>isCachable</literal> is an obsolete equivalent of <literal>IMMUTABLE</literal>; it's still accepted for @@ -619,7 +619,7 @@ CREATE [ OR REPLACE ] FUNCTION <para> Two functions are considered the same if they have the same names and - <emphasis>input</> argument types, ignoring any <literal>OUT</> + <emphasis>input</emphasis> argument types, ignoring any <literal>OUT</literal> parameters. Thus for example these declarations conflict: <programlisting> CREATE FUNCTION foo(int) ... @@ -635,7 +635,7 @@ CREATE FUNCTION foo(int, out text) ... CREATE FUNCTION foo(int) ... CREATE FUNCTION foo(int, int default 42) ... </programlisting> - A call <literal>foo(10)</> will fail due to the ambiguity about which + A call <literal>foo(10)</literal> will fail due to the ambiguity about which function should be called. </para> @@ -648,16 +648,16 @@ CREATE FUNCTION foo(int, int default 42) ... The full <acronym>SQL</acronym> type syntax is allowed for declaring a function's arguments and return value. However, parenthesized type modifiers (e.g., the precision field for - type <type>numeric</type>) are discarded by <command>CREATE FUNCTION</>. + type <type>numeric</type>) are discarded by <command>CREATE FUNCTION</command>. Thus for example - <literal>CREATE FUNCTION foo (varchar(10)) ...</> + <literal>CREATE FUNCTION foo (varchar(10)) ...</literal> is exactly the same as - <literal>CREATE FUNCTION foo (varchar) ...</>. + <literal>CREATE FUNCTION foo (varchar) ...</literal>. </para> <para> When replacing an existing function with <command>CREATE OR REPLACE - FUNCTION</>, there are restrictions on changing parameter names. + FUNCTION</command>, there are restrictions on changing parameter names. You cannot change the name already assigned to any input parameter (although you can add names to parameters that had none before). If there is more than one output parameter, you cannot change the @@ -668,9 +668,9 @@ CREATE FUNCTION foo(int, int default 42) ... </para> <para> - If a function is declared <literal>STRICT</> with a <literal>VARIADIC</> + If a function is declared <literal>STRICT</literal> with a <literal>VARIADIC</literal> argument, the strictness check tests that the variadic array <emphasis>as - a whole</> is non-null. The function will still be called if the + a whole</emphasis> is non-null. The function will still be called if the array has null elements. </para> @@ -723,7 +723,7 @@ CREATE FUNCTION dup(int) RETURNS dup_result SELECT * FROM dup(42); </programlisting> - Another way to return multiple columns is to use a <literal>TABLE</> + Another way to return multiple columns is to use a <literal>TABLE</literal> function: <programlisting> CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) @@ -732,8 +732,8 @@ CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) SELECT * FROM dup(42); </programlisting> - However, a <literal>TABLE</> function is different from the - preceding examples, because it actually returns a <emphasis>set</> + However, a <literal>TABLE</literal> function is different from the + preceding examples, because it actually returns a <emphasis>set</emphasis> of records, not just one record. </para> </refsect1> @@ -742,8 +742,8 @@ SELECT * FROM dup(42); <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title> <indexterm> - <primary><varname>search_path</varname> configuration parameter</> - <secondary>use in securing functions</> + <primary><varname>search_path</varname> configuration parameter</primary> + <secondary>use in securing functions</secondary> </indexterm> <para> @@ -758,7 +758,7 @@ SELECT * FROM dup(42); temporary-table schema, which is searched first by default, and is normally writable by anyone. A secure arrangement can be obtained by forcing the temporary schema to be searched last. To do this, - write <literal>pg_temp</><indexterm><primary>pg_temp</><secondary>securing functions</></> as the last entry in <varname>search_path</>. + write <literal>pg_temp</literal><indexterm><primary>pg_temp</primary><secondary>securing functions</secondary></indexterm> as the last entry in <varname>search_path</varname>. This function illustrates safe usage: <programlisting> @@ -778,27 +778,27 @@ $$ LANGUAGE plpgsql SET search_path = admin, pg_temp; </programlisting> - This function's intention is to access a table <literal>admin.pwds</>. - But without the <literal>SET</> clause, or with a <literal>SET</> clause - mentioning only <literal>admin</>, the function could be subverted by - creating a temporary table named <literal>pwds</>. + This function's intention is to access a table <literal>admin.pwds</literal>. + But without the <literal>SET</literal> clause, or with a <literal>SET</literal> clause + mentioning only <literal>admin</literal>, the function could be subverted by + creating a temporary table named <literal>pwds</literal>. </para> <para> Before <productname>PostgreSQL</productname> version 8.3, the - <literal>SET</> clause was not available, and so older functions may + <literal>SET</literal> clause was not available, and so older functions may contain rather complicated logic to save, set, and restore - <varname>search_path</>. The <literal>SET</> clause is far easier + <varname>search_path</varname>. The <literal>SET</literal> clause is far easier to use for this purpose. </para> <para> Another point to keep in mind is that by default, execute privilege - is granted to <literal>PUBLIC</> for newly created functions + is granted to <literal>PUBLIC</literal> for newly created functions (see <xref linkend="sql-grant"> for more information). Frequently you will wish to restrict use of a security definer function to only some users. To do that, you must revoke - the default <literal>PUBLIC</> privileges and then grant execute + the default <literal>PUBLIC</literal> privileges and then grant execute privilege selectively. To avoid having a window where the new function is accessible to all, create it and set the privileges within a single transaction. For example: diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index a462be790f6..bb2601dc8c8 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -51,8 +51,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= one or more columns of the table row. This feature can be used to obtain fast access to data based on some transformation of the basic data. For example, an index computed on - <literal>upper(col)</> would allow the clause - <literal>WHERE upper(col) = 'JIM'</> to use an index. + <literal>upper(col)</literal> would allow the clause + <literal>WHERE upper(col) = 'JIM'</literal> to use an index. </para> <para> @@ -85,7 +85,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> All functions and operators used in an index definition must be - <quote>immutable</>, that is, their results must depend only on + <quote>immutable</quote>, that is, their results must depend only on their arguments and never on any outside influence (such as the contents of another table or the current time). This restriction ensures that the behavior of the index is well-defined. To use a @@ -115,7 +115,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <term><literal>CONCURRENTLY</literal></term> <listitem> <para> - When this option is used, <productname>PostgreSQL</> will build the + When this option is used, <productname>PostgreSQL</productname> will build the index without taking any locks that prevent concurrent inserts, updates, or deletes on the table; whereas a standard index build locks out writes (but not reads) on the table until it's done. @@ -144,7 +144,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> The name of the index to be created. No schema name can be included here; the index is always created in the same schema as its parent - table. If the name is omitted, <productname>PostgreSQL</> chooses a + table. If the name is omitted, <productname>PostgreSQL</productname> chooses a suitable name based on the parent table's name and the indexed column name(s). </para> @@ -166,8 +166,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> The name of the index method to be used. Choices are <literal>btree</literal>, <literal>hash</literal>, - <literal>gist</literal>, <literal>spgist</>, <literal>gin</>, and - <literal>brin</>. + <literal>gist</literal>, <literal>spgist</literal>, <literal>gin</literal>, and + <literal>brin</literal>. The default method is <literal>btree</literal>. </para> </listitem> @@ -217,7 +217,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>ASC</></term> + <term><literal>ASC</literal></term> <listitem> <para> Specifies ascending sort order (which is the default). @@ -226,7 +226,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>DESC</></term> + <term><literal>DESC</literal></term> <listitem> <para> Specifies descending sort order. @@ -235,21 +235,21 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>NULLS FIRST</></term> + <term><literal>NULLS FIRST</literal></term> <listitem> <para> Specifies that nulls sort before non-nulls. This is the default - when <literal>DESC</> is specified. + when <literal>DESC</literal> is specified. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>NULLS LAST</></term> + <term><literal>NULLS LAST</literal></term> <listitem> <para> Specifies that nulls sort after non-nulls. This is the default - when <literal>DESC</> is not specified. + when <literal>DESC</literal> is not specified. </para> </listitem> </varlistentry> @@ -292,15 +292,15 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <title id="SQL-CREATEINDEX-storage-parameters-title">Index Storage Parameters</title> <para> - The optional <literal>WITH</> clause specifies <firstterm>storage - parameters</> for the index. Each index method has its own set of allowed + The optional <literal>WITH</literal> clause specifies <firstterm>storage + parameters</firstterm> for the index. Each index method has its own set of allowed storage parameters. The B-tree, hash, GiST and SP-GiST index methods all accept this parameter: </para> <variablelist> <varlistentry> - <term><literal>fillfactor</></term> + <term><literal>fillfactor</literal></term> <listitem> <para> The fillfactor for an index is a percentage that determines how full @@ -327,14 +327,14 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <variablelist> <varlistentry> - <term><literal>buffering</></term> + <term><literal>buffering</literal></term> <listitem> <para> Determines whether the buffering build technique described in <xref linkend="gist-buffering-build"> is used to build the index. With - <literal>OFF</> it is disabled, with <literal>ON</> it is enabled, and - with <literal>AUTO</> it is initially disabled, but turned on - on-the-fly once the index size reaches <xref linkend="guc-effective-cache-size">. The default is <literal>AUTO</>. + <literal>OFF</literal> it is disabled, with <literal>ON</literal> it is enabled, and + with <literal>AUTO</literal> it is initially disabled, but turned on + on-the-fly once the index size reaches <xref linkend="guc-effective-cache-size">. The default is <literal>AUTO</literal>. </para> </listitem> </varlistentry> @@ -346,23 +346,23 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <variablelist> <varlistentry> - <term><literal>fastupdate</></term> + <term><literal>fastupdate</literal></term> <listitem> <para> This setting controls usage of the fast update technique described in <xref linkend="gin-fast-update">. It is a Boolean parameter: - <literal>ON</> enables fast update, <literal>OFF</> disables it. - (Alternative spellings of <literal>ON</> and <literal>OFF</> are + <literal>ON</literal> enables fast update, <literal>OFF</literal> disables it. + (Alternative spellings of <literal>ON</literal> and <literal>OFF</literal> are allowed as described in <xref linkend="config-setting">.) The - default is <literal>ON</>. + default is <literal>ON</literal>. </para> <note> <para> - Turning <literal>fastupdate</> off via <command>ALTER INDEX</> prevents + Turning <literal>fastupdate</literal> off via <command>ALTER INDEX</command> prevents future insertions from going into the list of pending index entries, but does not in itself flush previous entries. You might want to - <command>VACUUM</> the table or call <function>gin_clean_pending_list</> + <command>VACUUM</command> the table or call <function>gin_clean_pending_list</function> function afterward to ensure the pending list is emptied. </para> </note> @@ -371,7 +371,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </variablelist> <variablelist> <varlistentry> - <term><literal>gin_pending_list_limit</></term> + <term><literal>gin_pending_list_limit</literal></term> <listitem> <para> Custom <xref linkend="guc-gin-pending-list-limit"> parameter. @@ -382,23 +382,23 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </variablelist> <para> - <acronym>BRIN</> indexes accept different parameters: + <acronym>BRIN</acronym> indexes accept different parameters: </para> <variablelist> <varlistentry> - <term><literal>pages_per_range</></term> + <term><literal>pages_per_range</literal></term> <listitem> <para> Defines the number of table blocks that make up one block range for - each entry of a <acronym>BRIN</> index (see <xref linkend="brin-intro"> - for more details). The default is <literal>128</>. + each entry of a <acronym>BRIN</acronym> index (see <xref linkend="brin-intro"> + for more details). The default is <literal>128</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>autosummarize</></term> + <term><literal>autosummarize</literal></term> <listitem> <para> Defines whether a summarization run is invoked for the previous page @@ -419,7 +419,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> Creating an index can interfere with regular operation of a database. - Normally <productname>PostgreSQL</> locks the table to be indexed against + Normally <productname>PostgreSQL</productname> locks the table to be indexed against writes and performs the entire index build with a single scan of the table. Other transactions can still read the table, but if they try to insert, update, or delete rows in the table they will block until the @@ -430,11 +430,11 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </para> <para> - <productname>PostgreSQL</> supports building indexes without locking + <productname>PostgreSQL</productname> supports building indexes without locking out writes. This method is invoked by specifying the - <literal>CONCURRENTLY</> option of <command>CREATE INDEX</>. + <literal>CONCURRENTLY</literal> option of <command>CREATE INDEX</command>. When this option is used, - <productname>PostgreSQL</> must perform two scans of the table, and in + <productname>PostgreSQL</productname> must perform two scans of the table, and in addition it must wait for all existing transactions that could potentially modify or use the index to terminate. Thus this method requires more total work than a standard index build and takes @@ -452,7 +452,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= After the second scan, the index build must wait for any transactions that have a snapshot (see <xref linkend="mvcc">) predating the second scan to terminate. Then finally the index can be marked ready for use, - and the <command>CREATE INDEX</> command terminates. + and the <command>CREATE INDEX</command> command terminates. Even then, however, the index may not be immediately usable for queries: in the worst case, it cannot be used as long as transactions exist that predate the start of the index build. @@ -460,11 +460,11 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> If a problem arises while scanning the table, such as a deadlock or a - uniqueness violation in a unique index, the <command>CREATE INDEX</> - command will fail but leave behind an <quote>invalid</> index. This index + uniqueness violation in a unique index, the <command>CREATE INDEX</command> + command will fail but leave behind an <quote>invalid</quote> index. This index will be ignored for querying purposes because it might be incomplete; - however it will still consume update overhead. The <application>psql</> - <command>\d</> command will report such an index as <literal>INVALID</>: + however it will still consume update overhead. The <application>psql</application> + <command>\d</command> command will report such an index as <literal>INVALID</literal>: <programlisting> postgres=# \d tab @@ -478,8 +478,8 @@ Indexes: The recommended recovery method in such cases is to drop the index and try again to perform - <command>CREATE INDEX CONCURRENTLY</>. (Another possibility is to rebuild - the index with <command>REINDEX</>. However, since <command>REINDEX</> + <command>CREATE INDEX CONCURRENTLY</command>. (Another possibility is to rebuild + the index with <command>REINDEX</command>. However, since <command>REINDEX</command> does not support concurrent builds, this option is unlikely to seem attractive.) </para> @@ -490,7 +490,7 @@ Indexes: when the second table scan begins. This means that constraint violations could be reported in other queries prior to the index becoming available for use, or even in cases where the index build eventually fails. Also, - if a failure does occur in the second scan, the <quote>invalid</> index + if a failure does occur in the second scan, the <quote>invalid</quote> index continues to enforce its uniqueness constraint afterwards. </para> @@ -505,8 +505,8 @@ Indexes: same table to occur in parallel, but only one concurrent index build can occur on a table at a time. In both cases, no other types of schema modification on the table are allowed meanwhile. Another difference - is that a regular <command>CREATE INDEX</> command can be performed within - a transaction block, but <command>CREATE INDEX CONCURRENTLY</> cannot. + is that a regular <command>CREATE INDEX</command> command can be performed within + a transaction block, but <command>CREATE INDEX CONCURRENTLY</command> cannot. </para> </refsect2> </refsect1> @@ -547,17 +547,17 @@ Indexes: <para> For index methods that support ordered scans (currently, only B-tree), - the optional clauses <literal>ASC</>, <literal>DESC</>, <literal>NULLS - FIRST</>, and/or <literal>NULLS LAST</> can be specified to modify + the optional clauses <literal>ASC</literal>, <literal>DESC</literal>, <literal>NULLS + FIRST</literal>, and/or <literal>NULLS LAST</literal> can be specified to modify the sort ordering of the index. Since an ordered index can be scanned either forward or backward, it is not normally useful to create a - single-column <literal>DESC</> index — that sort ordering is already + single-column <literal>DESC</literal> index — that sort ordering is already available with a regular index. The value of these options is that multicolumn indexes can be created that match the sort ordering requested by a mixed-ordering query, such as <literal>SELECT ... ORDER BY x ASC, y - DESC</>. The <literal>NULLS</> options are useful if you need to support - <quote>nulls sort low</> behavior, rather than the default <quote>nulls - sort high</>, in queries that depend on indexes to avoid sorting steps. + DESC</literal>. The <literal>NULLS</literal> options are useful if you need to support + <quote>nulls sort low</quote> behavior, rather than the default <quote>nulls + sort high</quote>, in queries that depend on indexes to avoid sorting steps. </para> <para> @@ -577,8 +577,8 @@ Indexes: Prior releases of <productname>PostgreSQL</productname> also had an R-tree index method. This method has been removed because it had no significant advantages over the GiST method. - If <literal>USING rtree</> is specified, <command>CREATE INDEX</> - will interpret it as <literal>USING gist</>, to simplify conversion + If <literal>USING rtree</literal> is specified, <command>CREATE INDEX</command> + will interpret it as <literal>USING gist</literal>, to simplify conversion of old databases to GiST. </para> </refsect1> @@ -595,13 +595,13 @@ CREATE UNIQUE INDEX title_idx ON films (title); </para> <para> - To create an index on the expression <literal>lower(title)</>, + To create an index on the expression <literal>lower(title)</literal>, allowing efficient case-insensitive searches: <programlisting> CREATE INDEX ON films ((lower(title))); </programlisting> (In this example we have chosen to omit the index name, so the system - will choose a name, typically <literal>films_lower_idx</>.) + will choose a name, typically <literal>films_lower_idx</literal>.) </para> <para> @@ -626,16 +626,16 @@ CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70); </para> <para> - To create a <acronym>GIN</> index with fast updates disabled: + To create a <acronym>GIN</acronym> index with fast updates disabled: <programlisting> CREATE INDEX gin_idx ON documents_table USING GIN (locations) WITH (fastupdate = off); </programlisting> </para> <para> - To create an index on the column <literal>code</> in the table - <literal>films</> and have the index reside in the tablespace - <literal>indexspace</>: + To create an index on the column <literal>code</literal> in the table + <literal>films</literal> and have the index reside in the tablespace + <literal>indexspace</literal>: <programlisting> CREATE INDEX code_idx ON films (code) TABLESPACE indexspace; </programlisting> diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 75165b677f1..20d56a766f3 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -40,14 +40,14 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <note> <para> As of <productname>PostgreSQL</productname> 9.1, most procedural - languages have been made into <quote>extensions</>, and should + languages have been made into <quote>extensions</quote>, and should therefore be installed with <xref linkend="sql-createextension"> not <command>CREATE LANGUAGE</command>. Direct use of <command>CREATE LANGUAGE</command> should now be confined to - extension installation scripts. If you have a <quote>bare</> + extension installation scripts. If you have a <quote>bare</quote> language in your database, perhaps as a result of an upgrade, you can convert it to an extension using - <literal>CREATE EXTENSION <replaceable>langname</> FROM + <literal>CREATE EXTENSION <replaceable>langname</replaceable> FROM unpackaged</literal>. </para> </note> @@ -67,11 +67,11 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa system catalog to determine the correct parameters. In the second form, the user supplies the language parameters along with the language name. The second form can be used to create a language that is not defined in - <structname>pg_pltemplate</>, but this approach is considered obsolescent. + <structname>pg_pltemplate</structname>, but this approach is considered obsolescent. </para> <para> - When the server finds an entry in the <structname>pg_pltemplate</> catalog + When the server finds an entry in the <structname>pg_pltemplate</structname> catalog for the given language name, it will use the catalog data even if the command includes language parameters. This behavior simplifies loading of old dump files, which are likely to contain out-of-date information @@ -84,7 +84,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa register a new language. However, the owner of a database can register a new language within that database if the language is listed in the <structname>pg_pltemplate</structname> catalog and is marked - as allowed to be created by database owners (<structfield>tmpldbacreate</> + as allowed to be created by database owners (<structfield>tmpldbacreate</structfield> is true). The default is that trusted languages can be created by database owners, but this can be adjusted by superusers by modifying the contents of <structname>pg_pltemplate</structname>. @@ -101,9 +101,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa and any existing functions written in the language are assumed to still be valid. In addition to the normal privilege requirements for creating a language, the user must be superuser or owner of the existing language. - The <literal>REPLACE</> case is mainly meant to be used to + The <literal>REPLACE</literal> case is mainly meant to be used to ensure that the language exists. If the language has a - <structname>pg_pltemplate</structname> entry then <literal>REPLACE</> + <structname>pg_pltemplate</structname> entry then <literal>REPLACE</literal> will not actually change anything about an existing definition, except in the unusual case where the <structname>pg_pltemplate</structname> entry has been modified since the language was created. @@ -184,9 +184,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa function is specified, the language does not support anonymous code blocks. The handler function must take one argument of - type <type>internal</type>, which will be the <command>DO</> command's + type <type>internal</type>, which will be the <command>DO</command> command's internal representation, and it will typically return - <type>void</>. The return value of the handler is ignored. + <type>void</type>. The return value of the handler is ignored. </para> </listitem> </varlistentry> @@ -204,7 +204,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa be checked when it is created. The validator function must take one argument of type <type>oid</type>, which will be the OID of the - to-be-created function, and will typically return <type>void</>. + to-be-created function, and will typically return <type>void</type>. </para> <para> @@ -220,9 +220,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa </variablelist> <para> - The <literal>TRUSTED</> option and the support function name(s) are + The <literal>TRUSTED</literal> option and the support function name(s) are ignored if the server has an entry for the specified language - name in <structname>pg_pltemplate</>. + name in <structname>pg_pltemplate</structname>. </para> </refsect1> @@ -243,7 +243,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <para> To create functions in a procedural language, a user must have the <literal>USAGE</literal> privilege for the language. By default, - <literal>USAGE</> is granted to <literal>PUBLIC</> (i.e., everyone) + <literal>USAGE</literal> is granted to <literal>PUBLIC</literal> (i.e., everyone) for trusted languages. This can be revoked if desired. </para> @@ -258,10 +258,10 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa The call handler function, the inline handler function (if any), and the validator function (if any) must already exist if the server does not have an entry for the language - in <structname>pg_pltemplate</>. But when there is an entry, + in <structname>pg_pltemplate</structname>. But when there is an entry, the functions need not already exist; they will be automatically defined if not present in the database. - (This might result in <command>CREATE LANGUAGE</> failing, if the + (This might result in <command>CREATE LANGUAGE</command> failing, if the shared library that implements the language is not available in the installation.) </para> @@ -269,11 +269,11 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <para> In <productname>PostgreSQL</productname> versions before 7.3, it was necessary to declare handler functions as returning the placeholder - type <type>opaque</>, rather than <type>language_handler</>. + type <type>opaque</type>, rather than <type>language_handler</type>. To support loading - of old dump files, <command>CREATE LANGUAGE</> will accept a function - declared as returning <type>opaque</>, but it will issue a notice and - change the function's declared return type to <type>language_handler</>. + of old dump files, <command>CREATE LANGUAGE</command> will accept a function + declared as returning <type>opaque</type>, but it will issue a notice and + change the function's declared return type to <type>language_handler</type>. </para> </refsect1> @@ -289,7 +289,7 @@ CREATE LANGUAGE plperl; </para> <para> - For a language not known in the <structname>pg_pltemplate</> catalog, a + For a language not known in the <structname>pg_pltemplate</structname> catalog, a sequence such as this is needed: <programlisting> CREATE FUNCTION plsample_call_handler() RETURNS language_handler diff --git a/doc/src/sgml/ref/create_materialized_view.sgml b/doc/src/sgml/ref/create_materialized_view.sgml index 577893fe929..126aa5666f8 100644 --- a/doc/src/sgml/ref/create_materialized_view.sgml +++ b/doc/src/sgml/ref/create_materialized_view.sgml @@ -36,13 +36,13 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> <para> <command>CREATE MATERIALIZED VIEW</command> defines a materialized view of a query. The query is executed and used to populate the view at the time - the command is issued (unless <command>WITH NO DATA</> is used) and may be + the command is issued (unless <command>WITH NO DATA</command> is used) and may be refreshed later using <command>REFRESH MATERIALIZED VIEW</command>. </para> <para> <command>CREATE MATERIALIZED VIEW</command> is similar to - <command>CREATE TABLE AS</>, except that it also remembers the query used + <command>CREATE TABLE AS</command>, except that it also remembers the query used to initialize the view, so that it can be refreshed later upon demand. A materialized view has many of the same properties as a table, but there is no support for temporary materialized views or automatic generation of @@ -55,7 +55,7 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a materialized view with the same name already @@ -125,13 +125,13 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> </varlistentry> <varlistentry> - <term><literal>WITH [ NO ] DATA</></term> + <term><literal>WITH [ NO ] DATA</literal></term> <listitem> <para> This clause specifies whether or not the materialized view should be populated at creation time. If not, the materialized view will be flagged as unscannable and cannot be queried until <command>REFRESH - MATERIALIZED VIEW</> is used. + MATERIALIZED VIEW</command> is used. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml index 829d8f2fffb..08eb7f2a083 100644 --- a/doc/src/sgml/ref/create_opclass.sgml +++ b/doc/src/sgml/ref/create_opclass.sgml @@ -37,7 +37,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <command>CREATE OPERATOR CLASS</command> creates a new operator class. An operator class defines how a particular data type can be used with an index. The operator class specifies that certain operators will fill - particular roles or <quote>strategies</> for this data type and this + particular roles or <quote>strategies</quote> for this data type and this index method. The operator class also specifies the support procedures to be used by the index method when the operator class is selected for an @@ -69,8 +69,8 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <para> Related operator classes can be grouped into <firstterm>operator - families</>. To add a new operator class to an existing family, - specify the <literal>FAMILY</> option in <command>CREATE OPERATOR + families</firstterm>. To add a new operator class to an existing family, + specify the <literal>FAMILY</literal> option in <command>CREATE OPERATOR CLASS</command>. Without this option, the new class is placed into a family named the same as the new class (creating that family if it doesn't already exist). @@ -96,7 +96,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </varlistentry> <varlistentry> - <term><literal>DEFAULT</></term> + <term><literal>DEFAULT</literal></term> <listitem> <para> If present, the operator class will become the default @@ -159,15 +159,15 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <term><replaceable class="parameter">op_type</replaceable></term> <listitem> <para> - In an <literal>OPERATOR</> clause, - the operand data type(s) of the operator, or <literal>NONE</> to + In an <literal>OPERATOR</literal> clause, + the operand data type(s) of the operator, or <literal>NONE</literal> to signify a left-unary or right-unary operator. The operand data types can be omitted in the normal case where they are the same as the operator class's data type. </para> <para> - In a <literal>FUNCTION</> clause, the operand data type(s) the + In a <literal>FUNCTION</literal> clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function (for B-tree comparison functions and hash functions) @@ -175,7 +175,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL functions in GiST, SP-GiST, GIN and BRIN operator classes). These defaults are correct, and so <replaceable class="parameter">op_type</replaceable> need not be specified in - <literal>FUNCTION</> clauses, except for the case of a B-tree sort + <literal>FUNCTION</literal> clauses, except for the case of a B-tree sort support function that is meant to support cross-data-type comparisons. </para> </listitem> @@ -191,8 +191,8 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </para> <para> - If neither <literal>FOR SEARCH</> nor <literal>FOR ORDER BY</> is - specified, <literal>FOR SEARCH</> is the default. + If neither <literal>FOR SEARCH</literal> nor <literal>FOR ORDER BY</literal> is + specified, <literal>FOR SEARCH</literal> is the default. </para> </listitem> </varlistentry> @@ -233,11 +233,11 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL The data type actually stored in the index. Normally this is the same as the column data type, but some index methods (currently GiST, GIN and BRIN) allow it to be different. The - <literal>STORAGE</> clause must be omitted unless the index + <literal>STORAGE</literal> clause must be omitted unless the index method allows a different type to be used. - If the column <replaceable class="parameter">data_type</> is specified - as <type>anyarray</>, the <replaceable class="parameter">storage_type</> - can be declared as <type>anyelement</> to indicate that the index + If the column <replaceable class="parameter">data_type</replaceable> is specified + as <type>anyarray</type>, the <replaceable class="parameter">storage_type</replaceable> + can be declared as <type>anyelement</type> to indicate that the index entries are members of the element type belonging to the actual array type that each particular index is created for. </para> @@ -246,7 +246,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </variablelist> <para> - The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</> + The <literal>OPERATOR</literal>, <literal>FUNCTION</literal>, and <literal>STORAGE</literal> clauses can appear in any order. </para> </refsect1> @@ -269,9 +269,9 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </para> <para> - Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</> - clause could include a <literal>RECHECK</> option. This is no longer - supported because whether an index operator is <quote>lossy</> is now + Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</literal> + clause could include a <literal>RECHECK</literal> option. This is no longer + supported because whether an index operator is <quote>lossy</quote> is now determined on-the-fly at run time. This allows efficient handling of cases where an operator might or might not be lossy. </para> @@ -282,7 +282,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <para> The following example command defines a GiST index operator class - for the data type <literal>_int4</> (array of <type>int4</type>). See the + for the data type <literal>_int4</literal> (array of <type>int4</type>). See the <xref linkend="intarray"> module for the complete example. </para> diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index 818e3a2315a..11c38fd38be 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -43,7 +43,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </para> <para> - The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1 + The operator name is a sequence of up to <symbol>NAMEDATALEN</symbol>-1 (63 by default) characters from the following list: <literallayout> + - * / < > = ~ ! @ # % ^ & | ` ? @@ -72,7 +72,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </listitem> <listitem> <para> - The use of <literal>=></> as an operator name is deprecated. It may + The use of <literal>=></literal> as an operator name is deprecated. It may be disallowed altogether in a future release. </para> </listitem> @@ -86,10 +86,10 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </para> <para> - At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For + At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For binary operators, both must be defined. For right unary - operators, only <literal>LEFTARG</> should be defined, while for left - unary operators only <literal>RIGHTARG</> should be defined. + operators, only <literal>LEFTARG</literal> should be defined, while for left + unary operators only <literal>RIGHTARG</literal> should be defined. </para> <para> @@ -122,11 +122,11 @@ CREATE OPERATOR <replaceable>name</replaceable> ( <para> The name of the operator to be defined. See above for allowable characters. The name can be schema-qualified, for example - <literal>CREATE OPERATOR myschema.+ (...)</>. If not, then + <literal>CREATE OPERATOR myschema.+ (...)</literal>. If not, then the operator is created in the current schema. Two operators in the same schema can have the same name if they operate on different data types. This is called - <firstterm>overloading</>. + <firstterm>overloading</firstterm>. </para> </listitem> </varlistentry> @@ -218,7 +218,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( <para> To give a schema-qualified operator name in <replaceable class="parameter">com_op</replaceable> or the other optional - arguments, use the <literal>OPERATOR()</> syntax, for example: + arguments, use the <literal>OPERATOR()</literal> syntax, for example: <programlisting> COMMUTATOR = OPERATOR(myschema.===) , </programlisting></para> @@ -233,18 +233,18 @@ COMMUTATOR = OPERATOR(myschema.===) , <para> It is not possible to specify an operator's lexical precedence in - <command>CREATE OPERATOR</>, because the parser's precedence behavior + <command>CREATE OPERATOR</command>, because the parser's precedence behavior is hard-wired. See <xref linkend="sql-precedence"> for precedence details. </para> <para> - The obsolete options <literal>SORT1</>, <literal>SORT2</>, - <literal>LTCMP</>, and <literal>GTCMP</> were formerly used to + The obsolete options <literal>SORT1</literal>, <literal>SORT2</literal>, + <literal>LTCMP</literal>, and <literal>GTCMP</literal> were formerly used to specify the names of sort operators associated with a merge-joinable operator. This is no longer necessary, since information about associated operators is found by looking at B-tree operator families instead. If one of these options is given, it is ignored except - for implicitly setting <literal>MERGES</> true. + for implicitly setting <literal>MERGES</literal> true. </para> <para> diff --git a/doc/src/sgml/ref/create_opfamily.sgml b/doc/src/sgml/ref/create_opfamily.sgml index c4bcf0863ef..ca5261b7a08 100644 --- a/doc/src/sgml/ref/create_opfamily.sgml +++ b/doc/src/sgml/ref/create_opfamily.sgml @@ -35,7 +35,7 @@ CREATE OPERATOR FAMILY <replaceable class="parameter">name</replaceable> USING < compatible with these operator classes but not essential for the functioning of any individual index. (Operators and functions that are essential to indexes should be grouped within the relevant operator - class, rather than being <quote>loose</> in the operator family. + class, rather than being <quote>loose</quote> in the operator family. Typically, single-data-type operators are bound to operator classes, while cross-data-type operators can be loose in an operator family containing operator classes for both data types.) @@ -45,7 +45,7 @@ CREATE OPERATOR FAMILY <replaceable class="parameter">name</replaceable> USING < The new operator family is initially empty. It should be populated by issuing subsequent <command>CREATE OPERATOR CLASS</command> commands to add contained operator classes, and optionally - <command>ALTER OPERATOR FAMILY</command> commands to add <quote>loose</> + <command>ALTER OPERATOR FAMILY</command> commands to add <quote>loose</quote> operators and their corresponding support functions. </para> diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml index 70df22c0593..1bcf2de4290 100644 --- a/doc/src/sgml/ref/create_policy.sgml +++ b/doc/src/sgml/ref/create_policy.sgml @@ -88,7 +88,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable <para> If row-level security is enabled for a table, but no applicable policies - exist, a <quote>default deny</> policy is assumed, so that no rows will + exist, a <quote>default deny</quote> policy is assumed, so that no rows will be visible or updatable. </para> </refsect1> @@ -188,9 +188,9 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable to queries that refer to the table if row level security is enabled. Rows for which the expression returns true will be visible. Any rows for which the expression returns false or null will not be - visible to the user (in a <command>SELECT</>), and will not be - available for modification (in an <command>UPDATE</> - or <command>DELETE</>). Such rows are silently suppressed; no error + visible to the user (in a <command>SELECT</command>), and will not be + available for modification (in an <command>UPDATE</command> + or <command>DELETE</command>). Such rows are silently suppressed; no error is reported. </para> </listitem> @@ -223,7 +223,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable <variablelist> <varlistentry id="SQL-CREATEPOLICY-ALL"> - <term><literal>ALL</></term> + <term><literal>ALL</literal></term> <listitem> <para> Using <literal>ALL</literal> for a policy means that it will apply @@ -254,7 +254,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-SELECT"> - <term><literal>SELECT</></term> + <term><literal>SELECT</literal></term> <listitem> <para> Using <literal>SELECT</literal> for a policy means that it will apply @@ -274,7 +274,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-INSERT"> - <term><literal>INSERT</></term> + <term><literal>INSERT</literal></term> <listitem> <para> Using <literal>INSERT</literal> for a policy means that it will apply @@ -295,7 +295,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-UPDATE"> - <term><literal>UPDATE</></term> + <term><literal>UPDATE</literal></term> <listitem> <para> Using <literal>UPDATE</literal> for a policy means that it will apply @@ -347,14 +347,14 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable Note, however, that unlike a standalone <literal>UPDATE</literal> command, if the existing row does not pass the <literal>USING</literal> expressions, an error will be thrown (the - <literal>UPDATE</literal> path will <emphasis>never</> be silently + <literal>UPDATE</literal> path will <emphasis>never</emphasis> be silently avoided). </para> </listitem> </varlistentry> <varlistentry id="SQL-CREATEPOLICY-DELETE"> - <term><literal>DELETE</></term> + <term><literal>DELETE</literal></term> <listitem> <para> Using <literal>DELETE</literal> for a policy means that it will apply diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml index 62a5fd432e6..b997d387e77 100644 --- a/doc/src/sgml/ref/create_publication.sgml +++ b/doc/src/sgml/ref/create_publication.sgml @@ -64,10 +64,10 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <listitem> <para> Specifies a list of tables to add to the publication. If - <literal>ONLY</> is specified before the table name, only - that table is added to the publication. If <literal>ONLY</> is not + <literal>ONLY</literal> is specified before the table name, only + that table is added to the publication. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are added. - Optionally, <literal>*</> can be specified after the table name to + Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> @@ -138,7 +138,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <para> To create a publication, the invoking user must have the - <literal>CREATE</> privilege for the current database. + <literal>CREATE</literal> privilege for the current database. (Of course, superusers bypass this check.) </para> @@ -151,12 +151,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <para> The tables added to a publication that publishes <command>UPDATE</command> and/or <command>DELETE</command> operations must have - <literal>REPLICA IDENTITY</> defined. Otherwise those operations will be + <literal>REPLICA IDENTITY</literal> defined. Otherwise those operations will be disallowed on those tables. </para> <para> - For an <command>INSERT ... ON CONFLICT</> command, the publication will + For an <command>INSERT ... ON CONFLICT</command> command, the publication will publish the operation that actually results from the command. So depending of the outcome, it may be published as either <command>INSERT</command> or <command>UPDATE</command>, or it may not be published at all. @@ -203,7 +203,7 @@ CREATE PUBLICATION insert_only FOR TABLE mydata <title>Compatibility</title> <para> - <command>CREATE PUBLICATION</command> is a <productname>PostgreSQL</> + <command>CREATE PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index 41670c4b059..4a4061a2371 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -51,11 +51,11 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <command>CREATE ROLE</command> adds a new role to a <productname>PostgreSQL</productname> database cluster. A role is an entity that can own database objects and have database privileges; - a role can be considered a <quote>user</>, a <quote>group</>, or both + a role can be considered a <quote>user</quote>, a <quote>group</quote>, or both depending on how it is used. Refer to <xref linkend="user-manag"> and <xref linkend="client-authentication"> for information about managing - users and authentication. You must have <literal>CREATEROLE</> + users and authentication. You must have <literal>CREATEROLE</literal> privilege or be a database superuser to use this command. </para> @@ -83,7 +83,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <term><literal>NOSUPERUSER</literal></term> <listitem> <para> - These clauses determine whether the new role is a <quote>superuser</>, + These clauses determine whether the new role is a <quote>superuser</quote>, who can override all access restrictions within the database. Superuser status is dangerous and should be used only when really needed. You must yourself be a superuser to create a new superuser. @@ -94,8 +94,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term><literal>CREATEDB</></term> - <term><literal>NOCREATEDB</></term> + <term><literal>CREATEDB</literal></term> + <term><literal>NOCREATEDB</literal></term> <listitem> <para> These clauses define a role's ability to create databases. If @@ -128,13 +128,13 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <term><literal>NOINHERIT</literal></term> <listitem> <para> - These clauses determine whether a role <quote>inherits</> the + These clauses determine whether a role <quote>inherits</quote> the privileges of roles it is a member of. A role with the <literal>INHERIT</literal> attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of. Without <literal>INHERIT</literal>, membership in another role - only grants the ability to <command>SET ROLE</> to that other role; + only grants the ability to <command>SET ROLE</command> to that other role; the privileges of the other role are only available after having done so. If not specified, @@ -156,7 +156,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac privileges, but are not users in the usual sense of the word. If not specified, <literal>NOLOGIN</literal> is the default, except when - <command>CREATE ROLE</> is invoked through its alternative spelling + <command>CREATE ROLE</command> is invoked through its alternative spelling <xref linkend="sql-createuser">. </para> </listitem> @@ -172,7 +172,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac connect to the server in replication mode (physical or logical replication) and in order to be able to create or drop replication slots. - A role having the <literal>REPLICATION</> attribute is a very + A role having the <literal>REPLICATION</literal> attribute is a very highly privileged role, and should only be used on roles actually used for replication. If not specified, <literal>NOREPLICATION</literal> is the default. @@ -210,7 +210,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> + <term>[ <literal>ENCRYPTED</literal> ] <literal>PASSWORD</literal> <replaceable class="parameter">password</replaceable></term> <listitem> <para> Sets the role's password. (A password is only of use for @@ -225,7 +225,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <note> <para> Specifying an empty string will also set the password to null, - but that was not the case before <productname>PostgreSQL</> + but that was not the case before <productname>PostgreSQL</productname> version 10. In earlier versions, an empty string could be used, or not, depending on the authentication method and the exact version, and libpq would refuse to use it in any case. @@ -235,12 +235,12 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </note> <para> The password is always stored encrypted in the system catalogs. The - <literal>ENCRYPTED</> keyword has no effect, but is accepted for + <literal>ENCRYPTED</literal> keyword has no effect, but is accepted for backwards compatibility. The method of encryption is determined by the configuration parameter <xref linkend="guc-password-encryption">. If the presented password string is already in MD5-encrypted or SCRAM-encrypted format, then it is stored as-is regardless of - <varname>password_encryption</> (since the system cannot decrypt + <varname>password_encryption</varname> (since the system cannot decrypt the specified encrypted password string, to encrypt it in a different format). This allows reloading of encrypted passwords during dump/restore. @@ -260,61 +260,61 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term><literal>IN ROLE</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>IN ROLE</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>IN ROLE</literal> clause lists one or more existing roles to which the new role will be immediately added as a new member. (Note that there is no option to add the new role as an - administrator; use a separate <command>GRANT</> command to do that.) + administrator; use a separate <command>GRANT</command> command to do that.) </para> </listitem> </varlistentry> <varlistentry> - <term><literal>IN GROUP</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>IN GROUP</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para><literal>IN GROUP</literal> is an obsolete spelling of - <literal>IN ROLE</>. + <literal>IN ROLE</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ROLE</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>ROLE</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>ROLE</literal> clause lists one or more existing roles which are automatically added as members of the new role. - (This in effect makes the new role a <quote>group</>.) + (This in effect makes the new role a <quote>group</quote>.) </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ADMIN</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>ADMIN</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>ADMIN</literal> clause is like <literal>ROLE</literal>, but the named roles are added to the new role <literal>WITH ADMIN - OPTION</>, giving them the right to grant membership in this role + OPTION</literal>, giving them the right to grant membership in this role to others. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>USER</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>USER</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>USER</literal> clause is an obsolete spelling of - the <literal>ROLE</> clause. + the <literal>ROLE</literal> clause. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>SYSID</> <replaceable class="parameter">uid</replaceable></term> + <term><literal>SYSID</literal> <replaceable class="parameter">uid</replaceable></term> <listitem> <para> The <literal>SYSID</literal> clause is ignored, but is accepted @@ -332,8 +332,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac Use <xref linkend="SQL-ALTERROLE"> to change the attributes of a role, and <xref linkend="SQL-DROPROLE"> to remove a role. All the attributes - specified by <command>CREATE ROLE</> can be modified by later - <command>ALTER ROLE</> commands. + specified by <command>CREATE ROLE</command> can be modified by later + <command>ALTER ROLE</command> commands. </para> <para> @@ -344,42 +344,42 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </para> <para> - The <literal>VALID UNTIL</> clause defines an expiration time for a - password only, not for the role <foreignphrase>per se</>. In + The <literal>VALID UNTIL</literal> clause defines an expiration time for a + password only, not for the role <foreignphrase>per se</foreignphrase>. In particular, the expiration time is not enforced when logging in using a non-password-based authentication method. </para> <para> - The <literal>INHERIT</> attribute governs inheritance of grantable + The <literal>INHERIT</literal> attribute governs inheritance of grantable privileges (that is, access privileges for database objects and role memberships). It does not apply to the special role attributes set by - <command>CREATE ROLE</> and <command>ALTER ROLE</>. For example, being - a member of a role with <literal>CREATEDB</> privilege does not immediately - grant the ability to create databases, even if <literal>INHERIT</> is set; + <command>CREATE ROLE</command> and <command>ALTER ROLE</command>. For example, being + a member of a role with <literal>CREATEDB</literal> privilege does not immediately + grant the ability to create databases, even if <literal>INHERIT</literal> is set; it would be necessary to become that role via <xref linkend="SQL-SET-ROLE"> before creating a database. </para> <para> - The <literal>INHERIT</> attribute is the default for reasons of backwards + The <literal>INHERIT</literal> attribute is the default for reasons of backwards compatibility: in prior releases of <productname>PostgreSQL</productname>, users always had access to all privileges of groups they were members of. - However, <literal>NOINHERIT</> provides a closer match to the semantics + However, <literal>NOINHERIT</literal> provides a closer match to the semantics specified in the SQL standard. </para> <para> - Be careful with the <literal>CREATEROLE</> privilege. There is no concept of - inheritance for the privileges of a <literal>CREATEROLE</>-role. That + Be careful with the <literal>CREATEROLE</literal> privilege. There is no concept of + inheritance for the privileges of a <literal>CREATEROLE</literal>-role. That means that even if a role does not have a certain privilege but is allowed to create other roles, it can easily create another role with different privileges than its own (except for creating roles with superuser - privileges). For example, if the role <quote>user</> has the - <literal>CREATEROLE</> privilege but not the <literal>CREATEDB</> privilege, - nonetheless it can create a new role with the <literal>CREATEDB</> - privilege. Therefore, regard roles that have the <literal>CREATEROLE</> + privileges). For example, if the role <quote>user</quote> has the + <literal>CREATEROLE</literal> privilege but not the <literal>CREATEDB</literal> privilege, + nonetheless it can create a new role with the <literal>CREATEDB</literal> + privilege. Therefore, regard roles that have the <literal>CREATEROLE</literal> privilege as almost-superuser-roles. </para> @@ -391,9 +391,9 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </para> <para> - The <literal>CONNECTION LIMIT</> option is only enforced approximately; + The <literal>CONNECTION LIMIT</literal> option is only enforced approximately; if two new sessions start at about the same time when just one - connection <quote>slot</> remains for the role, it is possible that + connection <quote>slot</quote> remains for the role, it is possible that both will fail. Also, the limit is never enforced for superusers. </para> @@ -425,8 +425,8 @@ CREATE ROLE jonathan LOGIN; <programlisting> CREATE USER davide WITH PASSWORD 'jw8s0F4'; </programlisting> - (<command>CREATE USER</> is the same as <command>CREATE ROLE</> except - that it implies <literal>LOGIN</>.) + (<command>CREATE USER</command> is the same as <command>CREATE ROLE</command> except + that it implies <literal>LOGIN</literal>.) </para> <para> @@ -453,7 +453,7 @@ CREATE ROLE admin WITH CREATEDB CREATEROLE; The <command>CREATE ROLE</command> statement is in the SQL standard, but the standard only requires the syntax <synopsis> -CREATE ROLE <replaceable class="parameter">name</> [ WITH ADMIN <replaceable class="parameter">role_name</> ] +CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <replaceable class="parameter">role_name</replaceable> ] </synopsis> Multiple initial administrators, and all the other options of <command>CREATE ROLE</command>, are @@ -471,8 +471,8 @@ CREATE ROLE <replaceable class="parameter">name</> [ WITH ADMIN <replaceable cla <para> The behavior specified by the SQL standard is most closely approximated - by giving users the <literal>NOINHERIT</> attribute, while roles are - given the <literal>INHERIT</> attribute. + by giving users the <literal>NOINHERIT</literal> attribute, while roles are + given the <literal>INHERIT</literal> attribute. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_rule.sgml b/doc/src/sgml/ref/create_rule.sgml index 53fdf566214..c772c383991 100644 --- a/doc/src/sgml/ref/create_rule.sgml +++ b/doc/src/sgml/ref/create_rule.sgml @@ -76,13 +76,13 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <literal>ON DELETE</literal> rules (or any subset of those that's sufficient for your purposes) to replace update actions on the view with appropriate updates on other tables. If you want to support - <command>INSERT RETURNING</> and so on, then be sure to put a suitable - <literal>RETURNING</> clause into each of these rules. + <command>INSERT RETURNING</command> and so on, then be sure to put a suitable + <literal>RETURNING</literal> clause into each of these rules. </para> <para> There is a catch if you try to use conditional rules for complex view - updates: there <emphasis>must</> be an unconditional + updates: there <emphasis>must</emphasis> be an unconditional <literal>INSTEAD</literal> rule for each action you wish to allow on the view. If the rule is conditional, or is not <literal>INSTEAD</literal>, then the system will still reject @@ -95,7 +95,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS Then make the conditional rules non-<literal>INSTEAD</literal>; in the cases where they are applied, they add to the default <literal>INSTEAD NOTHING</literal> action. (This method does not - currently work to support <literal>RETURNING</> queries, however.) + currently work to support <literal>RETURNING</literal> queries, however.) </para> <note> @@ -108,7 +108,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS </para> <para> - Another alternative worth considering is to use <literal>INSTEAD OF</> + Another alternative worth considering is to use <literal>INSTEAD OF</literal> triggers (see <xref linkend="sql-createtrigger">) in place of rules. </para> </note> @@ -161,7 +161,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <para> Any <acronym>SQL</acronym> conditional expression (returning <type>boolean</type>). The condition expression cannot refer - to any tables except <literal>NEW</> and <literal>OLD</>, and + to any tables except <literal>NEW</literal> and <literal>OLD</literal>, and cannot contain aggregate functions. </para> </listitem> @@ -171,7 +171,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <term><option>INSTEAD</option></term> <listitem> <para><literal>INSTEAD</literal> indicates that the commands should be - executed <emphasis>instead of</> the original command. + executed <emphasis>instead of</emphasis> the original command. </para> </listitem> </varlistentry> @@ -227,19 +227,19 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <para> In a rule for <literal>INSERT</literal>, <literal>UPDATE</literal>, or - <literal>DELETE</literal> on a view, you can add a <literal>RETURNING</> + <literal>DELETE</literal> on a view, you can add a <literal>RETURNING</literal> clause that emits the view's columns. This clause will be used to compute - the outputs if the rule is triggered by an <command>INSERT RETURNING</>, - <command>UPDATE RETURNING</>, or <command>DELETE RETURNING</> command + the outputs if the rule is triggered by an <command>INSERT RETURNING</command>, + <command>UPDATE RETURNING</command>, or <command>DELETE RETURNING</command> command respectively. When the rule is triggered by a command without - <literal>RETURNING</>, the rule's <literal>RETURNING</> clause will be + <literal>RETURNING</literal>, the rule's <literal>RETURNING</literal> clause will be ignored. The current implementation allows only unconditional - <literal>INSTEAD</> rules to contain <literal>RETURNING</>; furthermore - there can be at most one <literal>RETURNING</> clause among all the rules + <literal>INSTEAD</literal> rules to contain <literal>RETURNING</literal>; furthermore + there can be at most one <literal>RETURNING</literal> clause among all the rules for the same event. (This ensures that there is only one candidate - <literal>RETURNING</> clause to be used to compute the results.) - <literal>RETURNING</> queries on the view will be rejected if - there is no <literal>RETURNING</> clause in any available rule. + <literal>RETURNING</literal> clause to be used to compute the results.) + <literal>RETURNING</literal> queries on the view will be rejected if + there is no <literal>RETURNING</literal> clause in any available rule. </para> <para> diff --git a/doc/src/sgml/ref/create_schema.sgml b/doc/src/sgml/ref/create_schema.sgml index ce145f96a0b..ce3530c0489 100644 --- a/doc/src/sgml/ref/create_schema.sgml +++ b/doc/src/sgml/ref/create_schema.sgml @@ -48,9 +48,9 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp A schema is essentially a namespace: it contains named objects (tables, data types, functions, and operators) whose names can duplicate those of other objects existing in other - schemas. Named objects are accessed either by <quote>qualifying</> + schemas. Named objects are accessed either by <quote>qualifying</quote> their names with the schema name as a prefix, or by setting a search - path that includes the desired schema(s). A <literal>CREATE</> command + path that includes the desired schema(s). A <literal>CREATE</literal> command specifying an unqualified object name creates the object in the current schema (the one at the front of the search path, which can be determined with the function <function>current_schema</function>). @@ -60,7 +60,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp Optionally, <command>CREATE SCHEMA</command> can include subcommands to create objects within the new schema. The subcommands are treated essentially the same as separate commands issued after creating the - schema, except that if the <literal>AUTHORIZATION</> clause is used, + schema, except that if the <literal>AUTHORIZATION</literal> clause is used, all the created objects will be owned by that user. </para> </refsect1> @@ -100,10 +100,10 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <para> An SQL statement defining an object to be created within the schema. Currently, only <command>CREATE - TABLE</>, <command>CREATE VIEW</>, <command>CREATE - INDEX</>, <command>CREATE SEQUENCE</>, <command>CREATE - TRIGGER</> and <command>GRANT</> are accepted as clauses - within <command>CREATE SCHEMA</>. Other kinds of objects may + TABLE</command>, <command>CREATE VIEW</command>, <command>CREATE + INDEX</command>, <command>CREATE SEQUENCE</command>, <command>CREATE + TRIGGER</command> and <command>GRANT</command> are accepted as clauses + within <command>CREATE SCHEMA</command>. Other kinds of objects may be created in separate commands after the schema is created. </para> </listitem> @@ -114,7 +114,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <listitem> <para> Do nothing (except issuing a notice) if a schema with the same name - already exists. <replaceable class="parameter">schema_element</> + already exists. <replaceable class="parameter">schema_element</replaceable> subcommands cannot be included when this option is used. </para> </listitem> @@ -127,7 +127,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <para> To create a schema, the invoking user must have the - <literal>CREATE</> privilege for the current database. + <literal>CREATE</literal> privilege for the current database. (Of course, superusers bypass this check.) </para> </refsect1> @@ -143,17 +143,17 @@ CREATE SCHEMA myschema; </para> <para> - Create a schema for user <literal>joe</>; the schema will also be - named <literal>joe</>: + Create a schema for user <literal>joe</literal>; the schema will also be + named <literal>joe</literal>: <programlisting> CREATE SCHEMA AUTHORIZATION joe; </programlisting> </para> <para> - Create a schema named <literal>test</> that will be owned by user - <literal>joe</>, unless there already is a schema named <literal>test</>. - (It does not matter whether <literal>joe</> owns the pre-existing schema.) + Create a schema named <literal>test</literal> that will be owned by user + <literal>joe</literal>, unless there already is a schema named <literal>test</literal>. + (It does not matter whether <literal>joe</literal> owns the pre-existing schema.) <programlisting> CREATE SCHEMA IF NOT EXISTS test AUTHORIZATION joe; </programlisting> @@ -185,7 +185,7 @@ CREATE VIEW hollywood.winners AS <title>Compatibility</title> <para> - The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause + The SQL standard allows a <literal>DEFAULT CHARACTER SET</literal> clause in <command>CREATE SCHEMA</command>, as well as more subcommand types than are presently accepted by <productname>PostgreSQL</productname>. @@ -205,7 +205,7 @@ CREATE VIEW hollywood.winners AS all objects within it. <productname>PostgreSQL</productname> allows schemas to contain objects owned by users other than the schema owner. This can happen only if the schema owner grants the - <literal>CREATE</> privilege on their schema to someone else, or a + <literal>CREATE</literal> privilege on their schema to someone else, or a superuser chooses to create objects in it. </para> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 2af8c8d23e3..9248b1d459a 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -67,10 +67,10 @@ SELECT * FROM <replaceable>name</replaceable>; </programlisting> to examine the parameters and current state of a sequence. In particular, - the <literal>last_value</> field of the sequence shows the last value + the <literal>last_value</literal> field of the sequence shows the last value allocated by any session. (Of course, this value might be obsolete by the time it's printed, if other sessions are actively doing - <function>nextval</> calls.) + <function>nextval</function> calls.) </para> </refsect1> @@ -250,14 +250,14 @@ SELECT * FROM <replaceable>name</replaceable>; </para> <para> - Sequences are based on <type>bigint</> arithmetic, so the range + Sequences are based on <type>bigint</type> arithmetic, so the range cannot exceed the range of an eight-byte integer (-9223372036854775808 to 9223372036854775807). </para> <para> - Because <function>nextval</> and <function>setval</> calls are never - rolled back, sequence objects cannot be used if <quote>gapless</> + Because <function>nextval</function> and <function>setval</function> calls are never + rolled back, sequence objects cannot be used if <quote>gapless</quote> assignment of sequence numbers is needed. It is possible to build gapless assignment by using exclusive locking of a table containing a counter; but this solution is much more expensive than sequence @@ -271,9 +271,9 @@ SELECT * FROM <replaceable>name</replaceable>; used for a sequence object that will be used concurrently by multiple sessions. Each session will allocate and cache successive sequence values during one access to the sequence object and - increase the sequence object's <literal>last_value</> accordingly. + increase the sequence object's <literal>last_value</literal> accordingly. Then, the next <replaceable class="parameter">cache</replaceable>-1 - uses of <function>nextval</> within that session simply return the + uses of <function>nextval</function> within that session simply return the preallocated values without touching the sequence object. So, any numbers allocated but not used within a session will be lost when that session ends, resulting in <quote>holes</quote> in the @@ -290,18 +290,18 @@ SELECT * FROM <replaceable>name</replaceable>; 11..20 and return <function>nextval</function>=11 before session A has generated <literal>nextval</literal>=2. Thus, with a <replaceable class="parameter">cache</replaceable> setting of one - it is safe to assume that <function>nextval</> values are generated + it is safe to assume that <function>nextval</function> values are generated sequentially; with a <replaceable class="parameter">cache</replaceable> setting greater than one you - should only assume that the <function>nextval</> values are all + should only assume that the <function>nextval</function> values are all distinct, not that they are generated purely sequentially. Also, - <literal>last_value</> will reflect the latest value reserved by + <literal>last_value</literal> will reflect the latest value reserved by any session, whether or not it has yet been returned by - <function>nextval</>. + <function>nextval</function>. </para> <para> - Another consideration is that a <function>setval</> executed on + Another consideration is that a <function>setval</function> executed on such a sequence will not be noticed by other sessions until they have used up any preallocated values they have cached. </para> @@ -365,14 +365,14 @@ END; <itemizedlist> <listitem> <para> - Obtaining the next value is done using the <function>nextval()</> + Obtaining the next value is done using the <function>nextval()</function> function instead of the standard's <command>NEXT VALUE FOR</command> expression. </para> </listitem> <listitem> <para> - The <literal>OWNED BY</> clause is a <productname>PostgreSQL</> + The <literal>OWNED BY</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </listitem> diff --git a/doc/src/sgml/ref/create_server.sgml b/doc/src/sgml/ref/create_server.sgml index 47b8a6291bb..e14ce43bf9e 100644 --- a/doc/src/sgml/ref/create_server.sgml +++ b/doc/src/sgml/ref/create_server.sgml @@ -47,7 +47,7 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac </para> <para> - Creating a server requires <literal>USAGE</> privilege on the + Creating a server requires <literal>USAGE</literal> privilege on the foreign-data wrapper being used. </para> </refsect1> @@ -57,7 +57,7 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a server with the same name already exists. @@ -135,8 +135,8 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac <title>Examples</title> <para> - Create a server <literal>myserver</> that uses the - foreign-data wrapper <literal>postgres_fdw</>: + Create a server <literal>myserver</literal> that uses the + foreign-data wrapper <literal>postgres_fdw</literal>: <programlisting> CREATE SERVER myserver FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host 'foo', dbname 'foodb', port '5432'); </programlisting> diff --git a/doc/src/sgml/ref/create_statistics.sgml b/doc/src/sgml/ref/create_statistics.sgml index 0d68ca06b72..066af8a4b4d 100644 --- a/doc/src/sgml/ref/create_statistics.sgml +++ b/doc/src/sgml/ref/create_statistics.sgml @@ -41,7 +41,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <para> If a schema name is given (for example, <literal>CREATE STATISTICS - myschema.mystat ...</>) then the statistics object is created in the + myschema.mystat ...</literal>) then the statistics object is created in the specified schema. Otherwise it is created in the current schema. The name of the statistics object must be distinct from the name of any other statistics object in the same schema. @@ -54,7 +54,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a statistics object with the same name already @@ -129,7 +129,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <title>Examples</title> <para> - Create table <structname>t1</> with two functionally dependent columns, i.e. + Create table <structname>t1</structname> with two functionally dependent columns, i.e. knowledge of a value in the first column is sufficient for determining the value in the other column. Then functional dependency statistics are built on those columns: @@ -157,10 +157,10 @@ EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); </programlisting> Without functional-dependency statistics, the planner would assume - that the two <literal>WHERE</> conditions are independent, and would + that the two <literal>WHERE</literal> conditions are independent, and would multiply their selectivities together to arrive at a much-too-small row count estimate. - With such statistics, the planner recognizes that the <literal>WHERE</> + With such statistics, the planner recognizes that the <literal>WHERE</literal> conditions are redundant and does not underestimate the rowcount. </para> diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index bae9f839bd2..cd51b7fcac5 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -201,7 +201,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl to <literal>false</literal>, the tables are not subscribed, and so after you enable the subscription nothing will be replicated. It is required to run - <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order + <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order for tables to be subscribed. </para> </listitem> @@ -272,7 +272,7 @@ CREATE SUBSCRIPTION mysub <title>Compatibility</title> <para> - <command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index d15795857b1..2db2e9fc444 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -113,7 +113,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> If a schema name is given (for example, <literal>CREATE TABLE - myschema.mytable ...</>) then the table is created in the specified + myschema.mytable ...</literal>) then the table is created in the specified schema. Otherwise it is created in the current schema. Temporary tables exist in a special schema, so a schema name cannot be given when creating a temporary table. The name of the table must be @@ -158,7 +158,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <variablelist> <varlistentry id="SQL-CREATETABLE-TEMPORARY"> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the table is created as a temporary table. @@ -177,13 +177,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace For this reason, appropriate vacuum and analyze operations should be performed via session SQL commands. For example, if a temporary table is going to be used in complex queries, it is wise to run - <command>ANALYZE</> on the temporary table after it is populated. + <command>ANALYZE</command> on the temporary table after it is populated. </para> <para> Optionally, <literal>GLOBAL</literal> or <literal>LOCAL</literal> - can be written before <literal>TEMPORARY</> or <literal>TEMP</>. - This presently makes no difference in <productname>PostgreSQL</> + can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>. + This presently makes no difference in <productname>PostgreSQL</productname> and is deprecated; see <xref linkend="sql-createtable-compatibility" endterm="sql-createtable-compatibility-title">. @@ -192,7 +192,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry id="SQL-CREATETABLE-UNLOGGED"> - <term><literal>UNLOGGED</></term> + <term><literal>UNLOGGED</literal></term> <listitem> <para> If specified, the table is created as an unlogged table. Data written @@ -208,7 +208,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -263,14 +263,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace The <replaceable class="parameter">partition_bound_spec</replaceable> must correspond to the partitioning method and partition key of the parent table, and must not overlap with any existing partition of that - parent. The form with <literal>IN</> is used for list partitioning, - while the form with <literal>FROM</> and <literal>TO</> is used for + parent. The form with <literal>IN</literal> is used for list partitioning, + while the form with <literal>FROM</literal> and <literal>TO</literal> is used for range partitioning. </para> <para> Each of the values specified in - the <replaceable class="parameter">partition_bound_spec</> is + the <replaceable class="parameter">partition_bound_spec</replaceable> is a literal, <literal>NULL</literal>, <literal>MINVALUE</literal>, or <literal>MAXVALUE</literal>. Each literal value must be either a numeric constant that is coercible to the corresponding partition key @@ -294,52 +294,52 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace partition, whereas those in the <literal>TO</literal> list are not. Note that this statement must be understood according to the rules of row-wise comparison (<xref linkend="row-wise-comparison">). - For example, given <literal>PARTITION BY RANGE (x,y)</>, a partition + For example, given <literal>PARTITION BY RANGE (x,y)</literal>, a partition bound <literal>FROM (1, 2) TO (3, 4)</literal> - allows <literal>x=1</> with any <literal>y>=2</>, - <literal>x=2</> with any non-null <literal>y</>, - and <literal>x=3</> with any <literal>y<4</>. + allows <literal>x=1</literal> with any <literal>y>=2</literal>, + <literal>x=2</literal> with any non-null <literal>y</literal>, + and <literal>x=3</literal> with any <literal>y<4</literal>. </para> <para> - The special values <literal>MINVALUE</> and <literal>MAXVALUE</> + The special values <literal>MINVALUE</literal> and <literal>MAXVALUE</literal> may be used when creating a range partition to indicate that there is no lower or upper bound on the column's value. For example, a - partition defined using <literal>FROM (MINVALUE) TO (10)</> allows + partition defined using <literal>FROM (MINVALUE) TO (10)</literal> allows any values less than 10, and a partition defined using - <literal>FROM (10) TO (MAXVALUE)</> allows any values greater than + <literal>FROM (10) TO (MAXVALUE)</literal> allows any values greater than or equal to 10. </para> <para> When creating a range partition involving more than one column, it - can also make sense to use <literal>MAXVALUE</> as part of the lower - bound, and <literal>MINVALUE</> as part of the upper bound. For + can also make sense to use <literal>MAXVALUE</literal> as part of the lower + bound, and <literal>MINVALUE</literal> as part of the upper bound. For example, a partition defined using - <literal>FROM (0, MAXVALUE) TO (10, MAXVALUE)</> allows any rows + <literal>FROM (0, MAXVALUE) TO (10, MAXVALUE)</literal> allows any rows where the first partition key column is greater than 0 and less than or equal to 10. Similarly, a partition defined using - <literal>FROM ('a', MINVALUE) TO ('b', MINVALUE)</> allows any rows + <literal>FROM ('a', MINVALUE) TO ('b', MINVALUE)</literal> allows any rows where the first partition key column starts with "a". </para> <para> - Note that if <literal>MINVALUE</> or <literal>MAXVALUE</> is used for + Note that if <literal>MINVALUE</literal> or <literal>MAXVALUE</literal> is used for one column of a partitioning bound, the same value must be used for all - subsequent columns. For example, <literal>(10, MINVALUE, 0)</> is not - a valid bound; you should write <literal>(10, MINVALUE, MINVALUE)</>. + subsequent columns. For example, <literal>(10, MINVALUE, 0)</literal> is not + a valid bound; you should write <literal>(10, MINVALUE, MINVALUE)</literal>. </para> <para> - Also note that some element types, such as <literal>timestamp</>, + Also note that some element types, such as <literal>timestamp</literal>, have a notion of "infinity", which is just another value that can - be stored. This is different from <literal>MINVALUE</> and - <literal>MAXVALUE</>, which are not real values that can be stored, + be stored. This is different from <literal>MINVALUE</literal> and + <literal>MAXVALUE</literal>, which are not real values that can be stored, but rather they are ways of saying that the value is unbounded. - <literal>MAXVALUE</> can be thought of as being greater than any - other value, including "infinity" and <literal>MINVALUE</> as being + <literal>MAXVALUE</literal> can be thought of as being greater than any + other value, including "infinity" and <literal>MINVALUE</literal> as being less than any other value, including "minus infinity". Thus the range - <literal>FROM ('infinity') TO (MAXVALUE)</> is not an empty range; it + <literal>FROM ('infinity') TO (MAXVALUE)</literal> is not an empty range; it allows precisely one value to be stored — "infinity". </para> @@ -370,9 +370,9 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace column will be inherited by all partitions just like any other column. Modifications to the column names or types of a partitioned table, or the addition or removal of an OID column, will automatically propagate - to all partitions. <literal>CHECK</> constraints will be inherited + to all partitions. <literal>CHECK</literal> constraints will be inherited automatically by every partition, but an individual partition may specify - additional <literal>CHECK</> constraints; additional constraints with + additional <literal>CHECK</literal> constraints; additional constraints with the same name and condition as in the parent will be merged with the parent constraint. Defaults may be specified separately for each partition. @@ -421,7 +421,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>COLLATE <replaceable>collation</replaceable></literal></term> <listitem> <para> - The <literal>COLLATE</> clause assigns a collation to + The <literal>COLLATE</literal> clause assigns a collation to the column (which must be of a collatable data type). If not specified, the column data type's default collation is used. </para> @@ -432,13 +432,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term> <listitem> <para> - The optional <literal>INHERITS</> clause specifies a list of + The optional <literal>INHERITS</literal> clause specifies a list of tables from which the new table automatically inherits all columns. Parent tables can be plain tables or foreign tables. </para> <para> - Use of <literal>INHERITS</> creates a persistent relationship + Use of <literal>INHERITS</literal> creates a persistent relationship between the new child table and its parent table(s). Schema modifications to the parent(s) normally propagate to children as well, and by default the data of the child table is included in @@ -462,19 +462,19 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - <literal>CHECK</> constraints are merged in essentially the same way as + <literal>CHECK</literal> constraints are merged in essentially the same way as columns: if multiple parent tables and/or the new table definition - contain identically-named <literal>CHECK</> constraints, these + contain identically-named <literal>CHECK</literal> constraints, these constraints must all have the same check expression, or an error will be reported. Constraints having the same name and expression will - be merged into one copy. A constraint marked <literal>NO INHERIT</> in a - parent will not be considered. Notice that an unnamed <literal>CHECK</> + be merged into one copy. A constraint marked <literal>NO INHERIT</literal> in a + parent will not be considered. Notice that an unnamed <literal>CHECK</literal> constraint in the new table will never be merged, since a unique name will always be chosen for it. </para> <para> - Column <literal>STORAGE</> settings are also copied from parent tables. + Column <literal>STORAGE</literal> settings are also copied from parent tables. </para> <para> @@ -504,7 +504,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> A partitioned table is divided into sub-tables (called partitions), - which are created using separate <literal>CREATE TABLE</> commands. + which are created using separate <literal>CREATE TABLE</literal> commands. The partitioned table is itself empty. A data row inserted into the table is routed to a partition based on the value of columns or expressions in the partition key. If no existing partition matches @@ -542,7 +542,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace default behavior is to exclude default expressions, resulting in the copied columns in the new table having null defaults. Note that copying defaults that call database-modification functions, - such as <function>nextval</>, may create a functional linkage between + such as <function>nextval</function>, may create a functional linkage between the original and new tables. </para> <para> @@ -559,8 +559,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace constraints. </para> <para> - Indexes, <literal>PRIMARY KEY</>, <literal>UNIQUE</>, - and <literal>EXCLUDE</> constraints on the original table will be + Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>, + and <literal>EXCLUDE</literal> constraints on the original table will be created on the new table only if <literal>INCLUDING INDEXES</literal> is specified. Names for the new indexes and constraints are chosen according to the default rules, regardless of how the originals @@ -568,11 +568,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace the new indexes.) </para> <para> - <literal>STORAGE</> settings for the copied column definitions will be + <literal>STORAGE</literal> settings for the copied column definitions will be copied only if <literal>INCLUDING STORAGE</literal> is specified. The - default behavior is to exclude <literal>STORAGE</> settings, resulting + default behavior is to exclude <literal>STORAGE</literal> settings, resulting in the copied columns in the new table having type-specific default - settings. For more on <literal>STORAGE</> settings, see + settings. For more on <literal>STORAGE</literal> settings, see <xref linkend="storage-toast">. </para> <para> @@ -587,7 +587,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> Note that unlike <literal>INHERITS</literal>, columns and - constraints copied by <literal>LIKE</> are not merged with similarly + constraints copied by <literal>LIKE</literal> are not merged with similarly named columns and constraints. If the same name is specified explicitly or in another <literal>LIKE</literal> clause, an error is signaled. @@ -607,7 +607,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> An optional name for a column or table constraint. If the constraint is violated, the constraint name is present in error messages, - so constraint names like <literal>col must be positive</> can be used + so constraint names like <literal>col must be positive</literal> can be used to communicate helpful constraint information to client applications. (Double-quotes are needed to specify constraint names that contain spaces.) If a constraint name is not specified, the system generates a name. @@ -616,7 +616,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> The column is not allowed to contain null values. @@ -625,7 +625,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> The column is allowed to contain null values. This is the default. @@ -643,7 +643,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </literal></term> <listitem> <para> - The <literal>CHECK</> clause specifies an expression producing a + The <literal>CHECK</literal> clause specifies an expression producing a Boolean result which new or updated rows must satisfy for an insert or update operation to succeed. Expressions evaluating to TRUE or UNKNOWN succeed. Should any row of an insert or @@ -662,15 +662,15 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - A constraint marked with <literal>NO INHERIT</> will not propagate to + A constraint marked with <literal>NO INHERIT</literal> will not propagate to child tables. </para> <para> When a table has multiple <literal>CHECK</literal> constraints, they will be tested for each row in alphabetical order by name, - after checking <literal>NOT NULL</> constraints. - (<productname>PostgreSQL</> versions before 9.5 did not honor any + after checking <literal>NOT NULL</literal> constraints. + (<productname>PostgreSQL</productname> versions before 9.5 did not honor any particular firing order for <literal>CHECK</literal> constraints.) </para> </listitem> @@ -681,7 +681,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <replaceable>default_expr</replaceable></literal></term> <listitem> <para> - The <literal>DEFAULT</> clause assigns a default data value for + The <literal>DEFAULT</literal> clause assigns a default data value for the column whose column definition it appears within. The value is any variable-free expression (subqueries and cross-references to other columns in the current table are not allowed). The @@ -729,8 +729,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>UNIQUE</> (column constraint)</term> - <term><literal>UNIQUE ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</> (table constraint)</term> + <term><literal>UNIQUE</literal> (column constraint)</term> + <term><literal>UNIQUE ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</literal> (table constraint)</term> <listitem> <para> @@ -756,11 +756,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>PRIMARY KEY</> (column constraint)</term> - <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</> (table constraint)</term> + <term><literal>PRIMARY KEY</literal> (column constraint)</term> + <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</literal> (table constraint)</term> <listitem> <para> - The <literal>PRIMARY KEY</> constraint specifies that a column or + The <literal>PRIMARY KEY</literal> constraint specifies that a column or columns of a table can contain only unique (non-duplicate), nonnull values. Only one primary key can be specified for a table, whether as a column constraint or a table constraint. @@ -775,7 +775,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> <literal>PRIMARY KEY</literal> enforces the same data constraints as - a combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but + a combination of <literal>UNIQUE</literal> and <literal>NOT NULL</literal>, but identifying a set of columns as the primary key also provides metadata about the design of the schema, since a primary key implies that other tables can rely on this set of columns as a unique identifier for rows. @@ -787,19 +787,19 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ]</literal></term> <listitem> <para> - The <literal>EXCLUDE</> clause defines an exclusion + The <literal>EXCLUDE</literal> clause defines an exclusion constraint, which guarantees that if any two rows are compared on the specified column(s) or expression(s) using the specified operator(s), not all of these - comparisons will return <literal>TRUE</>. If all of the + comparisons will return <literal>TRUE</literal>. If all of the specified operators test for equality, this is equivalent to a - <literal>UNIQUE</> constraint, although an ordinary unique constraint + <literal>UNIQUE</literal> constraint, although an ordinary unique constraint will be faster. However, exclusion constraints can specify constraints that are more general than simple equality. For example, you can specify a constraint that no two rows in the table contain overlapping circles (see <xref linkend="datatype-geometric">) by using the - <literal>&&</> operator. + <literal>&&</literal> operator. </para> <para> @@ -807,7 +807,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace an index, so each specified operator must be associated with an appropriate operator class (see <xref linkend="indexes-opclass">) for the index access - method <replaceable>index_method</>. + method <replaceable>index_method</replaceable>. The operators are required to be commutative. Each <replaceable class="parameter">exclude_element</replaceable> can optionally specify an operator class and/or ordering options; @@ -816,17 +816,17 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - The access method must support <literal>amgettuple</> (see <xref - linkend="indexam">); at present this means <acronym>GIN</> + The access method must support <literal>amgettuple</literal> (see <xref + linkend="indexam">); at present this means <acronym>GIN</acronym> cannot be used. Although it's allowed, there is little point in using B-tree or hash indexes with an exclusion constraint, because this does nothing that an ordinary unique constraint doesn't do better. - So in practice the access method will always be <acronym>GiST</> or - <acronym>SP-GiST</>. + So in practice the access method will always be <acronym>GiST</acronym> or + <acronym>SP-GiST</acronym>. </para> <para> - The <replaceable class="parameter">predicate</> allows you to specify an + The <replaceable class="parameter">predicate</replaceable> allows you to specify an exclusion constraint on a subset of the table; internally this creates a partial index. Note that parentheses are required around the predicate. </para> @@ -853,7 +853,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace primary key of the <replaceable class="parameter">reftable</replaceable> is used. The referenced columns must be the columns of a non-deferrable unique or primary key constraint in the referenced table. The user - must have <literal>REFERENCES</> permission on the referenced table + must have <literal>REFERENCES</literal> permission on the referenced table (either the whole table, or the specific referenced columns). Note that foreign key constraints cannot be defined between temporary tables and permanent tables. @@ -863,16 +863,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace A value inserted into the referencing column(s) is matched against the values of the referenced table and referenced columns using the given match type. There are three match types: <literal>MATCH - FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH + FULL</literal>, <literal>MATCH PARTIAL</literal>, and <literal>MATCH SIMPLE</literal> (which is the default). <literal>MATCH - FULL</> will not allow one column of a multicolumn foreign key + FULL</literal> will not allow one column of a multicolumn foreign key to be null unless all foreign key columns are null; if they are all null, the row is not required to have a match in the referenced table. <literal>MATCH SIMPLE</literal> allows any of the foreign key columns to be null; if any of them are null, the row is not required to have a match in the referenced table. - <literal>MATCH PARTIAL</> is not yet implemented. - (Of course, <literal>NOT NULL</> constraints can be applied to the + <literal>MATCH PARTIAL</literal> is not yet implemented. + (Of course, <literal>NOT NULL</literal> constraints can be applied to the referencing column(s) to prevent these cases from arising.) </para> @@ -969,13 +969,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace deferrable can be postponed until the end of the transaction (using the <xref linkend="sql-set-constraints"> command). <literal>NOT DEFERRABLE</literal> is the default. - Currently, only <literal>UNIQUE</>, <literal>PRIMARY KEY</>, - <literal>EXCLUDE</>, and - <literal>REFERENCES</> (foreign key) constraints accept this - clause. <literal>NOT NULL</> and <literal>CHECK</> constraints are not + Currently, only <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, + <literal>EXCLUDE</literal>, and + <literal>REFERENCES</literal> (foreign key) constraints accept this + clause. <literal>NOT NULL</literal> and <literal>CHECK</literal> constraints are not deferrable. Note that deferrable constraints cannot be used as conflict arbitrators in an <command>INSERT</command> statement that - includes an <literal>ON CONFLICT DO UPDATE</> clause. + includes an <literal>ON CONFLICT DO UPDATE</literal> clause. </para> </listitem> </varlistentry> @@ -1003,16 +1003,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace This clause specifies optional storage parameters for a table or index; see <xref linkend="sql-createtable-storage-parameters" endterm="sql-createtable-storage-parameters-title"> for more - information. The <literal>WITH</> clause for a - table can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>) + information. The <literal>WITH</literal> clause for a + table can also include <literal>OIDS=TRUE</literal> (or just <literal>OIDS</literal>) to specify that rows of the new table should have OIDs (object identifiers) assigned to them, or - <literal>OIDS=FALSE</> to specify that the rows should not have OIDs. - If <literal>OIDS</> is not specified, the default setting depends upon + <literal>OIDS=FALSE</literal> to specify that the rows should not have OIDs. + If <literal>OIDS</literal> is not specified, the default setting depends upon the <xref linkend="guc-default-with-oids"> configuration parameter. (If the new table inherits from any tables that have OIDs, then - <literal>OIDS=TRUE</> is forced even if the command says - <literal>OIDS=FALSE</>.) + <literal>OIDS=TRUE</literal> is forced even if the command says + <literal>OIDS=FALSE</literal>.) </para> <para> @@ -1035,14 +1035,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>WITH OIDS</></term> - <term><literal>WITHOUT OIDS</></term> + <term><literal>WITH OIDS</literal></term> + <term><literal>WITHOUT OIDS</literal></term> <listitem> <para> - These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</> - and <literal>WITH (OIDS=FALSE)</>, respectively. If you wish to give - both an <literal>OIDS</> setting and storage parameters, you must use - the <literal>WITH ( ... )</> syntax; see above. + These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</literal> + and <literal>WITH (OIDS=FALSE)</literal>, respectively. If you wish to give + both an <literal>OIDS</literal> setting and storage parameters, you must use + the <literal>WITH ( ... )</literal> syntax; see above. </para> </listitem> </varlistentry> @@ -1110,7 +1110,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> This clause allows selection of the tablespace in which the index associated with a <literal>UNIQUE</literal>, <literal>PRIMARY - KEY</literal>, or <literal>EXCLUDE</> constraint will be created. + KEY</literal>, or <literal>EXCLUDE</literal> constraint will be created. If not specified, <xref linkend="guc-default-tablespace"> is consulted, or <xref linkend="guc-temp-tablespaces"> if the table is temporary. @@ -1128,16 +1128,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </indexterm> <para> - The <literal>WITH</> clause can specify <firstterm>storage parameters</> + The <literal>WITH</literal> clause can specify <firstterm>storage parameters</firstterm> for tables, and for indexes associated with a <literal>UNIQUE</literal>, - <literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</> constraint. + <literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</literal> constraint. Storage parameters for indexes are documented in <xref linkend="SQL-CREATEINDEX">. The storage parameters currently available for tables are listed below. For many of these parameters, as shown, there is an additional parameter with the same name prefixed with <literal>toast.</literal>, which controls the behavior of the - table's secondary <acronym>TOAST</> table, if any + table's secondary <acronym>TOAST</acronym> table, if any (see <xref linkend="storage-toast"> for more information about TOAST). If a table parameter value is set and the equivalent <literal>toast.</literal> parameter is not, the TOAST table @@ -1149,14 +1149,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <variablelist> <varlistentry> - <term><literal>fillfactor</> (<type>integer</>)</term> + <term><literal>fillfactor</literal> (<type>integer</type>)</term> <listitem> <para> The fillfactor for a table is a percentage between 10 and 100. 100 (complete packing) is the default. When a smaller fillfactor - is specified, <command>INSERT</> operations pack table pages only + is specified, <command>INSERT</command> operations pack table pages only to the indicated percentage; the remaining space on each page is - reserved for updating rows on that page. This gives <command>UPDATE</> + reserved for updating rows on that page. This gives <command>UPDATE</command> a chance to place the updated copy of a row on the same page as the original, which is more efficient than placing it on a different page. For a table whose entries are never updated, complete packing is the @@ -1167,7 +1167,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>parallel_workers</> (<type>integer</>)</term> + <term><literal>parallel_workers</literal> (<type>integer</type>)</term> <listitem> <para> This sets the number of workers that should be used to assist a parallel @@ -1180,12 +1180,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_enabled</>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</>)</term> + <term><literal>autovacuum_enabled</literal>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</type>)</term> <listitem> <para> Enables or disables the autovacuum daemon for a particular table. - If true, the autovacuum daemon will perform automatic <command>VACUUM</> - and/or <command>ANALYZE</> operations on this table following the rules + If true, the autovacuum daemon will perform automatic <command>VACUUM</command> + and/or <command>ANALYZE</command> operations on this table following the rules discussed in <xref linkend="autovacuum">. If false, this table will not be autovacuumed, except to prevent transaction ID wraparound. See <xref linkend="vacuum-for-wraparound"> for @@ -1194,14 +1194,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace transaction ID wraparound) if the <xref linkend="guc-autovacuum"> parameter is false; setting individual tables' storage parameters does not override that. Therefore there is seldom much point in explicitly - setting this storage parameter to <literal>true</>, only - to <literal>false</>. + setting this storage parameter to <literal>true</literal>, only + to <literal>false</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_threshold</>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_threshold</literal>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-threshold"> @@ -1211,7 +1211,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_scale_factor</>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</>)</term> + <term><literal>autovacuum_vacuum_scale_factor</literal>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-scale-factor"> @@ -1221,7 +1221,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_analyze_threshold</> (<type>integer</>)</term> + <term><literal>autovacuum_analyze_threshold</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-analyze-threshold"> @@ -1231,7 +1231,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_analyze_scale_factor</> (<type>float4</>)</term> + <term><literal>autovacuum_analyze_scale_factor</literal> (<type>float4</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-analyze-scale-factor"> @@ -1241,7 +1241,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_cost_delay</>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_cost_delay</literal>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-delay"> @@ -1251,7 +1251,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_cost_limit</>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_cost_limit</literal>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-limit"> @@ -1261,12 +1261,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_freeze_min_age</>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</>)</term> + <term><literal>autovacuum_freeze_min_age</literal>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-vacuum-freeze-min-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_freeze_min_age</> parameters that are + per-table <literal>autovacuum_freeze_min_age</literal> parameters that are larger than half the system-wide <xref linkend="guc-autovacuum-freeze-max-age"> setting. </para> @@ -1274,12 +1274,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_freeze_max_age</>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</>)</term> + <term><literal>autovacuum_freeze_max_age</literal>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-freeze-max-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_freeze_max_age</> parameters that are + per-table <literal>autovacuum_freeze_max_age</literal> parameters that are larger than the system-wide setting (it can only be set smaller). </para> </listitem> @@ -1301,7 +1301,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> Per-table value for <xref linkend="guc-vacuum-multixact-freeze-min-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_multixact_freeze_min_age</> parameters + per-table <literal>autovacuum_multixact_freeze_min_age</literal> parameters that are larger than half the system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age"> setting. @@ -1316,7 +1316,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace Per-table value for <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_multixact_freeze_max_age</> parameters + per-table <literal>autovacuum_multixact_freeze_max_age</literal> parameters that are larger than the system-wide setting (it can only be set smaller). </para> @@ -1369,11 +1369,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace generator as the table's primary key is preferred. However, if your application does make use of OIDs to identify specific rows of a table, it is recommended to create a unique constraint - on the <structfield>oid</> column of that table, to ensure that + on the <structfield>oid</structfield> column of that table, to ensure that OIDs in the table will indeed uniquely identify rows even after counter wraparound. Avoid assuming that OIDs are unique across tables; if you need a database-wide unique identifier, use the - combination of <structfield>tableoid</> and row OID for the + combination of <structfield>tableoid</structfield> and row OID for the purpose. </para> @@ -1411,8 +1411,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <title>Examples</title> <para> - Create table <structname>films</> and table - <structname>distributors</>: + Create table <structname>films</structname> and table + <structname>distributors</structname>: <programlisting> CREATE TABLE films ( @@ -1484,7 +1484,7 @@ CREATE TABLE distributors ( <para> Define a primary key table constraint for the table - <structname>films</>: + <structname>films</structname>: <programlisting> CREATE TABLE films ( @@ -1501,7 +1501,7 @@ CREATE TABLE films ( <para> Define a primary key constraint for table - <structname>distributors</>. The following two examples are + <structname>distributors</structname>. The following two examples are equivalent, the first using the table constraint syntax, the second the column constraint syntax: @@ -1537,7 +1537,7 @@ CREATE TABLE distributors ( </para> <para> - Define two <literal>NOT NULL</> column constraints on the table + Define two <literal>NOT NULL</literal> column constraints on the table <classname>distributors</classname>, one of which is explicitly given a name: @@ -1585,7 +1585,7 @@ WITH (fillfactor=70); </para> <para> - Create table <structname>circles</> with an exclusion + Create table <structname>circles</structname> with an exclusion constraint that prevents any two circles from overlapping: <programlisting> @@ -1597,7 +1597,7 @@ CREATE TABLE circles ( </para> <para> - Create table <structname>cinemas</> in tablespace <structname>diskvol1</>: + Create table <structname>cinemas</structname> in tablespace <structname>diskvol1</structname>: <programlisting> CREATE TABLE cinemas ( @@ -1761,8 +1761,8 @@ CREATE TABLE cities_partdef <para> The <literal>ON COMMIT</literal> clause for temporary tables also resembles the SQL standard, but has some differences. - If the <literal>ON COMMIT</> clause is omitted, SQL specifies that the - default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the + If the <literal>ON COMMIT</literal> clause is omitted, SQL specifies that the + default behavior is <literal>ON COMMIT DELETE ROWS</literal>. However, the default behavior in <productname>PostgreSQL</productname> is <literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT DROP</literal> option does not exist in SQL. @@ -1773,15 +1773,15 @@ CREATE TABLE cities_partdef <title>Non-deferred Uniqueness Constraints</title> <para> - When a <literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint is + When a <literal>UNIQUE</literal> or <literal>PRIMARY KEY</literal> constraint is not deferrable, <productname>PostgreSQL</productname> checks for uniqueness immediately whenever a row is inserted or modified. The SQL standard says that uniqueness should be enforced only at the end of the statement; this makes a difference when, for example, a single command updates multiple key values. To obtain standard-compliant behavior, declare the constraint as - <literal>DEFERRABLE</> but not deferred (i.e., <literal>INITIALLY - IMMEDIATE</>). Be aware that this can be significantly slower than + <literal>DEFERRABLE</literal> but not deferred (i.e., <literal>INITIALLY + IMMEDIATE</literal>). Be aware that this can be significantly slower than immediate uniqueness checking. </para> </refsect2> @@ -1790,8 +1790,8 @@ CREATE TABLE cities_partdef <title>Column Check Constraints</title> <para> - The SQL standard says that <literal>CHECK</> column constraints - can only refer to the column they apply to; only <literal>CHECK</> + The SQL standard says that <literal>CHECK</literal> column constraints + can only refer to the column they apply to; only <literal>CHECK</literal> table constraints can refer to multiple columns. <productname>PostgreSQL</productname> does not enforce this restriction; it treats column and table check constraints alike. @@ -1802,7 +1802,7 @@ CREATE TABLE cities_partdef <title><literal>EXCLUDE</literal> Constraint</title> <para> - The <literal>EXCLUDE</> constraint type is a + The <literal>EXCLUDE</literal> constraint type is a <productname>PostgreSQL</productname> extension. </para> </refsect2> @@ -1811,7 +1811,7 @@ CREATE TABLE cities_partdef <title><literal>NULL</literal> <quote>Constraint</quote></title> <para> - The <literal>NULL</> <quote>constraint</quote> (actually a + The <literal>NULL</literal> <quote>constraint</quote> (actually a non-constraint) is a <productname>PostgreSQL</productname> extension to the SQL standard that is included for compatibility with some other database systems (and for symmetry with the <literal>NOT @@ -1838,11 +1838,11 @@ CREATE TABLE cities_partdef <para> <productname>PostgreSQL</productname> allows a table of no columns - to be created (for example, <literal>CREATE TABLE foo();</>). This + to be created (for example, <literal>CREATE TABLE foo();</literal>). This is an extension from the SQL standard, which does not allow zero-column tables. Zero-column tables are not in themselves very useful, but disallowing them creates odd special cases for <command>ALTER TABLE - DROP COLUMN</>, so it seems cleaner to ignore this spec restriction. + DROP COLUMN</command>, so it seems cleaner to ignore this spec restriction. </para> </refsect2> @@ -1861,10 +1861,10 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>LIKE</> Clause</title> + <title><literal>LIKE</literal> Clause</title> <para> - While a <literal>LIKE</> clause exists in the SQL standard, many of the + While a <literal>LIKE</literal> clause exists in the SQL standard, many of the options that <productname>PostgreSQL</productname> accepts for it are not in the standard, and some of the standard's options are not implemented by <productname>PostgreSQL</productname>. @@ -1872,10 +1872,10 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>WITH</> Clause</title> + <title><literal>WITH</literal> Clause</title> <para> - The <literal>WITH</> clause is a <productname>PostgreSQL</productname> + The <literal>WITH</literal> clause is a <productname>PostgreSQL</productname> extension; neither storage parameters nor OIDs are in the standard. </para> </refsect2> @@ -1904,19 +1904,19 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>PARTITION BY</> Clause</title> + <title><literal>PARTITION BY</literal> Clause</title> <para> - The <literal>PARTITION BY</> clause is a + The <literal>PARTITION BY</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </refsect2> <refsect2> - <title><literal>PARTITION OF</> Clause</title> + <title><literal>PARTITION OF</literal> Clause</title> <para> - The <literal>PARTITION OF</> clause is a + The <literal>PARTITION OF</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </refsect2> diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 0fa28a11fa7..8198442a974 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -71,7 +71,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI <variablelist> <varlistentry> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the table is created as a temporary table. @@ -81,7 +81,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </varlistentry> <varlistentry> - <term><literal>UNLOGGED</></term> + <term><literal>UNLOGGED</literal></term> <listitem> <para> If specified, the table is created as an unlogged table. @@ -91,7 +91,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </varlistentry> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -127,25 +127,25 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI This clause specifies optional storage parameters for the new table; see <xref linkend="sql-createtable-storage-parameters" endterm="sql-createtable-storage-parameters-title"> for more - information. The <literal>WITH</> clause - can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>) + information. The <literal>WITH</literal> clause + can also include <literal>OIDS=TRUE</literal> (or just <literal>OIDS</literal>) to specify that rows of the new table should have OIDs (object identifiers) assigned to them, or - <literal>OIDS=FALSE</> to specify that the rows should not have OIDs. + <literal>OIDS=FALSE</literal> to specify that the rows should not have OIDs. See <xref linkend="sql-createtable"> for more information. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>WITH OIDS</></term> - <term><literal>WITHOUT OIDS</></term> + <term><literal>WITH OIDS</literal></term> + <term><literal>WITHOUT OIDS</literal></term> <listitem> <para> - These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</> - and <literal>WITH (OIDS=FALSE)</>, respectively. If you wish to give - both an <literal>OIDS</> setting and storage parameters, you must use - the <literal>WITH ( ... )</> syntax; see above. + These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</literal> + and <literal>WITH (OIDS=FALSE)</literal>, respectively. If you wish to give + both an <literal>OIDS</literal> setting and storage parameters, you must use + the <literal>WITH ( ... )</literal> syntax; see above. </para> </listitem> </varlistentry> @@ -214,14 +214,14 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI A <xref linkend="sql-select">, <link linkend="sql-table">TABLE</link>, or <xref linkend="sql-values"> command, or an <xref linkend="sql-execute"> command that runs a - prepared <command>SELECT</>, <command>TABLE</>, or - <command>VALUES</> query. + prepared <command>SELECT</command>, <command>TABLE</command>, or + <command>VALUES</command> query. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>WITH [ NO ] DATA</></term> + <term><literal>WITH [ NO ] DATA</literal></term> <listitem> <para> This clause specifies whether or not the data produced by the query @@ -241,7 +241,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI This command is functionally similar to <xref linkend="sql-selectinto">, but it is preferred since it is less likely to be confused with other uses of - the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE + the <command>SELECT INTO</command> syntax. Furthermore, <command>CREATE TABLE AS</command> offers a superset of the functionality offered by <command>SELECT INTO</command>. </para> @@ -315,7 +315,7 @@ CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS </listitem> <listitem> - <para><productname>PostgreSQL</> handles temporary tables in a way + <para><productname>PostgreSQL</productname> handles temporary tables in a way rather different from the standard; see <xref linkend="sql-createtable"> for details. @@ -324,7 +324,7 @@ CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS <listitem> <para> - The <literal>WITH</> clause is a <productname>PostgreSQL</productname> + The <literal>WITH</literal> clause is a <productname>PostgreSQL</productname> extension; neither storage parameters nor OIDs are in the standard. </para> </listitem> diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml index 2fed29ffaf3..4d95cac9e59 100644 --- a/doc/src/sgml/ref/create_tablespace.sgml +++ b/doc/src/sgml/ref/create_tablespace.sgml @@ -45,9 +45,9 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <para> A user with appropriate privileges can pass - <replaceable class="parameter">tablespace_name</> to - <command>CREATE DATABASE</>, <command>CREATE TABLE</>, - <command>CREATE INDEX</> or <command>ADD CONSTRAINT</> to have the data + <replaceable class="parameter">tablespace_name</replaceable> to + <command>CREATE DATABASE</command>, <command>CREATE TABLE</command>, + <command>CREATE INDEX</command> or <command>ADD CONSTRAINT</command> to have the data files for these objects stored within the specified tablespace. </para> @@ -93,7 +93,7 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <para> The directory that will be used for the tablespace. The directory should be empty and must be owned by the - <productname>PostgreSQL</> system user. The directory must be + <productname>PostgreSQL</productname> system user. The directory must be specified by an absolute path name. </para> </listitem> @@ -104,8 +104,8 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <listitem> <para> A tablespace parameter to be set or reset. Currently, the only - available parameters are <varname>seq_page_cost</>, - <varname>random_page_cost</> and <varname>effective_io_concurrency</>. + available parameters are <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname> and <varname>effective_io_concurrency</varname>. Setting either value for a particular tablespace will override the planner's usual estimate of the cost of reading pages from tables in that tablespace, as established by the configuration parameters of the @@ -128,7 +128,7 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> </para> <para> - <command>CREATE TABLESPACE</> cannot be executed inside a transaction + <command>CREATE TABLESPACE</command> cannot be executed inside a transaction block. </para> </refsect1> @@ -137,15 +137,15 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <title>Examples</title> <para> - Create a tablespace <literal>dbspace</> at <literal>/data/dbs</>: + Create a tablespace <literal>dbspace</literal> at <literal>/data/dbs</literal>: <programlisting> CREATE TABLESPACE dbspace LOCATION '/data/dbs'; </programlisting> </para> <para> - Create a tablespace <literal>indexspace</> at <literal>/data/indexes</> - owned by user <literal>genevieve</>: + Create a tablespace <literal>indexspace</literal> at <literal>/data/indexes</literal> + owned by user <literal>genevieve</literal>: <programlisting> CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; </programlisting></para> @@ -155,7 +155,7 @@ CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; <title>Compatibility</title> <para> - <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</> + <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 7fc481d9fcc..6726e3c7663 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -86,10 +86,10 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </para> <para> - Triggers that are specified to fire <literal>INSTEAD OF</> the trigger - event must be marked <literal>FOR EACH ROW</>, and can only be defined - on views. <literal>BEFORE</> and <literal>AFTER</> triggers on a view - must be marked as <literal>FOR EACH STATEMENT</>. + Triggers that are specified to fire <literal>INSTEAD OF</literal> the trigger + event must be marked <literal>FOR EACH ROW</literal>, and can only be defined + on views. <literal>BEFORE</literal> and <literal>AFTER</literal> triggers on a view + must be marked as <literal>FOR EACH STATEMENT</literal>. </para> <para> @@ -115,35 +115,35 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </thead> <tbody> <row> - <entry align="center" morerows="1"><literal>BEFORE</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>BEFORE</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Tables and foreign tables</entry> <entry align="center">Tables, views, and foreign tables</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">Tables</entry> </row> <row> - <entry align="center" morerows="1"><literal>AFTER</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>AFTER</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Tables and foreign tables</entry> <entry align="center">Tables, views, and foreign tables</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">Tables</entry> </row> <row> - <entry align="center" morerows="1"><literal>INSTEAD OF</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>INSTEAD OF</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Views</entry> <entry align="center">—</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">—</entry> </row> @@ -152,11 +152,11 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </informaltable> <para> - Also, a trigger definition can specify a Boolean <literal>WHEN</> + Also, a trigger definition can specify a Boolean <literal>WHEN</literal> condition, which will be tested to see whether the trigger should - be fired. In row-level triggers the <literal>WHEN</> condition can + be fired. In row-level triggers the <literal>WHEN</literal> condition can examine the old and/or new values of columns of the row. Statement-level - triggers can also have <literal>WHEN</> conditions, although the feature + triggers can also have <literal>WHEN</literal> conditions, although the feature is not so useful for them since the condition cannot refer to any values in the table. </para> @@ -167,36 +167,36 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </para> <para> - When the <literal>CONSTRAINT</> option is specified, this command creates a - <firstterm>constraint trigger</>. This is the same as a regular trigger + When the <literal>CONSTRAINT</literal> option is specified, this command creates a + <firstterm>constraint trigger</firstterm>. This is the same as a regular trigger except that the timing of the trigger firing can be adjusted using <xref linkend="SQL-SET-CONSTRAINTS">. - Constraint triggers must be <literal>AFTER ROW</> triggers on plain + Constraint triggers must be <literal>AFTER ROW</literal> triggers on plain tables (not foreign tables). They can be fired either at the end of the statement causing the triggering event, or at the end of the containing transaction; in the latter case they - are said to be <firstterm>deferred</>. A pending deferred-trigger firing + are said to be <firstterm>deferred</firstterm>. A pending deferred-trigger firing can also be forced to happen immediately by using <command>SET - CONSTRAINTS</>. Constraint triggers are expected to raise an exception + CONSTRAINTS</command>. Constraint triggers are expected to raise an exception when the constraints they implement are violated. </para> <para> - The <literal>REFERENCING</> option enables collection - of <firstterm>transition relations</>, which are row sets that include all + The <literal>REFERENCING</literal> option enables collection + of <firstterm>transition relations</firstterm>, which are row sets that include all of the rows inserted, deleted, or modified by the current SQL statement. This feature lets the trigger see a global view of what the statement did, not just one row at a time. This option is only allowed for - an <literal>AFTER</> trigger that is not a constraint trigger; also, if - the trigger is an <literal>UPDATE</> trigger, it must not specify + an <literal>AFTER</literal> trigger that is not a constraint trigger; also, if + the trigger is an <literal>UPDATE</literal> trigger, it must not specify a <replaceable class="parameter">column_name</replaceable> list. - <literal>OLD TABLE</> may only be specified once, and only for a trigger - that can fire on <literal>UPDATE</> or <literal>DELETE</>; it creates a - transition relation containing the <firstterm>before-images</> of all rows + <literal>OLD TABLE</literal> may only be specified once, and only for a trigger + that can fire on <literal>UPDATE</literal> or <literal>DELETE</literal>; it creates a + transition relation containing the <firstterm>before-images</firstterm> of all rows updated or deleted by the statement. - Similarly, <literal>NEW TABLE</> may only be specified once, and only for - a trigger that can fire on <literal>UPDATE</> or <literal>INSERT</>; - it creates a transition relation containing the <firstterm>after-images</> + Similarly, <literal>NEW TABLE</literal> may only be specified once, and only for + a trigger that can fire on <literal>UPDATE</literal> or <literal>INSERT</literal>; + it creates a transition relation containing the <firstterm>after-images</firstterm> of all rows updated or inserted by the statement. </para> @@ -225,7 +225,7 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> The name cannot be schema-qualified — the trigger inherits the schema of its table. For a constraint trigger, this is also the name to use when modifying the trigger's behavior using - <command>SET CONSTRAINTS</>. + <command>SET CONSTRAINTS</command>. </para> </listitem> </varlistentry> @@ -238,7 +238,7 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> <para> Determines whether the function is called before, after, or instead of the event. A constraint trigger can only be specified as - <literal>AFTER</>. + <literal>AFTER</literal>. </para> </listitem> </varlistentry> @@ -261,11 +261,11 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</replaceable> ... ] </synopsis> The trigger will only fire if at least one of the listed columns - is mentioned as a target of the <command>UPDATE</> command. + is mentioned as a target of the <command>UPDATE</command> command. </para> <para> - <literal>INSTEAD OF UPDATE</> events do not allow a list of columns. + <literal>INSTEAD OF UPDATE</literal> events do not allow a list of columns. A column list cannot be specified when requesting transition relations, either. </para> @@ -352,7 +352,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ once for every row affected by the trigger event, or just once per SQL statement. If neither is specified, <literal>FOR EACH STATEMENT</literal> is the default. Constraint triggers can only - be specified <literal>FOR EACH ROW</>. + be specified <literal>FOR EACH ROW</literal>. </para> </listitem> </varlistentry> @@ -362,20 +362,20 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <listitem> <para> A Boolean expression that determines whether the trigger function - will actually be executed. If <literal>WHEN</> is specified, the + will actually be executed. If <literal>WHEN</literal> is specified, the function will only be called if the <replaceable - class="parameter">condition</replaceable> returns <literal>true</>. - In <literal>FOR EACH ROW</literal> triggers, the <literal>WHEN</> + class="parameter">condition</replaceable> returns <literal>true</literal>. + In <literal>FOR EACH ROW</literal> triggers, the <literal>WHEN</literal> condition can refer to columns of the old and/or new row values by writing <literal>OLD.<replaceable class="parameter">column_name</replaceable></literal> or <literal>NEW.<replaceable class="parameter">column_name</replaceable></literal> respectively. - Of course, <literal>INSERT</> triggers cannot refer to <literal>OLD</> - and <literal>DELETE</> triggers cannot refer to <literal>NEW</>. + Of course, <literal>INSERT</literal> triggers cannot refer to <literal>OLD</literal> + and <literal>DELETE</literal> triggers cannot refer to <literal>NEW</literal>. </para> - <para><literal>INSTEAD OF</> triggers do not support <literal>WHEN</> + <para><literal>INSTEAD OF</literal> triggers do not support <literal>WHEN</literal> conditions. </para> @@ -385,7 +385,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ </para> <para> - Note that for constraint triggers, evaluation of the <literal>WHEN</> + Note that for constraint triggers, evaluation of the <literal>WHEN</literal> condition is not deferred, but occurs immediately after the row update operation is performed. If the condition does not evaluate to true then the trigger is not queued for deferred execution. @@ -398,7 +398,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <listitem> <para> A user-supplied function that is declared as taking no arguments - and returning type <literal>trigger</>, which is executed when + and returning type <literal>trigger</literal>, which is executed when the trigger fires. </para> </listitem> @@ -438,32 +438,32 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> A column-specific trigger (one defined using the <literal>UPDATE OF <replaceable>column_name</replaceable></literal> syntax) will fire when any - of its columns are listed as targets in the <command>UPDATE</> - command's <literal>SET</> list. It is possible for a column's value + of its columns are listed as targets in the <command>UPDATE</command> + command's <literal>SET</literal> list. It is possible for a column's value to change even when the trigger is not fired, because changes made to the - row's contents by <literal>BEFORE UPDATE</> triggers are not considered. - Conversely, a command such as <literal>UPDATE ... SET x = x ...</> - will fire a trigger on column <literal>x</>, even though the column's + row's contents by <literal>BEFORE UPDATE</literal> triggers are not considered. + Conversely, a command such as <literal>UPDATE ... SET x = x ...</literal> + will fire a trigger on column <literal>x</literal>, even though the column's value did not change. </para> <para> - In a <literal>BEFORE</> trigger, the <literal>WHEN</> condition is + In a <literal>BEFORE</literal> trigger, the <literal>WHEN</literal> condition is evaluated just before the function is or would be executed, so using - <literal>WHEN</> is not materially different from testing the same + <literal>WHEN</literal> is not materially different from testing the same condition at the beginning of the trigger function. Note in particular - that the <literal>NEW</> row seen by the condition is the current value, - as possibly modified by earlier triggers. Also, a <literal>BEFORE</> - trigger's <literal>WHEN</> condition is not allowed to examine the - system columns of the <literal>NEW</> row (such as <literal>oid</>), + that the <literal>NEW</literal> row seen by the condition is the current value, + as possibly modified by earlier triggers. Also, a <literal>BEFORE</literal> + trigger's <literal>WHEN</literal> condition is not allowed to examine the + system columns of the <literal>NEW</literal> row (such as <literal>oid</literal>), because those won't have been set yet. </para> <para> - In an <literal>AFTER</> trigger, the <literal>WHEN</> condition is + In an <literal>AFTER</literal> trigger, the <literal>WHEN</literal> condition is evaluated just after the row update occurs, and it determines whether an event is queued to fire the trigger at the end of statement. So when an - <literal>AFTER</> trigger's <literal>WHEN</> condition does not return + <literal>AFTER</literal> trigger's <literal>WHEN</literal> condition does not return true, it is not necessary to queue an event nor to re-fetch the row at end of statement. This can result in significant speedups in statements that modify many rows, if the trigger only needs to be fired for a few of the @@ -473,7 +473,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> In some cases it is possible for a single SQL command to fire more than one kind of trigger. For instance an <command>INSERT</command> with - an <literal>ON CONFLICT DO UPDATE</> clause may cause both insert and + an <literal>ON CONFLICT DO UPDATE</literal> clause may cause both insert and update operations, so it will fire both kinds of triggers as needed. The transition relations supplied to triggers are specific to their event type; thus an <command>INSERT</command> trigger @@ -483,14 +483,14 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> Row updates or deletions caused by foreign-key enforcement actions, such - as <literal>ON UPDATE CASCADE</> or <literal>ON DELETE SET NULL</>, are + as <literal>ON UPDATE CASCADE</literal> or <literal>ON DELETE SET NULL</literal>, are treated as part of the SQL command that caused them (note that such actions are never deferred). Relevant triggers on the affected table will be fired, so that this provides another way in which a SQL command might fire triggers not directly matching its type. In simple cases, triggers that request transition relations will see all changes caused in their table by a single original SQL command as a single transition relation. - However, there are cases in which the presence of an <literal>AFTER ROW</> + However, there are cases in which the presence of an <literal>AFTER ROW</literal> trigger that requests transition relations will cause the foreign-key enforcement actions triggered by a single SQL command to be split into multiple steps, each with its own transition relation(s). In such cases, @@ -516,10 +516,10 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> In <productname>PostgreSQL</productname> versions before 7.3, it was necessary to declare trigger functions as returning the placeholder - type <type>opaque</>, rather than <type>trigger</>. To support loading - of old dump files, <command>CREATE TRIGGER</> will accept a function - declared as returning <type>opaque</>, but it will issue a notice and - change the function's declared return type to <type>trigger</>. + type <type>opaque</type>, rather than <type>trigger</type>. To support loading + of old dump files, <command>CREATE TRIGGER</command> will accept a function + declared as returning <type>opaque</type>, but it will issue a notice and + change the function's declared return type to <type>trigger</type>. </para> </refsect1> @@ -527,8 +527,8 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <title>Examples</title> <para> - Execute the function <function>check_account_update</> whenever - a row of the table <literal>accounts</> is about to be updated: + Execute the function <function>check_account_update</function> whenever + a row of the table <literal>accounts</literal> is about to be updated: <programlisting> CREATE TRIGGER check_update @@ -537,8 +537,8 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - The same, but only execute the function if column <literal>balance</> - is specified as a target in the <command>UPDATE</> command: + The same, but only execute the function if column <literal>balance</literal> + is specified as a target in the <command>UPDATE</command> command: <programlisting> CREATE TRIGGER check_update @@ -547,7 +547,7 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - This form only executes the function if column <literal>balance</> + This form only executes the function if column <literal>balance</literal> has in fact changed value: <programlisting> @@ -558,7 +558,7 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - Call a function to log updates of <literal>accounts</>, but only if + Call a function to log updates of <literal>accounts</literal>, but only if something changed: <programlisting> @@ -569,7 +569,7 @@ CREATE TRIGGER log_update EXECUTE PROCEDURE log_account_update(); </programlisting> - Execute the function <function>view_insert_row</> for each row to insert + Execute the function <function>view_insert_row</function> for each row to insert rows into the tables underlying a view: <programlisting> @@ -579,8 +579,8 @@ CREATE TRIGGER view_insert EXECUTE PROCEDURE view_insert_row(); </programlisting> - Execute the function <function>check_transfer_balances_to_zero</> for each - statement to confirm that the <literal>transfer</> rows offset to a net of + Execute the function <function>check_transfer_balances_to_zero</function> for each + statement to confirm that the <literal>transfer</literal> rows offset to a net of zero: <programlisting> @@ -591,7 +591,7 @@ CREATE TRIGGER transfer_insert EXECUTE PROCEDURE check_transfer_balances_to_zero(); </programlisting> - Execute the function <function>check_matching_pairs</> for each row to + Execute the function <function>check_matching_pairs</function> for each row to confirm that changes are made to matching pairs at the same time (by the same statement): @@ -624,27 +624,27 @@ CREATE TRIGGER paired_items_update <para> The <command>CREATE TRIGGER</command> statement in <productname>PostgreSQL</productname> implements a subset of the - <acronym>SQL</> standard. The following functionalities are currently + <acronym>SQL</acronym> standard. The following functionalities are currently missing: <itemizedlist> <listitem> <para> - While transition table names for <literal>AFTER</> triggers are - specified using the <literal>REFERENCING</> clause in the standard way, - the row variables used in <literal>FOR EACH ROW</> triggers may not be - specified in a <literal>REFERENCING</> clause. They are available in a + While transition table names for <literal>AFTER</literal> triggers are + specified using the <literal>REFERENCING</literal> clause in the standard way, + the row variables used in <literal>FOR EACH ROW</literal> triggers may not be + specified in a <literal>REFERENCING</literal> clause. They are available in a manner that is dependent on the language in which the trigger function is written, but is fixed for any one language. Some languages - effectively behave as though there is a <literal>REFERENCING</> clause - containing <literal>OLD ROW AS OLD NEW ROW AS NEW</>. + effectively behave as though there is a <literal>REFERENCING</literal> clause + containing <literal>OLD ROW AS OLD NEW ROW AS NEW</literal>. </para> </listitem> <listitem> <para> The standard allows transition tables to be used with - column-specific <literal>UPDATE</> triggers, but then the set of rows + column-specific <literal>UPDATE</literal> triggers, but then the set of rows that should be visible in the transition tables depends on the trigger's column list. This is not currently implemented by <productname>PostgreSQL</productname>. @@ -673,7 +673,7 @@ CREATE TRIGGER paired_items_update <para> SQL specifies that <literal>BEFORE DELETE</literal> triggers on cascaded - deletes fire <emphasis>after</> the cascaded <literal>DELETE</> completes. + deletes fire <emphasis>after</emphasis> the cascaded <literal>DELETE</literal> completes. The <productname>PostgreSQL</productname> behavior is for <literal>BEFORE DELETE</literal> to always fire before the delete action, even a cascading one. This is considered more consistent. There is also nonstandard @@ -685,19 +685,19 @@ CREATE TRIGGER paired_items_update <para> The ability to specify multiple actions for a single trigger using - <literal>OR</literal> is a <productname>PostgreSQL</> extension of + <literal>OR</literal> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> <para> The ability to fire triggers for <command>TRUNCATE</command> is a - <productname>PostgreSQL</> extension of the SQL standard, as is the + <productname>PostgreSQL</productname> extension of the SQL standard, as is the ability to define statement-level triggers on views. </para> <para> <command>CREATE CONSTRAINT TRIGGER</command> is a - <productname>PostgreSQL</productname> extension of the <acronym>SQL</> + <productname>PostgreSQL</productname> extension of the <acronym>SQL</acronym> standard. </para> diff --git a/doc/src/sgml/ref/create_tsconfig.sgml b/doc/src/sgml/ref/create_tsconfig.sgml index 63321520df2..d1792e5d29d 100644 --- a/doc/src/sgml/ref/create_tsconfig.sgml +++ b/doc/src/sgml/ref/create_tsconfig.sgml @@ -99,7 +99,7 @@ CREATE TEXT SEARCH CONFIGURATION <replaceable class="parameter">name</replaceabl <title>Notes</title> <para> - The <literal>PARSER</> and <literal>COPY</> options are mutually + The <literal>PARSER</literal> and <literal>COPY</literal> options are mutually exclusive, because when an existing configuration is copied, its parser selection is copied too. </para> diff --git a/doc/src/sgml/ref/create_tstemplate.sgml b/doc/src/sgml/ref/create_tstemplate.sgml index 360ad41f354..e10f18b28b8 100644 --- a/doc/src/sgml/ref/create_tstemplate.sgml +++ b/doc/src/sgml/ref/create_tstemplate.sgml @@ -49,7 +49,7 @@ CREATE TEXT SEARCH TEMPLATE <replaceable class="parameter">name</replaceable> ( TEMPLATE</command>. This restriction is made because an erroneous text search template definition could confuse or even crash the server. The reason for separating templates from dictionaries is that a template - encapsulates the <quote>unsafe</> aspects of defining a dictionary. + encapsulates the <quote>unsafe</quote> aspects of defining a dictionary. The parameters that can be set when defining a dictionary are safe for unprivileged users to set, and so creating a dictionary need not be a privileged operation. diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 312bd050bc3..02ca27b281e 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -81,8 +81,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> There are five forms of <command>CREATE TYPE</command>, as shown in the syntax synopsis above. They respectively create a <firstterm>composite - type</>, an <firstterm>enum type</>, a <firstterm>range type</>, a - <firstterm>base type</>, or a <firstterm>shell type</>. The first four + type</firstterm>, an <firstterm>enum type</firstterm>, a <firstterm>range type</firstterm>, a + <firstterm>base type</firstterm>, or a <firstterm>shell type</firstterm>. The first four of these are discussed in turn below. A shell type is simply a placeholder for a type to be defined later; it is created by issuing <command>CREATE TYPE</command> with no parameters except for the type name. Shell types @@ -154,7 +154,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> declared. To do this, you must first create a shell type, which is a placeholder type that has no properties except a name and an owner. This is done by issuing the command <literal>CREATE TYPE - <replaceable>name</></literal>, with no additional parameters. Then + <replaceable>name</replaceable></literal>, with no additional parameters. Then the function can be declared using the shell type as argument and result, and finally the range type can be declared using the same name. This automatically replaces the shell type entry with a valid range type. @@ -211,7 +211,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> The first argument is the input text as a C string, the second argument is the type's own OID (except for array types, which instead receive their element type's OID), - and the third is the <literal>typmod</> of the destination column, if known + and the third is the <literal>typmod</literal> of the destination column, if known (-1 will be passed if not). The input function must return a value of the data type itself. Usually, an input function should be declared STRICT; if it is not, @@ -264,12 +264,12 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> You should at this point be wondering how the input and output functions can be declared to have results or arguments of the new type, when they have to be created before the new type can be created. The answer is that - the type should first be defined as a <firstterm>shell type</>, which is a + the type should first be defined as a <firstterm>shell type</firstterm>, which is a placeholder type that has no properties except a name and an owner. This is done by issuing the command <literal>CREATE TYPE - <replaceable>name</></literal>, with no additional parameters. Then the + <replaceable>name</replaceable></literal>, with no additional parameters. Then the C I/O functions can be defined referencing the shell type. Finally, - <command>CREATE TYPE</> with a full definition replaces the shell entry + <command>CREATE TYPE</command> with a full definition replaces the shell entry with a complete, valid type definition, after which the new type can be used normally. </para> @@ -279,23 +279,23 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">type_modifier_input_function</replaceable> and <replaceable class="parameter">type_modifier_output_function</replaceable> are needed if the type supports modifiers, that is optional constraints - attached to a type declaration, such as <literal>char(5)</> or - <literal>numeric(30,2)</>. <productname>PostgreSQL</productname> allows + attached to a type declaration, such as <literal>char(5)</literal> or + <literal>numeric(30,2)</literal>. <productname>PostgreSQL</productname> allows user-defined types to take one or more simple constants or identifiers as modifiers. However, this information must be capable of being packed into a single non-negative integer value for storage in the system catalogs. The <replaceable class="parameter">type_modifier_input_function</replaceable> - is passed the declared modifier(s) in the form of a <type>cstring</> + is passed the declared modifier(s) in the form of a <type>cstring</type> array. It must check the values for validity (throwing an error if they are wrong), and if they are correct, return a single non-negative - <type>integer</> value that will be stored as the column <quote>typmod</>. + <type>integer</type> value that will be stored as the column <quote>typmod</quote>. Type modifiers will be rejected if the type does not have a <replaceable class="parameter">type_modifier_input_function</replaceable>. The <replaceable class="parameter">type_modifier_output_function</replaceable> converts the internal integer typmod value back to the correct form for - user display. It must return a <type>cstring</> value that is the exact - string to append to the type name; for example <type>numeric</>'s - function might return <literal>(30,2)</>. + user display. It must return a <type>cstring</type> value that is the exact + string to append to the type name; for example <type>numeric</type>'s + function might return <literal>(30,2)</literal>. It is allowed to omit the <replaceable class="parameter">type_modifier_output_function</replaceable>, in which case the default display format is just the stored typmod integer @@ -305,14 +305,14 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> The optional <replaceable class="parameter">analyze_function</replaceable> performs type-specific statistics collection for columns of the data type. - By default, <command>ANALYZE</> will attempt to gather statistics using - the type's <quote>equals</> and <quote>less-than</> operators, if there + By default, <command>ANALYZE</command> will attempt to gather statistics using + the type's <quote>equals</quote> and <quote>less-than</quote> operators, if there is a default b-tree operator class for the type. For non-scalar types this behavior is likely to be unsuitable, so it can be overridden by specifying a custom analysis function. The analysis function must be - declared to take a single argument of type <type>internal</>, and return - a <type>boolean</> result. The detailed API for analysis functions appears - in <filename>src/include/commands/vacuum.h</>. + declared to take a single argument of type <type>internal</type>, and return + a <type>boolean</type> result. The detailed API for analysis functions appears + in <filename>src/include/commands/vacuum.h</filename>. </para> <para> @@ -327,7 +327,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> positive integer, or variable-length, indicated by setting <replaceable class="parameter">internallength</replaceable> to <literal>VARIABLE</literal>. (Internally, this is represented - by setting <literal>typlen</> to -1.) The internal representation of all + by setting <literal>typlen</literal> to -1.) The internal representation of all variable-length types must start with a 4-byte integer giving the total length of this value of the type. (Note that the length field is often encoded, as described in <xref linkend="storage-toast">; it's unwise @@ -338,7 +338,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> The optional flag <literal>PASSEDBYVALUE</literal> indicates that values of this data type are passed by value, rather than by reference. Types passed by value must be fixed-length, and their internal - representation cannot be larger than the size of the <type>Datum</> type + representation cannot be larger than the size of the <type>Datum</type> type (4 bytes on some machines, 8 bytes on others). </para> @@ -347,7 +347,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> specifies the storage alignment required for the data type. The allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries. Note that variable-length types must have an alignment of at least - 4, since they necessarily contain an <type>int4</> as their first component. + 4, since they necessarily contain an <type>int4</type> as their first component. </para> <para> @@ -372,12 +372,12 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> All <replaceable class="parameter">storage</replaceable> values other than <literal>plain</literal> imply that the functions of the data type - can handle values that have been <firstterm>toasted</>, as described + can handle values that have been <firstterm>toasted</firstterm>, as described in <xref linkend="storage-toast"> and <xref linkend="xtypes-toast">. The specific other value given merely determines the default TOAST storage strategy for columns of a toastable data type; users can pick other strategies for individual columns using <literal>ALTER TABLE - SET STORAGE</>. + SET STORAGE</literal>. </para> <para> @@ -389,9 +389,9 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">alignment</replaceable>, and <replaceable class="parameter">storage</replaceable> are copied from the named type. (It is possible, though usually undesirable, to override - some of these values by specifying them along with the <literal>LIKE</> + some of these values by specifying them along with the <literal>LIKE</literal> clause.) Specifying representation this way is especially useful when - the low-level implementation of the new type <quote>piggybacks</> on an + the low-level implementation of the new type <quote>piggybacks</quote> on an existing type in some fashion. </para> @@ -400,7 +400,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">preferred</replaceable> parameters can be used to help control which implicit cast will be applied in ambiguous situations. Each data type belongs to a category named by a single ASCII - character, and each type is either <quote>preferred</> or not within its + character, and each type is either <quote>preferred</quote> or not within its category. The parser will prefer casting to preferred types (but only from other types within the same category) when this rule is helpful in resolving overloaded functions or operators. For more details see <xref @@ -408,7 +408,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> other types, it is sufficient to leave these settings at the defaults. However, for a group of related types that have implicit casts, it is often helpful to mark them all as belonging to a category and select one or two - of the <quote>most general</> types as being preferred within the category. + of the <quote>most general</quote> types as being preferred within the category. The <replaceable class="parameter">category</replaceable> parameter is especially useful when adding a user-defined type to an existing built-in category, such as the numeric or string types. However, it is also @@ -426,7 +426,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> To indicate that a type is an array, specify the type of the array - elements using the <literal>ELEMENT</> key word. For example, to + elements using the <literal>ELEMENT</literal> key word. For example, to define an array of 4-byte integers (<type>int4</type>), specify <literal>ELEMENT = int4</literal>. More details about array types appear below. @@ -465,26 +465,26 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> so generated collides with an existing type name, the process is repeated until a non-colliding name is found.) This implicitly-created array type is variable length and uses the - built-in input and output functions <literal>array_in</> and - <literal>array_out</>. The array type tracks any changes in its + built-in input and output functions <literal>array_in</literal> and + <literal>array_out</literal>. The array type tracks any changes in its element type's owner or schema, and is dropped if the element type is. </para> <para> - You might reasonably ask why there is an <option>ELEMENT</> + You might reasonably ask why there is an <option>ELEMENT</option> option, if the system makes the correct array type automatically. - The only case where it's useful to use <option>ELEMENT</> is when you are + The only case where it's useful to use <option>ELEMENT</option> is when you are making a fixed-length type that happens to be internally an array of a number of identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan - to provide for the type as a whole. For example, type <type>point</> + to provide for the type as a whole. For example, type <type>point</type> is represented as just two floating-point numbers, which can be accessed - using <literal>point[0]</> and <literal>point[1]</>. + using <literal>point[0]</literal> and <literal>point[1]</literal>. Note that this facility only works for fixed-length types whose internal form is exactly a sequence of identical fixed-length fields. A subscriptable variable-length type must have the generalized internal representation - used by <literal>array_in</> and <literal>array_out</>. + used by <literal>array_in</literal> and <literal>array_out</literal>. For historical reasons (i.e., this is clearly wrong but it's far too late to change it), subscripting of fixed-length array types starts from zero, rather than from one as for variable-length arrays. @@ -697,7 +697,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">alignment</replaceable>, and <replaceable class="parameter">storage</replaceable> are copied from that type, unless overridden by explicit - specification elsewhere in this <command>CREATE TYPE</> command. + specification elsewhere in this <command>CREATE TYPE</command> command. </para> </listitem> </varlistentry> @@ -707,7 +707,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <listitem> <para> The category code (a single ASCII character) for this type. - The default is <literal>'U'</> for <quote>user-defined type</>. + The default is <literal>'U'</literal> for <quote>user-defined type</quote>. Other standard category codes can be found in <xref linkend="catalog-typcategory-table">. You may also choose other ASCII characters in order to create custom categories. @@ -779,7 +779,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> This is usually not an issue for the sorts of functions that are useful in a type definition. But you might want to think twice before designing a type - in a way that would require <quote>secret</> information to be used + in a way that would require <quote>secret</quote> information to be used while converting it to or from external form. </para> @@ -792,7 +792,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> this in case of maximum-length names or collisions with user type names that begin with underscore. Writing code that depends on this convention is therefore deprecated. Instead, use - <structname>pg_type</>.<structfield>typarray</> to locate the array type + <structname>pg_type</structname>.<structfield>typarray</structfield> to locate the array type associated with a given type. </para> @@ -807,7 +807,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> Before <productname>PostgreSQL</productname> version 8.2, the shell-type creation syntax - <literal>CREATE TYPE <replaceable>name</></literal> did not exist. + <literal>CREATE TYPE <replaceable>name</replaceable></literal> did not exist. The way to create a new base type was to create its input function first. In this approach, <productname>PostgreSQL</productname> will first see the name of the new data type as the return type of the input function. @@ -824,10 +824,10 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> In <productname>PostgreSQL</productname> versions before 7.3, it was customary to avoid creating a shell type at all, by replacing the functions' forward references to the type name with the placeholder - pseudo-type <type>opaque</>. The <type>cstring</> arguments and - results also had to be declared as <type>opaque</> before 7.3. To - support loading of old dump files, <command>CREATE TYPE</> will - accept I/O functions declared using <type>opaque</>, but it will issue + pseudo-type <type>opaque</type>. The <type>cstring</type> arguments and + results also had to be declared as <type>opaque</type> before 7.3. To + support loading of old dump files, <command>CREATE TYPE</command> will + accept I/O functions declared using <type>opaque</type>, but it will issue a notice and change the function declarations to use the correct types. </para> @@ -894,7 +894,7 @@ CREATE TABLE myboxes ( <para> If the internal structure of <type>box</type> were an array of four - <type>float4</> elements, we might instead use: + <type>float4</type> elements, we might instead use: <programlisting> CREATE TYPE box ( INTERNALLENGTH = 16, @@ -933,11 +933,11 @@ CREATE TABLE big_objs ( <para> The first form of the <command>CREATE TYPE</command> command, which - creates a composite type, conforms to the <acronym>SQL</> standard. + creates a composite type, conforms to the <acronym>SQL</acronym> standard. The other forms are <productname>PostgreSQL</productname> extensions. The <command>CREATE TYPE</command> statement in - the <acronym>SQL</> standard also defines other forms that are not - implemented in <productname>PostgreSQL</>. + the <acronym>SQL</acronym> standard also defines other forms that are not + implemented in <productname>PostgreSQL</productname>. </para> <para> diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index 480b6405e6b..500169da986 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -51,8 +51,8 @@ CREATE USER <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <command>CREATE USER</command> is now an alias for <xref linkend="sql-createrole">. The only difference is that when the command is spelled - <command>CREATE USER</command>, <literal>LOGIN</> is assumed - by default, whereas <literal>NOLOGIN</> is assumed when + <command>CREATE USER</command>, <literal>LOGIN</literal> is assumed + by default, whereas <literal>NOLOGIN</literal> is assumed when the command is spelled <command>CREATE ROLE</command>. </para> diff --git a/doc/src/sgml/ref/create_user_mapping.sgml b/doc/src/sgml/ref/create_user_mapping.sgml index d6f29c94893..10182e14266 100644 --- a/doc/src/sgml/ref/create_user_mapping.sgml +++ b/doc/src/sgml/ref/create_user_mapping.sgml @@ -41,7 +41,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <para> The owner of a foreign server can create user mappings for that server for any user. Also, a user can create a user mapping for - their own user name if <literal>USAGE</> privilege on the server has + their own user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -51,7 +51,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a mapping of the given user to the given foreign @@ -67,8 +67,8 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <listitem> <para> The name of an existing user that is mapped to foreign server. - <literal>CURRENT_USER</> and <literal>USER</> match the name of - the current user. When <literal>PUBLIC</> is specified, a + <literal>CURRENT_USER</literal> and <literal>USER</literal> match the name of + the current user. When <literal>PUBLIC</literal> is specified, a so-called public mapping is created that is used when no user-specific mapping is applicable. </para> @@ -103,7 +103,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <title>Examples</title> <para> - Create a user mapping for user <literal>bob</>, server <literal>foo</>: + Create a user mapping for user <literal>bob</literal>, server <literal>foo</literal>: <programlisting> CREATE USER MAPPING FOR bob SERVER foo OPTIONS (user 'bob', password 'secret'); </programlisting></para> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 695c7593120..c0dd0224955 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -48,7 +48,7 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class <para> If a schema name is given (for example, <literal>CREATE VIEW - myschema.myview ...</>) then the view is created in the specified + myschema.myview ...</literal>) then the view is created in the specified schema. Otherwise it is created in the current schema. Temporary views exist in a special schema, so a schema name cannot be given when creating a temporary view. The name of the view must be @@ -62,7 +62,7 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class <variablelist> <varlistentry> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the view is created as a temporary view. @@ -82,16 +82,16 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class </varlistentry> <varlistentry> - <term><literal>RECURSIVE</></term> + <term><literal>RECURSIVE</literal></term> <listitem> <para> Creates a recursive view. The syntax <synopsis> -CREATE RECURSIVE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> (<replaceable>column_names</>) AS SELECT <replaceable>...</>; +CREATE RECURSIVE VIEW [ <replaceable>schema</replaceable> . ] <replaceable>view_name</replaceable> (<replaceable>column_names</replaceable>) AS SELECT <replaceable>...</replaceable>; </synopsis> is equivalent to <synopsis> -CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECURSIVE <replaceable>view_name</> (<replaceable>column_names</>) AS (SELECT <replaceable>...</>) SELECT <replaceable>column_names</> FROM <replaceable>view_name</>; +CREATE VIEW [ <replaceable>schema</replaceable> . ] <replaceable>view_name</replaceable> AS WITH RECURSIVE <replaceable>view_name</replaceable> (<replaceable>column_names</replaceable>) AS (SELECT <replaceable>...</replaceable>) SELECT <replaceable>column_names</replaceable> FROM <replaceable>view_name</replaceable>; </synopsis> A view column name list must be specified for a recursive view. </para> @@ -129,9 +129,9 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <term><literal>check_option</literal> (<type>string</type>)</term> <listitem> <para> - This parameter may be either <literal>local</> or - <literal>cascaded</>, and is equivalent to specifying - <literal>WITH [ CASCADED | LOCAL ] CHECK OPTION</> (see below). + This parameter may be either <literal>local</literal> or + <literal>cascaded</literal>, and is equivalent to specifying + <literal>WITH [ CASCADED | LOCAL ] CHECK OPTION</literal> (see below). This option can be changed on existing views using <xref linkend="sql-alterview">. </para> @@ -175,12 +175,12 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <listitem> <para> This option controls the behavior of automatically updatable views. When - this option is specified, <command>INSERT</> and <command>UPDATE</> + this option is specified, <command>INSERT</command> and <command>UPDATE</command> commands on the view will be checked to ensure that new rows satisfy the view-defining condition (that is, the new rows are checked to ensure that they are visible through the view). If they are not, the update will be - rejected. If the <literal>CHECK OPTION</> is not specified, - <command>INSERT</> and <command>UPDATE</> commands on the view are + rejected. If the <literal>CHECK OPTION</literal> is not specified, + <command>INSERT</command> and <command>UPDATE</command> commands on the view are allowed to create rows that are not visible through the view. The following check options are supported: @@ -191,7 +191,7 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <para> New rows are only checked against the conditions defined directly in the view itself. Any conditions defined on underlying base views are - not checked (unless they also specify the <literal>CHECK OPTION</>). + not checked (unless they also specify the <literal>CHECK OPTION</literal>). </para> </listitem> </varlistentry> @@ -201,9 +201,9 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <listitem> <para> New rows are checked against the conditions of the view and all - underlying base views. If the <literal>CHECK OPTION</> is specified, - and neither <literal>LOCAL</> nor <literal>CASCADED</> is specified, - then <literal>CASCADED</> is assumed. + underlying base views. If the <literal>CHECK OPTION</literal> is specified, + and neither <literal>LOCAL</literal> nor <literal>CASCADED</literal> is specified, + then <literal>CASCADED</literal> is assumed. </para> </listitem> </varlistentry> @@ -211,26 +211,26 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR </para> <para> - The <literal>CHECK OPTION</> may not be used with <literal>RECURSIVE</> + The <literal>CHECK OPTION</literal> may not be used with <literal>RECURSIVE</literal> views. </para> <para> - Note that the <literal>CHECK OPTION</> is only supported on views that - are automatically updatable, and do not have <literal>INSTEAD OF</> - triggers or <literal>INSTEAD</> rules. If an automatically updatable - view is defined on top of a base view that has <literal>INSTEAD OF</> - triggers, then the <literal>LOCAL CHECK OPTION</> may be used to check + Note that the <literal>CHECK OPTION</literal> is only supported on views that + are automatically updatable, and do not have <literal>INSTEAD OF</literal> + triggers or <literal>INSTEAD</literal> rules. If an automatically updatable + view is defined on top of a base view that has <literal>INSTEAD OF</literal> + triggers, then the <literal>LOCAL CHECK OPTION</literal> may be used to check the conditions on the automatically updatable view, but the conditions - on the base view with <literal>INSTEAD OF</> triggers will not be + on the base view with <literal>INSTEAD OF</literal> triggers will not be checked (a cascaded check option will not cascade down to a trigger-updatable view, and any check options defined directly on a trigger-updatable view will be ignored). If the view or any of its base - relations has an <literal>INSTEAD</> rule that causes the - <command>INSERT</> or <command>UPDATE</> command to be rewritten, then + relations has an <literal>INSTEAD</literal> rule that causes the + <command>INSERT</command> or <command>UPDATE</command> command to be rewritten, then all check options will be ignored in the rewritten query, including any checks from automatically updatable views defined on top of the relation - with the <literal>INSTEAD</> rule. + with the <literal>INSTEAD</literal> rule. </para> </listitem> </varlistentry> @@ -251,8 +251,8 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <programlisting> CREATE VIEW vista AS SELECT 'Hello World'; </programlisting> - is bad form because the column name defaults to <literal>?column?</>; - also, the column data type defaults to <type>text</>, which might not + is bad form because the column name defaults to <literal>?column?</literal>; + also, the column data type defaults to <type>text</type>, which might not be what you wanted. Better style for a string literal in a view's result is something like: <programlisting> @@ -271,7 +271,7 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; </para> <para> - When <command>CREATE OR REPLACE VIEW</> is used on an + When <command>CREATE OR REPLACE VIEW</command> is used on an existing view, only the view's defining SELECT rule is changed. Other view properties, including ownership, permissions, and non-SELECT rules, remain unchanged. You must own the view @@ -287,30 +287,30 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; <para> Simple views are automatically updatable: the system will allow - <command>INSERT</>, <command>UPDATE</> and <command>DELETE</> statements + <command>INSERT</command>, <command>UPDATE</command> and <command>DELETE</command> statements to be used on the view in the same way as on a regular table. A view is automatically updatable if it satisfies all of the following conditions: <itemizedlist> <listitem> <para> - The view must have exactly one entry in its <literal>FROM</> list, + The view must have exactly one entry in its <literal>FROM</literal> list, which must be a table or another updatable view. </para> </listitem> <listitem> <para> - The view definition must not contain <literal>WITH</>, - <literal>DISTINCT</>, <literal>GROUP BY</>, <literal>HAVING</>, - <literal>LIMIT</>, or <literal>OFFSET</> clauses at the top level. + The view definition must not contain <literal>WITH</literal>, + <literal>DISTINCT</literal>, <literal>GROUP BY</literal>, <literal>HAVING</literal>, + <literal>LIMIT</literal>, or <literal>OFFSET</literal> clauses at the top level. </para> </listitem> <listitem> <para> - The view definition must not contain set operations (<literal>UNION</>, - <literal>INTERSECT</> or <literal>EXCEPT</>) at the top level. + The view definition must not contain set operations (<literal>UNION</literal>, + <literal>INTERSECT</literal> or <literal>EXCEPT</literal>) at the top level. </para> </listitem> @@ -327,42 +327,42 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; An automatically updatable view may contain a mix of updatable and non-updatable columns. A column is updatable if it is a simple reference to an updatable column of the underlying base relation; otherwise the - column is read-only, and an error will be raised if an <command>INSERT</> - or <command>UPDATE</> statement attempts to assign a value to it. + column is read-only, and an error will be raised if an <command>INSERT</command> + or <command>UPDATE</command> statement attempts to assign a value to it. </para> <para> If the view is automatically updatable the system will convert any - <command>INSERT</>, <command>UPDATE</> or <command>DELETE</> statement + <command>INSERT</command>, <command>UPDATE</command> or <command>DELETE</command> statement on the view into the corresponding statement on the underlying base - relation. <command>INSERT</> statements that have an <literal>ON - CONFLICT UPDATE</> clause are fully supported. + relation. <command>INSERT</command> statements that have an <literal>ON + CONFLICT UPDATE</literal> clause are fully supported. </para> <para> - If an automatically updatable view contains a <literal>WHERE</> + If an automatically updatable view contains a <literal>WHERE</literal> condition, the condition restricts which rows of the base relation are - available to be modified by <command>UPDATE</> and <command>DELETE</> - statements on the view. However, an <command>UPDATE</> is allowed to - change a row so that it no longer satisfies the <literal>WHERE</> + available to be modified by <command>UPDATE</command> and <command>DELETE</command> + statements on the view. However, an <command>UPDATE</command> is allowed to + change a row so that it no longer satisfies the <literal>WHERE</literal> condition, and thus is no longer visible through the view. Similarly, - an <command>INSERT</> command can potentially insert base-relation rows - that do not satisfy the <literal>WHERE</> condition and thus are not - visible through the view (<literal>ON CONFLICT UPDATE</> may + an <command>INSERT</command> command can potentially insert base-relation rows + that do not satisfy the <literal>WHERE</literal> condition and thus are not + visible through the view (<literal>ON CONFLICT UPDATE</literal> may similarly affect an existing row not visible through the view). - The <literal>CHECK OPTION</> may be used to prevent - <command>INSERT</> and <command>UPDATE</> commands from creating + The <literal>CHECK OPTION</literal> may be used to prevent + <command>INSERT</command> and <command>UPDATE</command> commands from creating such rows that are not visible through the view. </para> <para> If an automatically updatable view is marked with the - <literal>security_barrier</> property then all the view's <literal>WHERE</> + <literal>security_barrier</literal> property then all the view's <literal>WHERE</literal> conditions (and any conditions using operators which are marked as <literal>LEAKPROOF</literal>) will always be evaluated before any conditions that a user of the view has added. See <xref linkend="rules-privileges"> for full details. Note that, due to this, rows which are not ultimately returned (because they do not - pass the user's <literal>WHERE</> conditions) may still end up being locked. + pass the user's <literal>WHERE</literal> conditions) may still end up being locked. <command>EXPLAIN</command> can be used to see which conditions are applied at the relation level (and therefore do not lock rows) and which are not. @@ -372,7 +372,7 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; A more complex view that does not satisfy all these conditions is read-only by default: the system will not allow an insert, update, or delete on the view. You can get the effect of an updatable view by - creating <literal>INSTEAD OF</> triggers on the view, which must + creating <literal>INSTEAD OF</literal> triggers on the view, which must convert attempted inserts, etc. on the view into appropriate actions on other tables. For more information see <xref linkend="sql-createtrigger">. Another possibility is to create rules @@ -404,13 +404,13 @@ CREATE VIEW comedies AS WHERE kind = 'Comedy'; </programlisting> This will create a view containing the columns that are in the - <literal>film</> table at the time of view creation. Though - <literal>*</> was used to create the view, columns added later to + <literal>film</literal> table at the time of view creation. Though + <literal>*</literal> was used to create the view, columns added later to the table will not be part of the view. </para> <para> - Create a view with <literal>LOCAL CHECK OPTION</>: + Create a view with <literal>LOCAL CHECK OPTION</literal>: <programlisting> CREATE VIEW universal_comedies AS @@ -419,16 +419,16 @@ CREATE VIEW universal_comedies AS WHERE classification = 'U' WITH LOCAL CHECK OPTION; </programlisting> - This will create a view based on the <literal>comedies</> view, showing - only films with <literal>kind = 'Comedy'</> and - <literal>classification = 'U'</>. Any attempt to <command>INSERT</> or - <command>UPDATE</> a row in the view will be rejected if the new row - doesn't have <literal>classification = 'U'</>, but the film - <literal>kind</> will not be checked. + This will create a view based on the <literal>comedies</literal> view, showing + only films with <literal>kind = 'Comedy'</literal> and + <literal>classification = 'U'</literal>. Any attempt to <command>INSERT</command> or + <command>UPDATE</command> a row in the view will be rejected if the new row + doesn't have <literal>classification = 'U'</literal>, but the film + <literal>kind</literal> will not be checked. </para> <para> - Create a view with <literal>CASCADED CHECK OPTION</>: + Create a view with <literal>CASCADED CHECK OPTION</literal>: <programlisting> CREATE VIEW pg_comedies AS @@ -437,8 +437,8 @@ CREATE VIEW pg_comedies AS WHERE classification = 'PG' WITH CASCADED CHECK OPTION; </programlisting> - This will create a view that checks both the <literal>kind</> and - <literal>classification</> of new rows. + This will create a view that checks both the <literal>kind</literal> and + <literal>classification</literal> of new rows. </para> <para> @@ -454,10 +454,10 @@ CREATE VIEW comedies AS FROM films f WHERE f.kind = 'Comedy'; </programlisting> - This view will support <command>INSERT</>, <command>UPDATE</> and - <command>DELETE</>. All the columns from the <literal>films</> table will - be updatable, whereas the computed columns <literal>country</> and - <literal>avg_rating</> will be read-only. + This view will support <command>INSERT</command>, <command>UPDATE</command> and + <command>DELETE</command>. All the columns from the <literal>films</literal> table will + be updatable, whereas the computed columns <literal>country</literal> and + <literal>avg_rating</literal> will be read-only. </para> <para> @@ -469,7 +469,7 @@ UNION ALL SELECT n+1 FROM nums_1_100 WHERE n < 100; </programlisting> Notice that although the recursive view's name is schema-qualified in this - <command>CREATE</>, its internal self-reference is not schema-qualified. + <command>CREATE</command>, its internal self-reference is not schema-qualified. This is because the implicitly-created CTE's name cannot be schema-qualified. </para> @@ -482,7 +482,7 @@ UNION ALL <command>CREATE OR REPLACE VIEW</command> is a <productname>PostgreSQL</productname> language extension. So is the concept of a temporary view. - The <literal>WITH ( ... )</> clause is an extension as well. + The <literal>WITH ( ... )</literal> clause is an extension as well. </para> </refsect1> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 9fc4c16a810..0112d3a848f 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -86,8 +86,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-D <replaceable class="parameter">tablespace</replaceable></></term> - <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></></term> + <term><option>-D <replaceable class="parameter">tablespace</replaceable></option></term> + <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></option></term> <listitem> <para> Specifies the default tablespace for the database. (This name @@ -97,8 +97,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>createdb</application> generates @@ -108,8 +108,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-E <replaceable class="parameter">encoding</replaceable></></term> - <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></></term> + <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term> + <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term> <listitem> <para> Specifies the character encoding scheme to be used in this @@ -121,8 +121,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-l <replaceable class="parameter">locale</replaceable></></term> - <term><option>--locale=<replaceable class="parameter">locale</replaceable></></term> + <term><option>-l <replaceable class="parameter">locale</replaceable></option></term> + <term><option>--locale=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the locale to be used in this database. This is equivalent @@ -132,7 +132,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></></term> + <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the LC_COLLATE setting to be used in this database. @@ -141,7 +141,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></></term> + <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the LC_CTYPE setting to be used in this database. @@ -150,8 +150,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-O <replaceable class="parameter">owner</replaceable></></term> - <term><option>--owner=<replaceable class="parameter">owner</replaceable></></term> + <term><option>-O <replaceable class="parameter">owner</replaceable></option></term> + <term><option>--owner=<replaceable class="parameter">owner</replaceable></option></term> <listitem> <para> Specifies the database user who will own the new database. @@ -161,8 +161,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-T <replaceable class="parameter">template</replaceable></></term> - <term><option>--template=<replaceable class="parameter">template</replaceable></></term> + <term><option>-T <replaceable class="parameter">template</replaceable></option></term> + <term><option>--template=<replaceable class="parameter">template</replaceable></option></term> <listitem> <para> Specifies the template database from which to build this @@ -172,8 +172,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>createdb</application> version and exit. @@ -182,8 +182,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>createdb</application> command line @@ -209,8 +209,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -221,8 +221,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or the local Unix domain socket file @@ -232,8 +232,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -242,8 +242,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -257,8 +257,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>createdb</application> to prompt for a @@ -271,14 +271,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>createdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to when creating the @@ -325,8 +325,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -362,7 +362,7 @@ PostgreSQL documentation <para> To create the database <literal>demo</literal> using the - server on host <literal>eden</>, port 5000, using the + server on host <literal>eden</literal>, port 5000, using the <literal>template0</literal> template database, here is the command-line command and the underlying SQL command: <screen> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index fda77976ff2..788ee81dafb 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -34,15 +34,15 @@ PostgreSQL documentation <para> <application>createuser</application> creates a new <productname>PostgreSQL</productname> user (or more precisely, a role). - Only superusers and users with <literal>CREATEROLE</> privilege can create + Only superusers and users with <literal>CREATEROLE</literal> privilege can create new users, so <application>createuser</application> must be invoked by someone who can connect as a superuser or a user with - <literal>CREATEROLE</> privilege. + <literal>CREATEROLE</literal> privilege. </para> <para> If you wish to create a new superuser, you must connect as a - superuser, not merely with <literal>CREATEROLE</> privilege. + superuser, not merely with <literal>CREATEROLE</literal> privilege. Being a superuser implies the ability to bypass all access permission checks within the database, so superuserdom should not be granted lightly. </para> @@ -61,7 +61,7 @@ PostgreSQL documentation <title>Options</title> <para> - <application>createuser</> accepts the following command-line arguments: + <application>createuser</application> accepts the following command-line arguments: <variablelist> <varlistentry> @@ -77,8 +77,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-c <replaceable class="parameter">number</replaceable></></term> - <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></></term> + <term><option>-c <replaceable class="parameter">number</replaceable></option></term> + <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term> <listitem> <para> Set a maximum number of connections for the new user. @@ -88,8 +88,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-d</></term> - <term><option>--createdb</></term> + <term><option>-d</option></term> + <term><option>--createdb</option></term> <listitem> <para> The new user will be allowed to create databases. @@ -98,8 +98,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-D</></term> - <term><option>--no-createdb</></term> + <term><option>-D</option></term> + <term><option>--no-createdb</option></term> <listitem> <para> The new user will not be allowed to create databases. This is the @@ -109,8 +109,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>createuser</application> generates @@ -120,8 +120,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-E</></term> - <term><option>--encrypted</></term> + <term><option>-E</option></term> + <term><option>--encrypted</option></term> <listitem> <para> This option is obsolete but still accepted for backward @@ -131,21 +131,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-g <replaceable class="parameter">role</replaceable></></term> - <term><option>--role=<replaceable class="parameter">role</replaceable></></term> + <term><option>-g <replaceable class="parameter">role</replaceable></option></term> + <term><option>--role=<replaceable class="parameter">role</replaceable></option></term> <listitem> <para> Indicates role to which this role will be added immediately as a new member. Multiple roles to which this role will be added as a member can be specified by writing multiple - <option>-g</> switches. + <option>-g</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--inherit</></term> + <term><option>-i</option></term> + <term><option>--inherit</option></term> <listitem> <para> The new role will automatically inherit privileges of roles @@ -156,8 +156,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-I</></term> - <term><option>--no-inherit</></term> + <term><option>-I</option></term> + <term><option>--no-inherit</option></term> <listitem> <para> The new role will not automatically inherit privileges of roles @@ -167,7 +167,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--interactive</></term> + <term><option>--interactive</option></term> <listitem> <para> Prompt for the user name if none is specified on the command line, and @@ -181,8 +181,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-l</></term> - <term><option>--login</></term> + <term><option>-l</option></term> + <term><option>--login</option></term> <listitem> <para> The new user will be allowed to log in (that is, the user name @@ -193,8 +193,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-L</></term> - <term><option>--no-login</></term> + <term><option>-L</option></term> + <term><option>--no-login</option></term> <listitem> <para> The new user will not be allowed to log in. @@ -205,8 +205,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-P</></term> - <term><option>--pwprompt</></term> + <term><option>-P</option></term> + <term><option>--pwprompt</option></term> <listitem> <para> If given, <application>createuser</application> will issue a prompt for @@ -217,19 +217,19 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-r</></term> - <term><option>--createrole</></term> + <term><option>-r</option></term> + <term><option>--createrole</option></term> <listitem> <para> The new user will be allowed to create new roles (that is, - this user will have <literal>CREATEROLE</> privilege). + this user will have <literal>CREATEROLE</literal> privilege). </para> </listitem> </varlistentry> <varlistentry> - <term><option>-R</></term> - <term><option>--no-createrole</></term> + <term><option>-R</option></term> + <term><option>--no-createrole</option></term> <listitem> <para> The new user will not be allowed to create new roles. This is the @@ -239,8 +239,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-s</></term> - <term><option>--superuser</></term> + <term><option>-s</option></term> + <term><option>--superuser</option></term> <listitem> <para> The new user will be a superuser. @@ -249,8 +249,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-S</></term> - <term><option>--no-superuser</></term> + <term><option>-S</option></term> + <term><option>--no-superuser</option></term> <listitem> <para> The new user will not be a superuser. This is the default. @@ -259,8 +259,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>createuser</application> version and exit. @@ -269,7 +269,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--replication</></term> + <term><option>--replication</option></term> <listitem> <para> The new user will have the <literal>REPLICATION</literal> privilege, @@ -280,7 +280,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--no-replication</></term> + <term><option>--no-replication</option></term> <listitem> <para> The new user will not have the <literal>REPLICATION</literal> @@ -291,8 +291,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>createuser</application> command line @@ -310,8 +310,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -323,8 +323,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -335,8 +335,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as (not the user name to create). @@ -345,8 +345,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -360,8 +360,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>createuser</application> to prompt for a @@ -375,7 +375,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>createuser</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -403,8 +403,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -451,7 +451,7 @@ PostgreSQL documentation <para> To create the same user <literal>joe</literal> using the - server on host <literal>eden</>, port 5000, with attributes explicitly specified, + server on host <literal>eden</literal>, port 5000, with attributes explicitly specified, taking a look at the underlying command: <screen> <prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput> diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 5cb85cc568f..8eae0354af8 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -45,7 +45,7 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <note> <para> This page describes usage of cursors at the SQL command level. - If you are trying to use cursors inside a <application>PL/pgSQL</> + If you are trying to use cursors inside a <application>PL/pgSQL</application> function, the rules are different — see <xref linkend="plpgsql-cursors">. </para> @@ -144,13 +144,13 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> Normal cursors return data in text format, the same as a - <command>SELECT</> would produce. The <literal>BINARY</> option + <command>SELECT</command> would produce. The <literal>BINARY</literal> option specifies that the cursor should return data in binary format. This reduces conversion effort for both the server and client, at the cost of more programmer effort to deal with platform-dependent binary data formats. As an example, if a query returns a value of one from an integer column, - you would get a string of <literal>1</> with a default cursor, + you would get a string of <literal>1</literal> with a default cursor, whereas with a binary cursor you would get a 4-byte field containing the internal representation of the value (in big-endian byte order). @@ -165,8 +165,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <note> <para> - When the client application uses the <quote>extended query</> protocol - to issue a <command>FETCH</> command, the Bind protocol message + When the client application uses the <quote>extended query</quote> protocol + to issue a <command>FETCH</command> command, the Bind protocol message specifies whether data is to be retrieved in text or binary format. This choice overrides the way that the cursor is defined. The concept of a binary cursor as such is thus obsolete when using extended query @@ -177,7 +177,7 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> Unless <literal>WITH HOLD</literal> is specified, the cursor created by this command can only be used within the current - transaction. Thus, <command>DECLARE</> without <literal>WITH + transaction. Thus, <command>DECLARE</command> without <literal>WITH HOLD</literal> is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore <productname>PostgreSQL</productname> reports an error if such a @@ -204,25 +204,25 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> <literal>WITH HOLD</literal> may not be specified when the query - includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>. + includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>. </para> <para> - The <literal>SCROLL</> option should be specified when defining a + The <literal>SCROLL</literal> option should be specified when defining a cursor that will be used to fetch backwards. This is required by the SQL standard. However, for compatibility with earlier versions, <productname>PostgreSQL</productname> will allow - backward fetches without <literal>SCROLL</>, if the cursor's query + backward fetches without <literal>SCROLL</literal>, if the cursor's query plan is simple enough that no extra overhead is needed to support it. However, application developers are advised not to rely on using backward fetches from a cursor that has not been created - with <literal>SCROLL</literal>. If <literal>NO SCROLL</> is + with <literal>SCROLL</literal>. If <literal>NO SCROLL</literal> is specified, then backward fetches are disallowed in any case. </para> <para> Backward fetches are also disallowed when the query - includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>; therefore + includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>; therefore <literal>SCROLL</literal> may not be specified in this case. </para> @@ -241,42 +241,42 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI </caution> <para> - If the cursor's query includes <literal>FOR UPDATE</> or <literal>FOR - SHARE</>, then returned rows are locked at the time they are first + If the cursor's query includes <literal>FOR UPDATE</literal> or <literal>FOR + SHARE</literal>, then returned rows are locked at the time they are first fetched, in the same way as for a regular <xref linkend="sql-select"> command with these options. In addition, the returned rows will be the most up-to-date versions; therefore these options provide the equivalent of what the SQL standard - calls a <quote>sensitive cursor</>. (Specifying <literal>INSENSITIVE</> - together with <literal>FOR UPDATE</> or <literal>FOR SHARE</> is an error.) + calls a <quote>sensitive cursor</quote>. (Specifying <literal>INSENSITIVE</literal> + together with <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal> is an error.) </para> <caution> <para> - It is generally recommended to use <literal>FOR UPDATE</> if the cursor - is intended to be used with <command>UPDATE ... WHERE CURRENT OF</> or - <command>DELETE ... WHERE CURRENT OF</>. Using <literal>FOR UPDATE</> + It is generally recommended to use <literal>FOR UPDATE</literal> if the cursor + is intended to be used with <command>UPDATE ... WHERE CURRENT OF</command> or + <command>DELETE ... WHERE CURRENT OF</command>. Using <literal>FOR UPDATE</literal> prevents other sessions from changing the rows between the time they are - fetched and the time they are updated. Without <literal>FOR UPDATE</>, - a subsequent <literal>WHERE CURRENT OF</> command will have no effect if + fetched and the time they are updated. Without <literal>FOR UPDATE</literal>, + a subsequent <literal>WHERE CURRENT OF</literal> command will have no effect if the row was changed since the cursor was created. </para> <para> - Another reason to use <literal>FOR UPDATE</> is that without it, a - subsequent <literal>WHERE CURRENT OF</> might fail if the cursor query + Another reason to use <literal>FOR UPDATE</literal> is that without it, a + subsequent <literal>WHERE CURRENT OF</literal> might fail if the cursor query does not meet the SQL standard's rules for being <quote>simply - updatable</> (in particular, the cursor must reference just one table - and not use grouping or <literal>ORDER BY</>). Cursors + updatable</quote> (in particular, the cursor must reference just one table + and not use grouping or <literal>ORDER BY</literal>). Cursors that are not simply updatable might work, or might not, depending on plan choice details; so in the worst case, an application might work in testing and then fail in production. </para> <para> - The main reason not to use <literal>FOR UPDATE</> with <literal>WHERE - CURRENT OF</> is if you need the cursor to be scrollable, or to be + The main reason not to use <literal>FOR UPDATE</literal> with <literal>WHERE + CURRENT OF</literal> is if you need the cursor to be scrollable, or to be insensitive to the subsequent updates (that is, continue to show the old data). If this is a requirement, pay close heed to the caveats shown above. @@ -321,13 +321,13 @@ DECLARE liahona CURSOR FOR SELECT * FROM films; The SQL standard says that it is implementation-dependent whether cursors are sensitive to concurrent updates of the underlying data by default. In <productname>PostgreSQL</productname>, cursors are insensitive by default, - and can be made sensitive by specifying <literal>FOR UPDATE</>. Other + and can be made sensitive by specifying <literal>FOR UPDATE</literal>. Other products may work differently. </para> <para> The SQL standard allows cursors only in embedded - <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</> + <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</productname> permits cursors to be used interactively. </para> diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 8ced7de7be6..570e9aa7108 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -55,12 +55,12 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * </para> <para> - The optional <literal>RETURNING</> clause causes <command>DELETE</> + The optional <literal>RETURNING</literal> clause causes <command>DELETE</command> to compute and return value(s) based on each row actually deleted. Any expression using the table's columns, and/or columns of other tables mentioned in <literal>USING</literal>, can be computed. - The syntax of the <literal>RETURNING</> list is identical to that of the - output list of <command>SELECT</>. + The syntax of the <literal>RETURNING</literal> list is identical to that of the + output list of <command>SELECT</command>. </para> <para> @@ -81,7 +81,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> The <literal>WITH</literal> clause allows you to specify one or more - subqueries that can be referenced by name in the <command>DELETE</> + subqueries that can be referenced by name in the <command>DELETE</command> query. See <xref linkend="queries-with"> and <xref linkend="sql-select"> for details. </para> @@ -93,11 +93,11 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> The name (optionally schema-qualified) of the table to delete rows - from. If <literal>ONLY</> is specified before the table name, + from. If <literal>ONLY</literal> is specified before the table name, matching rows are deleted from the named table only. If - <literal>ONLY</> is not specified, matching rows are also deleted + <literal>ONLY</literal> is not specified, matching rows are also deleted from any tables inheriting from the named table. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -109,9 +109,9 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <para> A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. For - example, given <literal>DELETE FROM foo AS f</>, the remainder + example, given <literal>DELETE FROM foo AS f</literal>, the remainder of the <command>DELETE</command> statement must refer to this - table as <literal>f</> not <literal>foo</>. + table as <literal>f</literal> not <literal>foo</literal>. </para> </listitem> </varlistentry> @@ -121,7 +121,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> A list of table expressions, allowing columns from other tables - to appear in the <literal>WHERE</> condition. This is similar + to appear in the <literal>WHERE</literal> condition. 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 @@ -137,7 +137,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> An expression that returns a value of type <type>boolean</type>. - Only rows for which this expression returns <literal>true</> + Only rows for which this expression returns <literal>true</literal> will be deleted. </para> </listitem> @@ -147,15 +147,15 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <term><replaceable class="parameter">cursor_name</replaceable></term> <listitem> <para> - The name of the cursor to use in a <literal>WHERE CURRENT OF</> + The name of the cursor to use in a <literal>WHERE CURRENT OF</literal> condition. The row to be deleted is the one most recently fetched from this cursor. The cursor must be a non-grouping - query on the <command>DELETE</>'s target table. - Note that <literal>WHERE CURRENT OF</> cannot be + query on the <command>DELETE</command>'s target table. + Note that <literal>WHERE CURRENT OF</literal> cannot be specified together with a Boolean condition. See <xref linkend="sql-declare"> for more information about using cursors with - <literal>WHERE CURRENT OF</>. + <literal>WHERE CURRENT OF</literal>. </para> </listitem> </varlistentry> @@ -164,11 +164,11 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <term><replaceable class="parameter">output_expression</replaceable></term> <listitem> <para> - An expression to be computed and returned by the <command>DELETE</> + An expression to be computed and returned by the <command>DELETE</command> command after each row is deleted. The expression can use any column names of the table named by <replaceable class="parameter">table_name</replaceable> - or table(s) listed in <literal>USING</>. - Write <literal>*</> to return all columns. + or table(s) listed in <literal>USING</literal>. + Write <literal>*</literal> to return all columns. </para> </listitem> </varlistentry> @@ -188,7 +188,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <title>Outputs</title> <para> - On successful completion, a <command>DELETE</> command returns a command + On successful completion, a <command>DELETE</command> command returns a command tag of the form <screen> DELETE <replaceable class="parameter">count</replaceable> @@ -197,16 +197,16 @@ DELETE <replaceable class="parameter">count</replaceable> of rows deleted. Note that the number may be less than the number of rows that matched the <replaceable class="parameter">condition</replaceable> when deletes were - suppressed by a <literal>BEFORE DELETE</> trigger. If <replaceable + suppressed by a <literal>BEFORE DELETE</literal> trigger. If <replaceable class="parameter">count</replaceable> is 0, no rows were deleted by the query (this is not considered an error). </para> <para> - If the <command>DELETE</> command contains a <literal>RETURNING</> - clause, the result will be similar to that of a <command>SELECT</> + If the <command>DELETE</command> command contains a <literal>RETURNING</literal> + clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the - <literal>RETURNING</> list, computed over the row(s) deleted by the + <literal>RETURNING</literal> list, computed over the row(s) deleted by the command. </para> </refsect1> @@ -216,16 +216,16 @@ DELETE <replaceable class="parameter">count</replaceable> <para> <productname>PostgreSQL</productname> lets you reference columns of - other tables in the <literal>WHERE</> condition by specifying the + other tables in the <literal>WHERE</literal> condition by specifying the other tables in the <literal>USING</literal> clause. For example, to delete all films produced by a given producer, one can do: <programlisting> DELETE FROM films USING producers WHERE producer_id = producers.id AND producers.name = 'foo'; </programlisting> - What is essentially happening here is a join between <structname>films</> - and <structname>producers</>, with all successfully joined - <structname>films</> rows being marked for deletion. + What is essentially happening here is a join between <structname>films</structname> + and <structname>producers</structname>, with all successfully joined + <structname>films</structname> rows being marked for deletion. This syntax is not standard. A more standard way to do it is: <programlisting> DELETE FROM films @@ -261,8 +261,8 @@ DELETE FROM tasks WHERE status = 'DONE' RETURNING *; </para> <para> - Delete the row of <structname>tasks</> on which the cursor - <literal>c_tasks</> is currently positioned: + Delete the row of <structname>tasks</structname> on which the cursor + <literal>c_tasks</literal> is currently positioned: <programlisting> DELETE FROM tasks WHERE CURRENT OF c_tasks; </programlisting></para> @@ -273,9 +273,9 @@ DELETE FROM tasks WHERE CURRENT OF c_tasks; <para> This command conforms to the <acronym>SQL</acronym> standard, except - that the <literal>USING</literal> and <literal>RETURNING</> clauses + that the <literal>USING</literal> and <literal>RETURNING</literal> clauses are <productname>PostgreSQL</productname> extensions, as is the ability - to use <literal>WITH</> with <command>DELETE</>. + to use <literal>WITH</literal> with <command>DELETE</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/discard.sgml b/doc/src/sgml/ref/discard.sgml index e859bf7bab7..f432e70430d 100644 --- a/doc/src/sgml/ref/discard.sgml +++ b/doc/src/sgml/ref/discard.sgml @@ -29,10 +29,10 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP } <title>Description</title> <para> - <command>DISCARD</> releases internal resources associated with a + <command>DISCARD</command> releases internal resources associated with a database session. This command is useful for partially or fully resetting the session's state. There are several subcommands to - release different types of resources; the <command>DISCARD ALL</> + release different types of resources; the <command>DISCARD ALL</command> variant subsumes all the others, and also resets additional state. </para> </refsect1> @@ -57,9 +57,9 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP } <listitem> <para> Discards all cached sequence-related state, - including <function>currval()</>/<function>lastval()</> + including <function>currval()</function>/<function>lastval()</function> information and any preallocated sequence values that have not - yet been returned by <function>nextval()</>. + yet been returned by <function>nextval()</function>. (See <xref linkend="sql-createsequence"> for a description of preallocated sequence values.) </para> @@ -104,7 +104,7 @@ DISCARD TEMP; <title>Notes</title> <para> - <command>DISCARD ALL</> cannot be executed inside a transaction block. + <command>DISCARD ALL</command> cannot be executed inside a transaction block. </para> </refsect1> diff --git a/doc/src/sgml/ref/do.sgml b/doc/src/sgml/ref/do.sgml index d4da32c34dc..5d2e9b1b8ce 100644 --- a/doc/src/sgml/ref/do.sgml +++ b/doc/src/sgml/ref/do.sgml @@ -39,12 +39,12 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <para> The code block is treated as though it were the body of a function - with no parameters, returning <type>void</>. It is parsed and + with no parameters, returning <type>void</type>. It is parsed and executed a single time. </para> <para> - The optional <literal>LANGUAGE</> clause can be written either + The optional <literal>LANGUAGE</literal> clause can be written either before or after the code block. </para> </refsect1> @@ -58,7 +58,7 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <listitem> <para> The procedural language code to be executed. This must be specified - as a string literal, just as in <command>CREATE FUNCTION</>. + as a string literal, just as in <command>CREATE FUNCTION</command>. Use of a dollar-quoted literal is recommended. </para> </listitem> @@ -69,7 +69,7 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <listitem> <para> The name of the procedural language the code is written in. - If omitted, the default is <literal>plpgsql</>. + If omitted, the default is <literal>plpgsql</literal>. </para> </listitem> </varlistentry> @@ -81,12 +81,12 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <para> The procedural language to be used must already have been installed - into the current database by means of <command>CREATE LANGUAGE</>. - <literal>plpgsql</> is installed by default, but other languages are not. + into the current database by means of <command>CREATE LANGUAGE</command>. + <literal>plpgsql</literal> is installed by default, but other languages are not. </para> <para> - The user must have <literal>USAGE</> privilege for the procedural + The user must have <literal>USAGE</literal> privilege for the procedural language, or must be a superuser if the language is untrusted. This is the same privilege requirement as for creating a function in the language. @@ -96,8 +96,8 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <refsect1 id="sql-do-examples"> <title id="sql-do-examples-title">Examples</title> <para> - Grant all privileges on all views in schema <literal>public</> to - role <literal>webuser</>: + Grant all privileges on all views in schema <literal>public</literal> to + role <literal>webuser</literal>: <programlisting> DO $$DECLARE r record; BEGIN diff --git a/doc/src/sgml/ref/drop_access_method.sgml b/doc/src/sgml/ref/drop_access_method.sgml index 8aa9197fe4a..aa5d2505c7d 100644 --- a/doc/src/sgml/ref/drop_access_method.sgml +++ b/doc/src/sgml/ref/drop_access_method.sgml @@ -85,7 +85,7 @@ DROP ACCESS METHOD [ IF EXISTS ] <replaceable class="parameter">name</replaceabl <title>Examples</title> <para> - Drop the access method <literal>heptree</>: + Drop the access method <literal>heptree</literal>: <programlisting> DROP ACCESS METHOD heptree; </programlisting></para> @@ -96,7 +96,7 @@ DROP ACCESS METHOD heptree; <para> <command>DROP ACCESS METHOD</command> is a - <productname>PostgreSQL</> extension. + <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index dde1ea24449..ac29e7a4193 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -70,8 +70,8 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. </para> </listitem> </varlistentry> @@ -94,10 +94,10 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr <listitem> <para> An input data type on which the aggregate function operates. - To reference a zero-argument aggregate function, write <literal>*</> + To reference a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. To reference an ordered-set aggregate function, write - <literal>ORDER BY</> between the direct and aggregated argument + <literal>ORDER BY</literal> between the direct and aggregated argument specifications. </para> </listitem> @@ -148,7 +148,7 @@ DROP AGGREGATE myavg(integer); </para> <para> - To remove the hypothetical-set aggregate function <literal>myrank</>, + To remove the hypothetical-set aggregate function <literal>myrank</literal>, which takes an arbitrary list of ordering columns and a matching list of direct arguments: <programlisting> diff --git a/doc/src/sgml/ref/drop_collation.sgml b/doc/src/sgml/ref/drop_collation.sgml index 2177d8e5d65..23f8e88fc95 100644 --- a/doc/src/sgml/ref/drop_collation.sgml +++ b/doc/src/sgml/ref/drop_collation.sgml @@ -83,7 +83,7 @@ DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRIC <title>Examples</title> <para> - To drop the collation named <literal>german</>: + To drop the collation named <literal>german</literal>: <programlisting> DROP COLLATION german; </programlisting></para> @@ -95,7 +95,7 @@ DROP COLLATION german; <para> The <command>DROP COLLATION</command> command conforms to the <acronym>SQL</acronym> standard, apart from the <literal>IF - EXISTS</> option, which is a <productname>PostgreSQL</> extension. + EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_conversion.sgml b/doc/src/sgml/ref/drop_conversion.sgml index 1a33b3dcc52..9d56ec51a59 100644 --- a/doc/src/sgml/ref/drop_conversion.sgml +++ b/doc/src/sgml/ref/drop_conversion.sgml @@ -74,7 +74,7 @@ DROP CONVERSION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRI <title>Examples</title> <para> - To drop the conversion named <literal>myname</>: + To drop the conversion named <literal>myname</literal>: <programlisting> DROP CONVERSION myname; </programlisting></para> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index 44436ad48db..7e5fbe7396c 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -71,7 +71,7 @@ DROP DATABASE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>DROP DATABASE</> cannot be executed inside a transaction + <command>DROP DATABASE</command> cannot be executed inside a transaction block. </para> diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index ba546165c20..b1dac01e652 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -58,7 +58,7 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . </varlistentry> <varlistentry> - <term><literal>CASCADE</></term> + <term><literal>CASCADE</literal></term> <listitem> <para> Automatically drop objects that depend on the domain (such as @@ -70,7 +70,7 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . </varlistentry> <varlistentry> - <term><literal>RESTRICT</></term> + <term><literal>RESTRICT</literal></term> <listitem> <para> Refuse to drop the domain if any objects depend on it. This is @@ -97,7 +97,7 @@ DROP DOMAIN box; <para> This command conforms to the SQL standard, except for the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml index ba529220135..f75308a20d3 100644 --- a/doc/src/sgml/ref/drop_extension.sgml +++ b/doc/src/sgml/ref/drop_extension.sgml @@ -79,7 +79,7 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ <para> Refuse to drop the extension if any objects depend on it (other than its own member objects and other extensions listed in the same - <command>DROP</> command). This is the default. + <command>DROP</command> command). This is the default. </para> </listitem> </varlistentry> @@ -97,7 +97,7 @@ DROP EXTENSION hstore; </programlisting> This command will fail if any of <literal>hstore</literal>'s objects are in use in the database, for example if any tables have columns - of the <type>hstore</> type. Add the <literal>CASCADE</> option to + of the <type>hstore</type> type. Add the <literal>CASCADE</literal> option to forcibly remove those dependent objects as well. </para> </refsect1> @@ -106,7 +106,7 @@ DROP EXTENSION hstore; <title>Compatibility</title> <para> - <command>DROP EXTENSION</command> is a <productname>PostgreSQL</> + <command>DROP EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml index 702cc021dbc..a3c73a0d46b 100644 --- a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml @@ -86,7 +86,7 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</rep <title>Examples</title> <para> - Drop the foreign-data wrapper <literal>dbi</>: + Drop the foreign-data wrapper <literal>dbi</literal>: <programlisting> DROP FOREIGN DATA WRAPPER dbi; </programlisting></para> @@ -97,8 +97,8 @@ DROP FOREIGN DATA WRAPPER dbi; <para> <command>DROP FOREIGN DATA WRAPPER</command> conforms to ISO/IEC - 9075-9 (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + 9075-9 (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_foreign_table.sgml b/doc/src/sgml/ref/drop_foreign_table.sgml index 173eadadd36..456d55d1122 100644 --- a/doc/src/sgml/ref/drop_foreign_table.sgml +++ b/doc/src/sgml/ref/drop_foreign_table.sgml @@ -95,7 +95,7 @@ DROP FOREIGN TABLE films, distributors; <para> This command conforms to the ISO/IEC 9075-9 (SQL/MED), except that the standard only allows one foreign table to be dropped per command, and apart - from the <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + from the <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 0aa984528d3..9c9adb9a46d 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -67,14 +67,14 @@ DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>DROP FUNCTION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 4c838fffffb..de36c135d16 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -44,19 +44,19 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <replaceable class="parameter">name</r <listitem> <para> Drop the index without locking out concurrent selects, inserts, updates, - and deletes on the index's table. A normal <command>DROP INDEX</> + and deletes on the index's table. A normal <command>DROP INDEX</command> acquires exclusive lock on the table, blocking other accesses until the index drop can be completed. With this option, the command instead waits until conflicting transactions have completed. </para> <para> There are several caveats to be aware of when using this option. - Only one index name can be specified, and the <literal>CASCADE</> option - is not supported. (Thus, an index that supports a <literal>UNIQUE</> or - <literal>PRIMARY KEY</> constraint cannot be dropped this way.) - Also, regular <command>DROP INDEX</> commands can be + Only one index name can be specified, and the <literal>CASCADE</literal> option + is not supported. (Thus, an index that supports a <literal>UNIQUE</literal> or + <literal>PRIMARY KEY</literal> constraint cannot be dropped this way.) + Also, regular <command>DROP INDEX</command> commands can be performed within a transaction block, but - <command>DROP INDEX CONCURRENTLY</> cannot. + <command>DROP INDEX CONCURRENTLY</command> cannot. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 081bd5fe3ec..524d7583703 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -31,13 +31,13 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <replaceable class="parameter">name</ <para> <command>DROP LANGUAGE</command> removes the definition of a previously registered procedural language. You must be a superuser - or the owner of the language to use <command>DROP LANGUAGE</>. + or the owner of the language to use <command>DROP LANGUAGE</command>. </para> <note> <para> As of <productname>PostgreSQL</productname> 9.1, most procedural - languages have been made into <quote>extensions</>, and should + languages have been made into <quote>extensions</quote>, and should therefore be removed with <xref linkend="sql-dropextension"> not <command>DROP LANGUAGE</command>. </para> diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml index 423a211bcab..83af6d7e485 100644 --- a/doc/src/sgml/ref/drop_opclass.sgml +++ b/doc/src/sgml/ref/drop_opclass.sgml @@ -37,7 +37,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="parameter">name</replaceab <command>DROP OPERATOR CLASS</command> does not drop any of the operators or functions referenced by the class. If there are any indexes depending on the operator class, you will need to specify - <literal>CASCADE</> for the drop to complete. + <literal>CASCADE</literal> for the drop to complete. </para> </refsect1> @@ -101,13 +101,13 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="parameter">name</replaceab <title>Notes</title> <para> - <command>DROP OPERATOR CLASS</> will not drop the operator family + <command>DROP OPERATOR CLASS</command> will not drop the operator family containing the class, even if there is nothing else left in the family (in particular, in the case where the family was implicitly - created by <command>CREATE OPERATOR CLASS</>). An empty operator + created by <command>CREATE OPERATOR CLASS</command>). An empty operator family is harmless, but for the sake of tidiness you might wish to - remove the family with <command>DROP OPERATOR FAMILY</>; or perhaps - better, use <command>DROP OPERATOR FAMILY</> in the first place. + remove the family with <command>DROP OPERATOR FAMILY</command>; or perhaps + better, use <command>DROP OPERATOR FAMILY</command> in the first place. </para> </refsect1> @@ -122,7 +122,7 @@ DROP OPERATOR CLASS widget_ops USING btree; </programlisting> This command will not succeed if there are any existing indexes - that use the operator class. Add <literal>CASCADE</> to drop + that use the operator class. Add <literal>CASCADE</literal> to drop such indexes along with the operator class. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_opfamily.sgml b/doc/src/sgml/ref/drop_opfamily.sgml index a7b90f306c7..b825978aee9 100644 --- a/doc/src/sgml/ref/drop_opfamily.sgml +++ b/doc/src/sgml/ref/drop_opfamily.sgml @@ -38,7 +38,7 @@ DROP OPERATOR FAMILY [ IF EXISTS ] <replaceable class="parameter">name</replacea classes contained in the family, but it does not drop any of the operators or functions referenced by the family. If there are any indexes depending on operator classes within the family, you will need to specify - <literal>CASCADE</> for the drop to complete. + <literal>CASCADE</literal> for the drop to complete. </para> </refsect1> @@ -109,7 +109,7 @@ DROP OPERATOR FAMILY float_ops USING btree; </programlisting> This command will not succeed if there are any existing indexes - that use operator classes within the family. Add <literal>CASCADE</> to + that use operator classes within the family. Add <literal>CASCADE</literal> to drop such indexes along with the operator family. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml index 0426373d2de..8b4b3644e66 100644 --- a/doc/src/sgml/ref/drop_owned.sgml +++ b/doc/src/sgml/ref/drop_owned.sgml @@ -92,7 +92,7 @@ DROP OWNED BY { <replaceable class="parameter">name</replaceable> | CURRENT_USER <para> The <xref linkend="sql-reassign-owned"> command is an alternative that reassigns the ownership of all the database objects owned by one or - more roles. However, <command>REASSIGN OWNED</> does not deal with + more roles. However, <command>REASSIGN OWNED</command> does not deal with privileges for other objects. </para> diff --git a/doc/src/sgml/ref/drop_publication.sgml b/doc/src/sgml/ref/drop_publication.sgml index bf43db3dac3..1c129c04443 100644 --- a/doc/src/sgml/ref/drop_publication.sgml +++ b/doc/src/sgml/ref/drop_publication.sgml @@ -89,7 +89,7 @@ DROP PUBLICATION mypublication; <title>Compatibility</title> <para> - <command>DROP PUBLICATION</command> is a <productname>PostgreSQL</> + <command>DROP PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_role.sgml b/doc/src/sgml/ref/drop_role.sgml index fcddfeb172c..3c1bbaba6fd 100644 --- a/doc/src/sgml/ref/drop_role.sgml +++ b/doc/src/sgml/ref/drop_role.sgml @@ -31,7 +31,7 @@ DROP ROLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ... <para> <command>DROP ROLE</command> removes the specified role(s). To drop a superuser role, you must be a superuser yourself; - to drop non-superuser roles, you must have <literal>CREATEROLE</> + to drop non-superuser roles, you must have <literal>CREATEROLE</literal> privilege. </para> @@ -47,7 +47,7 @@ DROP ROLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ... <para> However, it is not necessary to remove role memberships involving - the role; <command>DROP ROLE</> automatically revokes any memberships + the role; <command>DROP ROLE</command> automatically revokes any memberships of the target role in other roles, and of other roles in the target role. The other roles are not dropped nor otherwise affected. </para> diff --git a/doc/src/sgml/ref/drop_schema.sgml b/doc/src/sgml/ref/drop_schema.sgml index fd1fcd7e037..bb3af1e1863 100644 --- a/doc/src/sgml/ref/drop_schema.sgml +++ b/doc/src/sgml/ref/drop_schema.sgml @@ -114,7 +114,7 @@ DROP SCHEMA mystuff CASCADE; <command>DROP SCHEMA</command> is fully conforming with the SQL standard, except that the standard only allows one schema to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index 9d827f0cb17..5027129b38b 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -98,7 +98,7 @@ DROP SEQUENCE serial; <command>DROP SEQUENCE</command> conforms to the <acronym>SQL</acronym> standard, except that the standard only allows one sequence to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_server.sgml b/doc/src/sgml/ref/drop_server.sgml index 42acdd41dc1..8ef0e014e4f 100644 --- a/doc/src/sgml/ref/drop_server.sgml +++ b/doc/src/sgml/ref/drop_server.sgml @@ -86,7 +86,7 @@ DROP SERVER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . <title>Examples</title> <para> - Drop a server <literal>foo</> if it exists: + Drop a server <literal>foo</literal> if it exists: <programlisting> DROP SERVER IF EXISTS foo; </programlisting></para> @@ -97,8 +97,8 @@ DROP SERVER IF EXISTS foo; <para> <command>DROP SERVER</command> conforms to ISO/IEC 9075-9 - (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_subscription.sgml b/doc/src/sgml/ref/drop_subscription.sgml index f5734e6f300..58b14894757 100644 --- a/doc/src/sgml/ref/drop_subscription.sgml +++ b/doc/src/sgml/ref/drop_subscription.sgml @@ -114,7 +114,7 @@ DROP SUBSCRIPTION mysub; <title>Compatibility</title> <para> - <command>DROP SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>DROP SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index ae96cf06575..cea7e003511 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -40,8 +40,8 @@ DROP TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, .. <command>DROP TABLE</command> always removes any indexes, rules, triggers, and constraints that exist for the target table. However, to drop a table that is referenced by a view or a foreign-key - constraint of another table, <literal>CASCADE</> must be - specified. (<literal>CASCADE</> will remove a dependent view entirely, + constraint of another table, <literal>CASCADE</literal> must be + specified. (<literal>CASCADE</literal> will remove a dependent view entirely, but in the foreign-key case it will only remove the foreign-key constraint, not the other table entirely.) </para> @@ -112,7 +112,7 @@ DROP TABLE films, distributors; <para> This command conforms to the SQL standard, except that the standard only allows one table to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tablespace.sgml b/doc/src/sgml/ref/drop_tablespace.sgml index ee40cc6b0c3..4343035ebb2 100644 --- a/doc/src/sgml/ref/drop_tablespace.sgml +++ b/doc/src/sgml/ref/drop_tablespace.sgml @@ -39,7 +39,7 @@ DROP TABLESPACE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> in the tablespace even if no objects in the current database are using the tablespace. Also, if the tablespace is listed in the <xref linkend="guc-temp-tablespaces"> setting of any active session, the - <command>DROP</> might fail due to temporary files residing in the + <command>DROP</command> might fail due to temporary files residing in the tablespace. </para> </refsect1> @@ -74,7 +74,7 @@ DROP TABLESPACE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>DROP TABLESPACE</> cannot be executed inside a transaction block. + <command>DROP TABLESPACE</command> cannot be executed inside a transaction block. </para> </refsect1> @@ -93,7 +93,7 @@ DROP TABLESPACE mystuff; <title>Compatibility</title> <para> - <command>DROP TABLESPACE</command> is a <productname>PostgreSQL</> + <command>DROP TABLESPACE</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsconfig.sgml b/doc/src/sgml/ref/drop_tsconfig.sgml index e4a1738baeb..cc053beceb7 100644 --- a/doc/src/sgml/ref/drop_tsconfig.sgml +++ b/doc/src/sgml/ref/drop_tsconfig.sgml @@ -94,8 +94,8 @@ DROP TEXT SEARCH CONFIGURATION my_english; </programlisting> This command will not succeed if there are any existing indexes - that reference the configuration in <function>to_tsvector</> calls. - Add <literal>CASCADE</> to + that reference the configuration in <function>to_tsvector</function> calls. + Add <literal>CASCADE</literal> to drop such indexes along with the text search configuration. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsdictionary.sgml b/doc/src/sgml/ref/drop_tsdictionary.sgml index faa4b3a1e5d..66af10fb0f4 100644 --- a/doc/src/sgml/ref/drop_tsdictionary.sgml +++ b/doc/src/sgml/ref/drop_tsdictionary.sgml @@ -94,7 +94,7 @@ DROP TEXT SEARCH DICTIONARY english; </programlisting> This command will not succeed if there are any existing text search - configurations that use the dictionary. Add <literal>CASCADE</> to + configurations that use the dictionary. Add <literal>CASCADE</literal> to drop such configurations along with the dictionary. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsparser.sgml b/doc/src/sgml/ref/drop_tsparser.sgml index bc9dae17a5e..3fa9467ebdd 100644 --- a/doc/src/sgml/ref/drop_tsparser.sgml +++ b/doc/src/sgml/ref/drop_tsparser.sgml @@ -92,7 +92,7 @@ DROP TEXT SEARCH PARSER my_parser; </programlisting> This command will not succeed if there are any existing text search - configurations that use the parser. Add <literal>CASCADE</> to + configurations that use the parser. Add <literal>CASCADE</literal> to drop such configurations along with the parser. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tstemplate.sgml b/doc/src/sgml/ref/drop_tstemplate.sgml index 98f5523e513..ad832754573 100644 --- a/doc/src/sgml/ref/drop_tstemplate.sgml +++ b/doc/src/sgml/ref/drop_tstemplate.sgml @@ -93,7 +93,7 @@ DROP TEXT SEARCH TEMPLATE thesaurus; </programlisting> This command will not succeed if there are any existing text search - dictionaries that use the template. Add <literal>CASCADE</> to + dictionaries that use the template. Add <literal>CASCADE</literal> to drop such dictionaries along with the template. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 4ec1b92f329..92ac2729caf 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -96,8 +96,8 @@ DROP TYPE box; <para> This command is similar to the corresponding command in the SQL - standard, apart from the <literal>IF EXISTS</> - option, which is a <productname>PostgreSQL</> extension. + standard, apart from the <literal>IF EXISTS</literal> + option, which is a <productname>PostgreSQL</productname> extension. But note that much of the <command>CREATE TYPE</command> command and the data type extension mechanisms in <productname>PostgreSQL</productname> differ from the SQL standard. diff --git a/doc/src/sgml/ref/drop_user_mapping.sgml b/doc/src/sgml/ref/drop_user_mapping.sgml index eb4c3202939..27284acae4c 100644 --- a/doc/src/sgml/ref/drop_user_mapping.sgml +++ b/doc/src/sgml/ref/drop_user_mapping.sgml @@ -36,7 +36,7 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <para> The owner of a foreign server can drop user mappings for that server for any user. Also, a user can drop a user mapping for their own - user name if <literal>USAGE</> privilege on the server has been + user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -59,9 +59,9 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <term><replaceable class="parameter">user_name</replaceable></term> <listitem> <para> - User name of the mapping. <literal>CURRENT_USER</> - and <literal>USER</> match the name of the current - user. <literal>PUBLIC</> is used to match all present and + User name of the mapping. <literal>CURRENT_USER</literal> + and <literal>USER</literal> match the name of the current + user. <literal>PUBLIC</literal> is used to match all present and future user names in the system. </para> </listitem> @@ -82,7 +82,7 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <title>Examples</title> <para> - Drop a user mapping <literal>bob</>, server <literal>foo</> if it exists: + Drop a user mapping <literal>bob</literal>, server <literal>foo</literal> if it exists: <programlisting> DROP USER MAPPING IF EXISTS FOR bob SERVER foo; </programlisting></para> @@ -93,8 +93,8 @@ DROP USER MAPPING IF EXISTS FOR bob SERVER foo; <para> <command>DROP USER MAPPING</command> conforms to ISO/IEC 9075-9 - (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 002d2c6dd65..a33b33335b0 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -97,7 +97,7 @@ DROP VIEW kinds; <para> This command conforms to the SQL standard, except that the standard only allows one view to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index 16c49e7928b..9dd44be8828 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -53,7 +53,7 @@ PostgreSQL documentation <title>Options</title> <para> - <application>dropdb</> accepts the following command-line arguments: + <application>dropdb</application> accepts the following command-line arguments: <variablelist> <varlistentry> @@ -66,8 +66,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>dropdb</application> generates @@ -77,8 +77,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--interactive</></term> + <term><option>-i</option></term> + <term><option>--interactive</option></term> <listitem> <para> Issues a verification prompt before doing anything destructive. @@ -87,8 +87,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>dropdb</application> version and exit. @@ -97,7 +97,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--if-exists</></term> + <term><option>--if-exists</option></term> <listitem> <para> Do not throw an error if the database does not exist. A notice is issued @@ -107,8 +107,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>dropdb</application> command line @@ -127,8 +127,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -140,8 +140,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -152,8 +152,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -162,8 +162,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -177,8 +177,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>dropdb</application> to prompt for a @@ -191,14 +191,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>dropdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to in order to drop the @@ -231,8 +231,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index d7ad61b3d63..1387b7dc2da 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -35,7 +35,7 @@ PostgreSQL documentation <para> <application>dropuser</application> removes an existing <productname>PostgreSQL</productname> user. - Only superusers and users with the <literal>CREATEROLE</> privilege can + Only superusers and users with the <literal>CREATEROLE</literal> privilege can remove <productname>PostgreSQL</productname> users. (To remove a superuser, you must yourself be a superuser.) </para> @@ -70,8 +70,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>dropuser</application> generates @@ -81,8 +81,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--interactive</></term> + <term><option>-i</option></term> + <term><option>--interactive</option></term> <listitem> <para> Prompt for confirmation before actually removing the user, and prompt @@ -92,8 +92,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>dropuser</application> version and exit. @@ -102,7 +102,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--if-exists</></term> + <term><option>--if-exists</option></term> <listitem> <para> Do not throw an error if the user does not exist. A notice is @@ -112,8 +112,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>dropuser</application> command line @@ -131,8 +131,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -144,8 +144,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -156,8 +156,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as (not the user name to drop). @@ -166,8 +166,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -181,8 +181,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>dropuser</application> to prompt for a @@ -195,7 +195,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>dropuser</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -223,8 +223,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index 8bfb47c4d79..a9eaff815dc 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -220,9 +220,9 @@ PostgreSQL documentation <para> When compiling the preprocessed C code files, the compiler needs to - be able to find the <application>ECPG</> header files in the - <productname>PostgreSQL</> include directory. Therefore, you might - have to use the <option>-I</> option when invoking the compiler + be able to find the <application>ECPG</application> header files in the + <productname>PostgreSQL</productname> include directory. Therefore, you might + have to use the <option>-I</option> option when invoking the compiler (e.g., <literal>-I/usr/local/pgsql/include</literal>). </para> diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml index 10e414515bf..1f74118efd9 100644 --- a/doc/src/sgml/ref/end.sgml +++ b/doc/src/sgml/ref/end.sgml @@ -62,7 +62,7 @@ END [ WORK | TRANSACTION ] </para> <para> - Issuing <command>END</> when not inside a transaction does + Issuing <command>END</command> when not inside a transaction does no harm, but it will provoke a warning message. </para> </refsect1> diff --git a/doc/src/sgml/ref/execute.sgml b/doc/src/sgml/ref/execute.sgml index 6ab5e54fa7e..6ac413d8086 100644 --- a/doc/src/sgml/ref/execute.sgml +++ b/doc/src/sgml/ref/execute.sgml @@ -87,12 +87,12 @@ EXECUTE <replaceable class="parameter">name</replaceable> [ ( <replaceable class <title>Outputs</title> <para> The command tag returned by <command>EXECUTE</command> - is that of the prepared statement, and not <literal>EXECUTE</>. + is that of the prepared statement, and not <literal>EXECUTE</literal>. </para> </refsect1> <refsect1> - <title>Examples</> + <title>Examples</title> <para> Examples are given in the <xref linkend="sql-prepare-examples" endterm="sql-prepare-examples-title"> section of the <xref diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 42191809436..bbf2e11cbb9 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -160,15 +160,15 @@ ROLLBACK; shared blocks hit, read, dirtied, and written, the number of local blocks hit, read, dirtied, and written, and the number of temp blocks read and written. - A <emphasis>hit</> means that a read was avoided because the block was + A <emphasis>hit</emphasis> means that a read was avoided because the block was found already in cache when needed. Shared blocks contain data from regular tables and indexes; local blocks contain data from temporary tables and indexes; while temp blocks contain short-term working data used in sorts, hashes, Materialize plan nodes, and similar cases. - The number of blocks <emphasis>dirtied</> indicates the number of + The number of blocks <emphasis>dirtied</emphasis> indicates the number of previously unmodified blocks that were changed by this query; while the - number of blocks <emphasis>written</> indicates the number of + number of blocks <emphasis>written</emphasis> indicates the number of previously-dirtied blocks evicted from cache by this backend during query processing. The number of blocks shown for an @@ -229,9 +229,9 @@ ROLLBACK; <listitem> <para> Specifies whether the selected option should be turned on or off. - You can write <literal>TRUE</literal>, <literal>ON</>, or + You can write <literal>TRUE</literal>, <literal>ON</literal>, or <literal>1</literal> to enable the option, and <literal>FALSE</literal>, - <literal>OFF</>, or <literal>0</literal> to disable it. The + <literal>OFF</literal>, or <literal>0</literal> to disable it. The <replaceable class="parameter">boolean</replaceable> value can also be omitted, in which case <literal>TRUE</literal> is assumed. </para> @@ -242,10 +242,10 @@ ROLLBACK; <term><replaceable class="parameter">statement</replaceable></term> <listitem> <para> - Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>, - <command>DELETE</>, <command>VALUES</>, <command>EXECUTE</>, - <command>DECLARE</>, <command>CREATE TABLE AS</>, or - <command>CREATE MATERIALIZED VIEW AS</> statement, whose execution + Any <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>, + <command>DELETE</command>, <command>VALUES</command>, <command>EXECUTE</command>, + <command>DECLARE</command>, <command>CREATE TABLE AS</command>, or + <command>CREATE MATERIALIZED VIEW AS</command> statement, whose execution plan you wish to see. </para> </listitem> diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index 7651dcd0f82..fb79a1ac61a 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -57,20 +57,20 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <para> A cursor has an associated position, which is used by - <command>FETCH</>. The cursor position can be before the first row of the + <command>FETCH</command>. The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result. When created, a cursor is positioned before the first row. After fetching some rows, the cursor is positioned on the row most recently - retrieved. If <command>FETCH</> runs off the end of the available rows + retrieved. If <command>FETCH</command> runs off the end of the available rows then the cursor is left positioned after the last row, or before the first - row if fetching backward. <command>FETCH ALL</> or <command>FETCH BACKWARD - ALL</> will always leave the cursor positioned after the last row or before + row if fetching backward. <command>FETCH ALL</command> or <command>FETCH BACKWARD + ALL</command> will always leave the cursor positioned after the last row or before the first row. </para> <para> - The forms <literal>NEXT</>, <literal>PRIOR</>, <literal>FIRST</>, - <literal>LAST</>, <literal>ABSOLUTE</>, <literal>RELATIVE</> fetch + The forms <literal>NEXT</literal>, <literal>PRIOR</literal>, <literal>FIRST</literal>, + <literal>LAST</literal>, <literal>ABSOLUTE</literal>, <literal>RELATIVE</literal> fetch a single row after moving the cursor appropriately. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as @@ -78,7 +78,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < </para> <para> - The forms using <literal>FORWARD</> and <literal>BACKWARD</> + The forms using <literal>FORWARD</literal> and <literal>BACKWARD</literal> retrieve the indicated number of rows moving in the forward or backward direction, leaving the cursor positioned on the last-returned row (or after/before all rows, if the <replaceable @@ -87,8 +87,8 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < </para> <para> - <literal>RELATIVE 0</>, <literal>FORWARD 0</>, and - <literal>BACKWARD 0</> all request fetching the current row without + <literal>RELATIVE 0</literal>, <literal>FORWARD 0</literal>, and + <literal>BACKWARD 0</literal> all request fetching the current row without moving the cursor, that is, re-fetching the most recently fetched row. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned. @@ -97,7 +97,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <note> <para> This page describes usage of cursors at the SQL command level. - If you are trying to use cursors inside a <application>PL/pgSQL</> + If you are trying to use cursors inside a <application>PL/pgSQL</application> function, the rules are different — see <xref linkend="plpgsql-cursors">. </para> @@ -274,10 +274,10 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <listitem> <para><replaceable class="parameter">count</replaceable> is a possibly-signed integer constant, determining the location or - number of rows to fetch. For <literal>FORWARD</> and - <literal>BACKWARD</> cases, specifying a negative <replaceable + number of rows to fetch. For <literal>FORWARD</literal> and + <literal>BACKWARD</literal> cases, specifying a negative <replaceable class="parameter">count</replaceable> is equivalent to changing - the sense of <literal>FORWARD</> and <literal>BACKWARD</>. + the sense of <literal>FORWARD</literal> and <literal>BACKWARD</literal>. </para> </listitem> </varlistentry> @@ -297,7 +297,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <title>Outputs</title> <para> - On successful completion, a <command>FETCH</> command returns a command + On successful completion, a <command>FETCH</command> command returns a command tag of the form <screen> FETCH <replaceable class="parameter">count</replaceable> @@ -315,8 +315,8 @@ FETCH <replaceable class="parameter">count</replaceable> <para> The cursor should be declared with the <literal>SCROLL</literal> - option if one intends to use any variants of <command>FETCH</> - other than <command>FETCH NEXT</> or <command>FETCH FORWARD</> with + option if one intends to use any variants of <command>FETCH</command> + other than <command>FETCH NEXT</command> or <command>FETCH FORWARD</command> with a positive count. For simple queries <productname>PostgreSQL</productname> will allow backwards fetch from cursors not declared with <literal>SCROLL</literal>, but this @@ -400,8 +400,8 @@ COMMIT WORK; </para> <para> - The SQL standard allows only <literal>FROM</> preceding the cursor - name; the option to use <literal>IN</>, or to leave them out altogether, is + The SQL standard allows only <literal>FROM</literal> preceding the cursor + name; the option to use <literal>IN</literal>, or to leave them out altogether, is an extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 385cfe6a9ca..fd9fe03a6ad 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -116,7 +116,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace There is also an option to grant privileges on all objects of the same type within one or more schemas. This functionality is currently supported only for tables, sequences, and functions (but note that <literal>ALL - TABLES</> is considered to include views and foreign tables). + TABLES</literal> is considered to include views and foreign tables). </para> <para> @@ -174,7 +174,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace (including domains). The object owner can, of course, <command>REVOKE</command> both default and expressly granted privileges. (For maximum - security, issue the <command>REVOKE</> in the same transaction that + security, issue the <command>REVOKE</command> in the same transaction that creates the object; then there is no window in which another user can use the object.) Also, these initial default privilege settings can be changed using the @@ -211,7 +211,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-insert"> of a new row into the specified table. If specific columns are listed, - only those columns may be assigned to in the <command>INSERT</> + only those columns may be assigned to in the <command>INSERT</command> command (other columns will therefore receive default values). Also allows <xref linkend="sql-copy"> FROM. </para> @@ -224,8 +224,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-update"> of any column, or the specific columns listed, of the specified table. - (In practice, any nontrivial <command>UPDATE</> command will require - <literal>SELECT</> privilege as well, since it must reference table + (In practice, any nontrivial <command>UPDATE</command> command will require + <literal>SELECT</literal> privilege as well, since it must reference table columns to determine which rows to update, and/or to compute new values for columns.) <literal>SELECT ... FOR UPDATE</literal> @@ -246,8 +246,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-delete"> of a row from the specified table. - (In practice, any nontrivial <command>DELETE</> command will require - <literal>SELECT</> privilege as well, since it must reference table + (In practice, any nontrivial <command>DELETE</command> command will require + <literal>SELECT</literal> privilege as well, since it must reference table columns to determine which rows to delete.) </para> </listitem> @@ -292,7 +292,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> For schemas, allows new objects to be created within the schema. - To rename an existing object, you must own the object <emphasis>and</> + To rename an existing object, you must own the object <emphasis>and</emphasis> have this privilege for the containing schema. </para> <para> @@ -310,7 +310,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows the user to connect to the specified database. This privilege is checked at connection startup (in addition to checking - any restrictions imposed by <filename>pg_hba.conf</>). + any restrictions imposed by <filename>pg_hba.conf</filename>). </para> </listitem> </varlistentry> @@ -348,7 +348,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> For schemas, allows access to objects contained in the specified schema (assuming that the objects' own privilege requirements are - also met). Essentially this allows the grantee to <quote>look up</> + also met). Essentially this allows the grantee to <quote>look up</quote> objects within the schema. Without this permission, it is still possible to see the object names, e.g. by querying the system tables. Also, after revoking this permission, existing backends might have @@ -416,14 +416,14 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace OPTION</literal> on itself, but it may grant or revoke membership in itself from a database session where the session user matches the role. Database superusers can grant or revoke membership in any role - to anyone. Roles having <literal>CREATEROLE</> privilege can grant + to anyone. Roles having <literal>CREATEROLE</literal> privilege can grant or revoke membership in any role that is not a superuser. </para> <para> Unlike the case with privileges, membership in a role cannot be granted - to <literal>PUBLIC</>. Note also that this form of the command does not - allow the noise word <literal>GROUP</>. + to <literal>PUBLIC</literal>. Note also that this form of the command does not + allow the noise word <literal>GROUP</literal>. </para> </refsect2> </refsect1> @@ -440,13 +440,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Since <productname>PostgreSQL</productname> 8.1, the concepts of users and groups have been unified into a single kind of entity called a role. - It is therefore no longer necessary to use the keyword <literal>GROUP</> - to identify whether a grantee is a user or a group. <literal>GROUP</> + It is therefore no longer necessary to use the keyword <literal>GROUP</literal> + to identify whether a grantee is a user or a group. <literal>GROUP</literal> is still allowed in the command, but it is a noise word. </para> <para> - A user may perform <command>SELECT</>, <command>INSERT</>, etc. on a + A user may perform <command>SELECT</command>, <command>INSERT</command>, etc. on a column if they hold that privilege for either the specific column or its whole table. Granting the privilege at the table level and then revoking it for one column will not do what one might wish: the @@ -454,12 +454,12 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> - When a non-owner of an object attempts to <command>GRANT</> privileges + When a non-owner of an object attempts to <command>GRANT</command> privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object. As long as some privilege is available, the command will proceed, but it will grant only those privileges for which the user has grant options. The <command>GRANT ALL - PRIVILEGES</> forms will issue a warning message if no grant options are + PRIVILEGES</command> forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held. (In principle these statements apply to the object owner as well, but @@ -470,13 +470,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> It should be noted that database superusers can access all objects regardless of object privilege settings. This - is comparable to the rights of <literal>root</> in a Unix system. - As with <literal>root</>, it's unwise to operate as a superuser + is comparable to the rights of <literal>root</literal> in a Unix system. + As with <literal>root</literal>, it's unwise to operate as a superuser except when absolutely necessary. </para> <para> - If a superuser chooses to issue a <command>GRANT</> or <command>REVOKE</> + If a superuser chooses to issue a <command>GRANT</command> or <command>REVOKE</command> command, the command is performed as though it were issued by the owner of the affected object. In particular, privileges granted via such a command will appear to have been granted by the object owner. @@ -485,32 +485,32 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> - <command>GRANT</> and <command>REVOKE</> can also be done by a role + <command>GRANT</command> and <command>REVOKE</command> can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges <literal>WITH GRANT OPTION</literal> on the object. In this case the privileges will be recorded as having been granted by the role that actually owns the object or holds the privileges <literal>WITH GRANT OPTION</literal>. For example, if table - <literal>t1</> is owned by role <literal>g1</>, of which role - <literal>u1</> is a member, then <literal>u1</> can grant privileges - on <literal>t1</> to <literal>u2</>, but those privileges will appear - to have been granted directly by <literal>g1</>. Any other member - of role <literal>g1</> could revoke them later. + <literal>t1</literal> is owned by role <literal>g1</literal>, of which role + <literal>u1</literal> is a member, then <literal>u1</literal> can grant privileges + on <literal>t1</literal> to <literal>u2</literal>, but those privileges will appear + to have been granted directly by <literal>g1</literal>. Any other member + of role <literal>g1</literal> could revoke them later. </para> <para> - If the role executing <command>GRANT</> holds the required privileges + If the role executing <command>GRANT</command> holds the required privileges indirectly via more than one role membership path, it is unspecified which containing role will be recorded as having done the grant. In such - cases it is best practice to use <command>SET ROLE</> to become the - specific role you want to do the <command>GRANT</> as. + cases it is best practice to use <command>SET ROLE</command> to become the + specific role you want to do the <command>GRANT</command> as. </para> <para> Granting permission on a table does not automatically extend permissions to any sequences used by the table, including - sequences tied to <type>SERIAL</> columns. Permissions on + sequences tied to <type>SERIAL</type> columns. Permissions on sequences must be set separately. </para> @@ -551,8 +551,8 @@ rolename=xxxx -- privileges granted to a role /yyyy -- role that granted this privilege </literallayout> - The above example display would be seen by user <literal>miriam</> after - creating table <literal>mytable</> and doing: + The above example display would be seen by user <literal>miriam</literal> after + creating table <literal>mytable</literal> and doing: <programlisting> GRANT SELECT ON mytable TO PUBLIC; @@ -562,31 +562,31 @@ GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw; </para> <para> - For non-table objects there are other <command>\d</> commands + For non-table objects there are other <command>\d</command> commands that can display their privileges. </para> <para> - If the <quote>Access privileges</> column is empty for a given object, + If the <quote>Access privileges</quote> column is empty for a given object, it means the object has default privileges (that is, its privileges column is null). Default privileges always include all privileges for the owner, - and can include some privileges for <literal>PUBLIC</> depending on the - object type, as explained above. The first <command>GRANT</> or - <command>REVOKE</> on an object + and can include some privileges for <literal>PUBLIC</literal> depending on the + object type, as explained above. The first <command>GRANT</command> or + <command>REVOKE</command> on an object will instantiate the default privileges (producing, for example, - <literal>{miriam=arwdDxt/miriam}</>) and then modify them per the + <literal>{miriam=arwdDxt/miriam}</literal>) and then modify them per the specified request. Similarly, entries are shown in <quote>Column access - privileges</> only for columns with nondefault privileges. - (Note: for this purpose, <quote>default privileges</> always means the + privileges</quote> only for columns with nondefault privileges. + (Note: for this purpose, <quote>default privileges</quote> always means the built-in default privileges for the object's type. An object whose - privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</> + privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</command> command will always be shown with an explicit privilege entry that - includes the effects of the <command>ALTER</>.) + includes the effects of the <command>ALTER</command>.) </para> <para> Notice that the owner's implicit grant options are not marked in the - access privileges display. A <literal>*</> will appear only when + access privileges display. A <literal>*</literal> will appear only when grant options have been explicitly granted to someone. </para> </refsect1> @@ -617,7 +617,7 @@ GRANT ALL PRIVILEGES ON kinds TO manuel; </para> <para> - Grant membership in role <literal>admins</> to user <literal>joe</>: + Grant membership in role <literal>admins</literal> to user <literal>joe</literal>: <programlisting> GRANT admins TO joe; @@ -637,14 +637,14 @@ GRANT admins TO joe; <para> <productname>PostgreSQL</productname> allows an object owner to revoke their own ordinary privileges: for example, a table owner can make the table - read-only to themselves by revoking their own <literal>INSERT</>, - <literal>UPDATE</>, <literal>DELETE</>, and <literal>TRUNCATE</> + read-only to themselves by revoking their own <literal>INSERT</literal>, + <literal>UPDATE</literal>, <literal>DELETE</literal>, and <literal>TRUNCATE</literal> privileges. This is not possible according to the SQL standard. The reason is that <productname>PostgreSQL</productname> treats the owner's privileges as having been granted by the owner to themselves; therefore they can revoke them too. In the SQL standard, the owner's privileges are - granted by an assumed entity <quote>_SYSTEM</>. Not being - <quote>_SYSTEM</>, the owner cannot revoke these rights. + granted by an assumed entity <quote>_SYSTEM</quote>. Not being + <quote>_SYSTEM</quote>, the owner cannot revoke these rights. </para> <para> diff --git a/doc/src/sgml/ref/import_foreign_schema.sgml b/doc/src/sgml/ref/import_foreign_schema.sgml index f22893f1373..9bc83f1c6a6 100644 --- a/doc/src/sgml/ref/import_foreign_schema.sgml +++ b/doc/src/sgml/ref/import_foreign_schema.sgml @@ -124,9 +124,9 @@ IMPORT FOREIGN SCHEMA <replaceable class="parameter">remote_schema</replaceable> <title>Examples</title> <para> - Import table definitions from a remote schema <structname>foreign_films</> - on server <structname>film_server</>, creating the foreign tables in - local schema <structname>films</>: + Import table definitions from a remote schema <structname>foreign_films</structname> + on server <structname>film_server</structname>, creating the foreign tables in + local schema <structname>films</structname>: <programlisting> IMPORT FOREIGN SCHEMA foreign_films @@ -135,8 +135,8 @@ IMPORT FOREIGN SCHEMA foreign_films </para> <para> - As above, but import only the two tables <structname>actors</> and - <literal>directors</> (if they exist): + As above, but import only the two tables <structname>actors</structname> and + <literal>directors</literal> (if they exist): <programlisting> IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors) @@ -149,8 +149,8 @@ IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors) <para> The <command>IMPORT FOREIGN SCHEMA</command> command conforms to the - <acronym>SQL</acronym> standard, except that the <literal>OPTIONS</> - clause is a <productname>PostgreSQL</> extension. + <acronym>SQL</acronym> standard, except that the <literal>OPTIONS</literal> + clause is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 732fecab8ec..6696d4d05ab 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -79,8 +79,8 @@ PostgreSQL documentation <para> <command>initdb</command> initializes the database cluster's default locale and character set encoding. The character set encoding, - collation order (<literal>LC_COLLATE</>) and character set classes - (<literal>LC_CTYPE</>, e.g. upper, lower, digit) can be set separately + collation order (<literal>LC_COLLATE</literal>) and character set classes + (<literal>LC_CTYPE</literal>, e.g. upper, lower, digit) can be set separately for a database when it is created. <command>initdb</command> determines those settings for the <literal>template1</literal> database, which will serve as the default for all other databases. @@ -89,7 +89,7 @@ PostgreSQL documentation <para> To alter the default collation order or character set classes, use the <option>--lc-collate</option> and <option>--lc-ctype</option> options. - Collation orders other than <literal>C</> or <literal>POSIX</> also have + Collation orders other than <literal>C</literal> or <literal>POSIX</literal> also have a performance penalty. For these reasons it is important to choose the right locale when running <command>initdb</command>. </para> @@ -98,8 +98,8 @@ PostgreSQL documentation The remaining locale categories can be changed later when the server is started. You can also use <option>--locale</option> to set the default for all locale categories, including collation order and - character set classes. All server locale values (<literal>lc_*</>) can - be displayed via <command>SHOW ALL</>. + character set classes. All server locale values (<literal>lc_*</literal>) can + be displayed via <command>SHOW ALL</command>. More details can be found in <xref linkend="locale">. </para> @@ -121,7 +121,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the default authentication method for local - users used in <filename>pg_hba.conf</> (<literal>host</literal> + users used in <filename>pg_hba.conf</filename> (<literal>host</literal> and <literal>local</literal> lines). <command>initdb</command> will prepopulate <filename>pg_hba.conf</filename> entries using the specified authentication method for non-replication as well as @@ -129,8 +129,8 @@ PostgreSQL documentation </para> <para> - Do not use <literal>trust</> unless you trust all local users on your - system. <literal>trust</> is the default for ease of installation. + Do not use <literal>trust</literal> unless you trust all local users on your + system. <literal>trust</literal> is the default for ease of installation. </para> </listitem> </varlistentry> @@ -140,7 +140,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the authentication method for local users via - TCP/IP connections used in <filename>pg_hba.conf</> + TCP/IP connections used in <filename>pg_hba.conf</filename> (<literal>host</literal> lines). </para> </listitem> @@ -151,7 +151,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the authentication method for local users via - Unix-domain socket connections used in <filename>pg_hba.conf</> + Unix-domain socket connections used in <filename>pg_hba.conf</filename> (<literal>local</literal> lines). </para> </listitem> @@ -255,7 +255,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--pwfile=<replaceable>filename</></option></term> + <term><option>--pwfile=<replaceable>filename</replaceable></option></term> <listitem> <para> Makes <command>initdb</command> read the database superuser's password @@ -270,14 +270,14 @@ PostgreSQL documentation <listitem> <para> Safely write all database files to disk and exit. This does not - perform any of the normal <application>initdb</> operations. + perform any of the normal <application>initdb</application> operations. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-T <replaceable>config</></option></term> - <term><option>--text-search-config=<replaceable>config</></option></term> + <term><option>-T <replaceable>config</replaceable></option></term> + <term><option>--text-search-config=<replaceable>config</replaceable></option></term> <listitem> <para> Sets the default text search configuration. @@ -319,7 +319,7 @@ PostgreSQL documentation <term><option>--wal-segsize=<replaceable>SEGSIZE</replaceable></option></term> <listitem> <para> - Set the <firstterm>WAL segment size</>, in megabytes. This is + Set the <firstterm>WAL segment size</firstterm>, in megabytes. This is the size of each individual file in the WAL log. It may be useful to adjust this size to control the granularity of WAL log shipping. This option can only be set during initialization, and cannot be @@ -395,8 +395,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>initdb</application> version and exit. @@ -405,8 +405,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>initdb</application> command line @@ -449,8 +449,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index ce037e59027..7f44ec31d15 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -56,10 +56,10 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> The target column names can be listed in any order. If no list of column names is given at all, the default is all the columns of the - table in their declared order; or the first <replaceable>N</> column - names, if there are only <replaceable>N</> columns supplied by the - <literal>VALUES</> clause or <replaceable>query</>. The values - supplied by the <literal>VALUES</> clause or <replaceable>query</> are + table in their declared order; or the first <replaceable>N</replaceable> column + names, if there are only <replaceable>N</replaceable> columns supplied by the + <literal>VALUES</literal> clause or <replaceable>query</replaceable>. The values + supplied by the <literal>VALUES</literal> clause or <replaceable>query</replaceable> are associated with the explicit or implicit column list left-to-right. </para> @@ -75,21 +75,21 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac </para> <para> - <literal>ON CONFLICT</> can be used to specify an alternative + <literal>ON CONFLICT</literal> can be used to specify an alternative action to raising a unique constraint or exclusion constraint violation error. (See <xref linkend="sql-on-conflict" endterm="sql-on-conflict-title"> below.) </para> <para> - The optional <literal>RETURNING</> clause causes <command>INSERT</> + The optional <literal>RETURNING</literal> clause causes <command>INSERT</command> to compute and return value(s) based on each row actually inserted - (or updated, if an <literal>ON CONFLICT DO UPDATE</> clause was + (or updated, if an <literal>ON CONFLICT DO UPDATE</literal> clause was used). This is primarily useful for obtaining values that were supplied by defaults, such as a serial sequence number. However, any expression using the table's columns is allowed. The syntax of - the <literal>RETURNING</> list is identical to that of the output - list of <command>SELECT</>. Only rows that were successfully + the <literal>RETURNING</literal> list is identical to that of the output + list of <command>SELECT</command>. Only rows that were successfully inserted or updated will be returned. For example, if a row was locked but not updated because an <literal>ON CONFLICT DO UPDATE ... WHERE</literal> clause <replaceable @@ -99,7 +99,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> You must have <literal>INSERT</literal> privilege on a table in - order to insert into it. If <literal>ON CONFLICT DO UPDATE</> is + order to insert into it. If <literal>ON CONFLICT DO UPDATE</literal> is present, <literal>UPDATE</literal> privilege on the table is also required. </para> @@ -107,17 +107,17 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> If a column list is specified, you only need <literal>INSERT</literal> privilege on the listed columns. - Similarly, when <literal>ON CONFLICT DO UPDATE</> is specified, you - only need <literal>UPDATE</> privilege on the column(s) that are - listed to be updated. However, <literal>ON CONFLICT DO UPDATE</> - also requires <literal>SELECT</> privilege on any column whose - values are read in the <literal>ON CONFLICT DO UPDATE</> - expressions or <replaceable>condition</>. + Similarly, when <literal>ON CONFLICT DO UPDATE</literal> is specified, you + only need <literal>UPDATE</literal> privilege on the column(s) that are + listed to be updated. However, <literal>ON CONFLICT DO UPDATE</literal> + also requires <literal>SELECT</literal> privilege on any column whose + values are read in the <literal>ON CONFLICT DO UPDATE</literal> + expressions or <replaceable>condition</replaceable>. </para> <para> - Use of the <literal>RETURNING</> clause requires <literal>SELECT</> - privilege on all columns mentioned in <literal>RETURNING</>. + Use of the <literal>RETURNING</literal> clause requires <literal>SELECT</literal> + privilege on all columns mentioned in <literal>RETURNING</literal>. If you use the <replaceable class="parameter">query</replaceable> clause to insert rows from a query, you of course need to have <literal>SELECT</literal> privilege on @@ -144,7 +144,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <listitem> <para> The <literal>WITH</literal> clause allows you to specify one or more - subqueries that can be referenced by name in the <command>INSERT</> + subqueries that can be referenced by name in the <command>INSERT</command> query. See <xref linkend="queries-with"> and <xref linkend="sql-select"> for details. </para> @@ -175,8 +175,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac A substitute name for <replaceable class="parameter">table_name</replaceable>. When an alias is provided, it completely hides the actual name of the table. - This is particularly useful when <literal>ON CONFLICT DO UPDATE</> - targets a table named <varname>excluded</>, since that will otherwise + This is particularly useful when <literal>ON CONFLICT DO UPDATE</literal> + targets a table named <varname>excluded</varname>, since that will otherwise be taken as the name of the special table representing rows proposed for insertion. </para> @@ -193,11 +193,11 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac can be qualified with a subfield name or array subscript, if needed. (Inserting into only some fields of a composite column leaves the other fields null.) When referencing a - column with <literal>ON CONFLICT DO UPDATE</>, do not include + column with <literal>ON CONFLICT DO UPDATE</literal>, do not include the table's name in the specification of a target column. For example, <literal>INSERT INTO table_name ... ON CONFLICT DO UPDATE - SET table_name.col = 1</> is invalid (this follows the general - behavior for <command>UPDATE</>). + SET table_name.col = 1</literal> is invalid (this follows the general + behavior for <command>UPDATE</command>). </para> </listitem> </varlistentry> @@ -281,11 +281,11 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <listitem> <para> An expression to be computed and returned by the - <command>INSERT</> command after each row is inserted or + <command>INSERT</command> command after each row is inserted or updated. The expression can use any column names of the table named by <replaceable class="parameter">table_name</replaceable>. Write - <literal>*</> to return all columns of the inserted or updated + <literal>*</literal> to return all columns of the inserted or updated row(s). </para> </listitem> @@ -386,7 +386,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac UPDATE</literal> have access to the existing row using the table's name (or an alias), and to rows proposed for insertion using the special <varname>excluded</varname> table. - <literal>SELECT</> privilege is required on any column in the + <literal>SELECT</literal> privilege is required on any column in the target table where corresponding <varname>excluded</varname> columns are read. </para> @@ -406,7 +406,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac The name of a <replaceable class="parameter">table_name</replaceable> column. Used to infer arbiter indexes. Follows <command>CREATE - INDEX</command> format. <literal>SELECT</> privilege on + INDEX</command> format. <literal>SELECT</literal> privilege on <replaceable class="parameter">index_column_name</replaceable> is required. </para> @@ -422,7 +422,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac infer expressions on <replaceable class="parameter">table_name</replaceable> columns appearing within index definitions (not simple columns). Follows - <command>CREATE INDEX</command> format. <literal>SELECT</> + <command>CREATE INDEX</command> format. <literal>SELECT</literal> privilege on any column appearing within <replaceable class="parameter">index_expression</replaceable> is required. </para> @@ -469,7 +469,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac Used to allow inference of partial unique indexes. Any indexes that satisfy the predicate (which need not actually be partial indexes) can be inferred. Follows <command>CREATE - INDEX</command> format. <literal>SELECT</> privilege on any + INDEX</command> format. <literal>SELECT</literal> privilege on any column appearing within <replaceable class="parameter">index_predicate</replaceable> is required. </para> @@ -494,7 +494,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac An expression that returns a value of type <type>boolean</type>. Only rows for which this expression returns <literal>true</literal> will be updated, although all - rows will be locked when the <literal>ON CONFLICT DO UPDATE</> + rows will be locked when the <literal>ON CONFLICT DO UPDATE</literal> action is taken. Note that <replaceable>condition</replaceable> is evaluated last, after a conflict has been identified as a candidate to update. @@ -510,7 +510,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac </para> <para> - <command>INSERT</command> with an <literal>ON CONFLICT DO UPDATE</> + <command>INSERT</command> with an <literal>ON CONFLICT DO UPDATE</literal> clause is a <quote>deterministic</quote> statement. This means that the command will not be allowed to affect any single existing row more than once; a cardinality violation error will be raised @@ -538,7 +538,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <title>Outputs</title> <para> - On successful completion, an <command>INSERT</> command returns a command + On successful completion, an <command>INSERT</command> command returns a command tag of the form <screen> INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable> @@ -554,10 +554,10 @@ INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</repl </para> <para> - If the <command>INSERT</> command contains a <literal>RETURNING</> - clause, the result will be similar to that of a <command>SELECT</> + If the <command>INSERT</command> command contains a <literal>RETURNING</literal> + clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the - <literal>RETURNING</> list, computed over the row(s) inserted or + <literal>RETURNING</literal> list, computed over the row(s) inserted or updated by the command. </para> </refsect1> @@ -616,7 +616,7 @@ INSERT INTO films DEFAULT VALUES; </para> <para> - To insert multiple rows using the multirow <command>VALUES</> syntax: + To insert multiple rows using the multirow <command>VALUES</command> syntax: <programlisting> INSERT INTO films (code, title, did, date_prod, kind) VALUES @@ -675,7 +675,7 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd; Insert or update new distributors as appropriate. Assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column. Note that the special - <varname>excluded</> table is used to reference values originally + <varname>excluded</varname> table is used to reference values originally proposed for insertion: <programlisting> INSERT INTO distributors (did, dname) @@ -697,7 +697,7 @@ INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH') <para> Insert or update new distributors as appropriate. Example assumes a unique index has been defined that constrains values appearing in - the <literal>did</literal> column. <literal>WHERE</> clause is + the <literal>did</literal> column. <literal>WHERE</literal> clause is used to limit the rows actually updated (any existing row not updated will still be locked, though): <programlisting> @@ -734,13 +734,13 @@ INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International') <para> <command>INSERT</command> conforms to the SQL standard, except that - the <literal>RETURNING</> clause is a + the <literal>RETURNING</literal> clause is a <productname>PostgreSQL</productname> extension, as is the ability - to use <literal>WITH</> with <command>INSERT</>, and the ability to - specify an alternative action with <literal>ON CONFLICT</>. + to use <literal>WITH</literal> with <command>INSERT</command>, and the ability to + specify an alternative action with <literal>ON CONFLICT</literal>. Also, the case in which a column name list is omitted, but not all the columns are - filled from the <literal>VALUES</> clause or <replaceable>query</>, + filled from the <literal>VALUES</literal> clause or <replaceable>query</replaceable>, is disallowed by the standard. </para> diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 76215716d61..65275627174 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -54,12 +54,12 @@ LISTEN <replaceable class="parameter">channel</replaceable> <para> The method a client application must use to detect notification events depends on which <productname>PostgreSQL</productname> application programming interface it - uses. With the <application>libpq</> library, the application issues + uses. With the <application>libpq</application> library, the application issues <command>LISTEN</command> as an ordinary SQL command, and then must periodically call the function <function>PQnotifies</function> to find out whether any notification events have been received. Other interfaces such as - <application>libpgtcl</> provide higher-level methods for handling notify events; indeed, - with <application>libpgtcl</> the application programmer should not even issue + <application>libpgtcl</application> provide higher-level methods for handling notify events; indeed, + with <application>libpgtcl</application> the application programmer should not even issue <command>LISTEN</command> or <command>UNLISTEN</command> directly. See the documentation for the interface you are using for more details. </para> diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index 2be28e6d15a..b9e3fe8b255 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -28,12 +28,12 @@ LOAD '<replaceable class="parameter">filename</replaceable>' <title>Description</title> <para> - This command loads a shared library file into the <productname>PostgreSQL</> + This command loads a shared library file into the <productname>PostgreSQL</productname> server's address space. If the file has been loaded already, the command does nothing. Shared library files that contain C functions are automatically loaded whenever one of their functions is called. - Therefore, an explicit <command>LOAD</> is usually only needed to - load a library that modifies the server's behavior through <quote>hooks</> + Therefore, an explicit <command>LOAD</command> is usually only needed to + load a library that modifies the server's behavior through <quote>hooks</quote> rather than providing a set of functions. </para> @@ -47,15 +47,15 @@ LOAD '<replaceable class="parameter">filename</replaceable>' </para> <indexterm> - <primary><filename>$libdir/plugins</></primary> + <primary><filename>$libdir/plugins</filename></primary> </indexterm> <para> - Non-superusers can only apply <command>LOAD</> to library files - located in <filename>$libdir/plugins/</> — the specified + Non-superusers can only apply <command>LOAD</command> to library files + located in <filename>$libdir/plugins/</filename> — the specified <replaceable class="parameter">filename</replaceable> must begin with exactly that string. (It is the database administrator's - responsibility to ensure that only <quote>safe</> libraries + responsibility to ensure that only <quote>safe</quote> libraries are installed there.) </para> </refsect1> diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index f1dbb8e65a8..6d68ec6c53b 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -51,13 +51,13 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] restrictive lock mode possible. <command>LOCK TABLE</command> provides for cases when you might need more restrictive locking. For example, suppose an application runs a transaction at the - <literal>READ COMMITTED</> isolation level and needs to ensure that + <literal>READ COMMITTED</literal> isolation level and needs to ensure that data in a table remains stable for the duration of the transaction. - To achieve this you could obtain <literal>SHARE</> lock mode over the + To achieve this you could obtain <literal>SHARE</literal> lock mode over the table before querying. This will prevent concurrent data changes and ensure subsequent reads of the table see a stable view of - committed data, because <literal>SHARE</> lock mode conflicts with - the <literal>ROW EXCLUSIVE</> lock acquired by writers, and your + committed data, because <literal>SHARE</literal> lock mode conflicts with + the <literal>ROW EXCLUSIVE</literal> lock acquired by writers, and your <command>LOCK TABLE <replaceable class="parameter">name</replaceable> IN SHARE MODE</command> statement will wait until any concurrent holders of <literal>ROW @@ -68,28 +68,28 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <para> To achieve a similar effect when running a transaction at the - <literal>REPEATABLE READ</> or <literal>SERIALIZABLE</> - isolation level, you have to execute the <command>LOCK TABLE</> statement - before executing any <command>SELECT</> or data modification statement. - A <literal>REPEATABLE READ</> or <literal>SERIALIZABLE</> transaction's + <literal>REPEATABLE READ</literal> or <literal>SERIALIZABLE</literal> + isolation level, you have to execute the <command>LOCK TABLE</command> statement + before executing any <command>SELECT</command> or data modification statement. + A <literal>REPEATABLE READ</literal> or <literal>SERIALIZABLE</literal> transaction's view of data will be frozen when its first - <command>SELECT</> or data modification statement begins. A <command>LOCK - TABLE</> later in the transaction will still prevent concurrent writes + <command>SELECT</command> or data modification statement begins. A <command>LOCK + TABLE</command> later in the transaction will still prevent concurrent writes — but it won't ensure that what the transaction reads corresponds to the latest committed values. </para> <para> If a transaction of this sort is going to change the data in the - table, then it should use <literal>SHARE ROW EXCLUSIVE</> lock mode - instead of <literal>SHARE</> mode. This ensures that only one + table, then it should use <literal>SHARE ROW EXCLUSIVE</literal> lock mode + instead of <literal>SHARE</literal> mode. This ensures that only one transaction of this type runs at a time. Without this, a deadlock - is possible: two transactions might both acquire <literal>SHARE</> - mode, and then be unable to also acquire <literal>ROW EXCLUSIVE</> + is possible: two transactions might both acquire <literal>SHARE</literal> + mode, and then be unable to also acquire <literal>ROW EXCLUSIVE</literal> mode to actually perform their updates. (Note that a transaction's own locks never conflict, so a transaction can acquire <literal>ROW - EXCLUSIVE</> mode when it holds <literal>SHARE</> mode — but not - if anyone else holds <literal>SHARE</> mode.) To avoid deadlocks, + EXCLUSIVE</literal> mode when it holds <literal>SHARE</literal> mode — but not + if anyone else holds <literal>SHARE</literal> mode.) To avoid deadlocks, make sure all transactions acquire locks on the same objects in the same order, and if multiple lock modes are involved for a single object, then transactions should always acquire the most @@ -111,16 +111,16 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <listitem> <para> The name (optionally schema-qualified) of an existing table to - lock. If <literal>ONLY</> is specified before the table name, only that - table is locked. If <literal>ONLY</> is not specified, the table and all - its descendant tables (if any) are locked. Optionally, <literal>*</> + lock. If <literal>ONLY</literal> is specified before the table name, only that + table is locked. If <literal>ONLY</literal> is not specified, the table and all + its descendant tables (if any) are locked. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> <para> - The command <literal>LOCK TABLE a, b;</> is equivalent to - <literal>LOCK TABLE a; LOCK TABLE b;</>. The tables are locked + The command <literal>LOCK TABLE a, b;</literal> is equivalent to + <literal>LOCK TABLE a; LOCK TABLE b;</literal>. The tables are locked one-by-one in the order specified in the <command>LOCK TABLE</command> command. </para> @@ -160,18 +160,18 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <title>Notes</title> <para> - <literal>LOCK TABLE ... IN ACCESS SHARE MODE</> requires <literal>SELECT</> + <literal>LOCK TABLE ... IN ACCESS SHARE MODE</literal> requires <literal>SELECT</literal> privileges on the target table. <literal>LOCK TABLE ... IN ROW EXCLUSIVE - MODE</> requires <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, - or <literal>TRUNCATE</> privileges on the target table. All other forms of - <command>LOCK</> require table-level <literal>UPDATE</>, <literal>DELETE</>, - or <literal>TRUNCATE</> privileges. + MODE</literal> requires <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>, + or <literal>TRUNCATE</literal> privileges on the target table. All other forms of + <command>LOCK</command> require table-level <literal>UPDATE</literal>, <literal>DELETE</literal>, + or <literal>TRUNCATE</literal> privileges. </para> <para> - <command>LOCK TABLE</> is useless outside a transaction block: the lock + <command>LOCK TABLE</command> is useless outside a transaction block: the lock would remain held only to the completion of the statement. Therefore - <productname>PostgreSQL</productname> reports an error if <command>LOCK</> + <productname>PostgreSQL</productname> reports an error if <command>LOCK</command> is used outside a transaction block. Use <xref linkend="sql-begin"> and @@ -181,13 +181,13 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] </para> <para> - <command>LOCK TABLE</> only deals with table-level locks, and so - the mode names involving <literal>ROW</> are all misnomers. These + <command>LOCK TABLE</command> only deals with table-level locks, and so + the mode names involving <literal>ROW</literal> are all misnomers. These mode names should generally be read as indicating the intention of the user to acquire row-level locks within the locked table. Also, - <literal>ROW EXCLUSIVE</> mode is a shareable table lock. Keep in + <literal>ROW EXCLUSIVE</literal> mode is a shareable table lock. Keep in mind that all the lock modes have identical semantics so far as - <command>LOCK TABLE</> is concerned, differing only in the rules + <command>LOCK TABLE</command> is concerned, differing only in the rules about which modes conflict with which. For information on how to acquire an actual row-level lock, see <xref linkend="locking-rows"> and the <xref linkend="sql-for-update-share" @@ -200,7 +200,7 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <title>Examples</title> <para> - Obtain a <literal>SHARE</> lock on a primary key table when going to perform + Obtain a <literal>SHARE</literal> lock on a primary key table when going to perform inserts into a foreign key table: <programlisting> @@ -216,7 +216,7 @@ COMMIT WORK; </para> <para> - Take a <literal>SHARE ROW EXCLUSIVE</> lock on a primary key table when going to perform + Take a <literal>SHARE ROW EXCLUSIVE</literal> lock on a primary key table when going to perform a delete operation: <programlisting> @@ -240,8 +240,8 @@ COMMIT WORK; </para> <para> - Except for <literal>ACCESS SHARE</>, <literal>ACCESS EXCLUSIVE</>, - and <literal>SHARE UPDATE EXCLUSIVE</> lock modes, the + Except for <literal>ACCESS SHARE</literal>, <literal>ACCESS EXCLUSIVE</literal>, + and <literal>SHARE UPDATE EXCLUSIVE</literal> lock modes, the <productname>PostgreSQL</productname> lock modes and the <command>LOCK TABLE</command> syntax are compatible with those present in <productname>Oracle</productname>. diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 6b809b961d6..4bf78968588 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -69,7 +69,7 @@ MOVE [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <r <title>Outputs</title> <para> - On successful completion, a <command>MOVE</> command returns a command + On successful completion, a <command>MOVE</command> command returns a command tag of the form <screen> MOVE <replaceable class="parameter">count</replaceable> diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index 09debd6685f..4376b9fdd73 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -30,9 +30,9 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <para> The <command>NOTIFY</command> command sends a notification event together - with an optional <quote>payload</> string to each client application that + with an optional <quote>payload</quote> string to each client application that has previously executed - <command>LISTEN <replaceable class="parameter">channel</></command> + <command>LISTEN <replaceable class="parameter">channel</replaceable></command> for the specified channel name in the current database. Notifications are visible to all users. </para> @@ -49,7 +49,7 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <para> The information passed to the client for a notification event includes the notification channel - name, the notifying session's server process <acronym>PID</>, and the + name, the notifying session's server process <acronym>PID</acronym>, and the payload string, which is an empty string if it has not been specified. </para> @@ -115,9 +115,9 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla result in useless work, for example, reading a database table to find the same updates that that session just wrote out. It is possible to avoid such extra work by noticing whether the notifying - session's server process <acronym>PID</> (supplied in the + session's server process <acronym>PID</acronym> (supplied in the notification event message) is the same as one's own session's - <acronym>PID</> (available from <application>libpq</>). When they + <acronym>PID</acronym> (available from <application>libpq</application>). When they are the same, the notification event is one's own work bouncing back, and can be ignored. </para> @@ -139,7 +139,7 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <term><replaceable class="parameter">payload</replaceable></term> <listitem> <para> - The <quote>payload</> string to be communicated along with the + The <quote>payload</quote> string to be communicated along with the notification. This must be specified as a simple string literal. In the default configuration it must be shorter than 8000 bytes. (If binary data or large amounts of information need to be communicated, diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index f790c560034..1944c185cb9 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <cmdsynopsis> <command>pg_basebackup</command> - <arg rep="repeat"><replaceable>option</></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -69,7 +69,7 @@ PostgreSQL documentation <application>pg_basebackup</application> can make a base backup from not only the master but also the standby. To take a backup from the standby, set up the standby so that it can accept replication connections (that is, set - <varname>max_wal_senders</> and <xref linkend="guc-hot-standby">, + <varname>max_wal_senders</varname> and <xref linkend="guc-hot-standby">, and configure <link linkend="auth-pg-hba-conf">host-based authentication</link>). You will also need to enable <xref linkend="guc-full-page-writes"> on the master. </para> @@ -85,7 +85,7 @@ PostgreSQL documentation </listitem> <listitem> <para> - If you are using <literal>-X none</>, there is no guarantee that all + If you are using <literal>-X none</literal>, there is no guarantee that all WAL files required for the backup are archived at the end of backup. </para> </listitem> @@ -97,9 +97,9 @@ PostgreSQL documentation <listitem> <para> All WAL records required for the backup must contain sufficient full-page writes, - which requires you to enable <varname>full_page_writes</> on the master and - not to use a tool like <application>pg_compresslog</> as - <varname>archive_command</> to remove full-page writes from WAL files. + which requires you to enable <varname>full_page_writes</varname> on the master and + not to use a tool like <application>pg_compresslog</application> as + <varname>archive_command</varname> to remove full-page writes from WAL files. </para> </listitem> </itemizedlist> @@ -193,8 +193,8 @@ PostgreSQL documentation <listitem> <para> The maximum transfer rate of data transferred from the server. Values are - in kilobytes per second. Use a suffix of <literal>M</> to indicate megabytes - per second. A suffix of <literal>k</> is also accepted, and has no effect. + in kilobytes per second. Use a suffix of <literal>M</literal> to indicate megabytes + per second. A suffix of <literal>k</literal> is also accepted, and has no effect. Valid values are between 32 kilobytes per second and 1024 megabytes per second. </para> <para> @@ -534,7 +534,7 @@ PostgreSQL documentation string. See <xref linkend="libpq-connstring"> for more information. </para> <para> - The option is called <literal>--dbname</> for consistency with other + The option is called <literal>--dbname</literal> for consistency with other client applications, but because <application>pg_basebackup</application> doesn't connect to any particular database in the cluster, database name in the connection string will be ignored. @@ -594,8 +594,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -623,7 +623,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_basebackup</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -636,8 +636,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_basebackup</application> version and exit. @@ -646,8 +646,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_basebackup</application> command line @@ -665,8 +665,8 @@ PostgreSQL documentation <title>Environment</title> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -709,8 +709,8 @@ PostgreSQL documentation tar file before starting the PostgreSQL server. If there are additional tablespaces, the tar files for them need to be unpacked in the correct locations. In this case the symbolic links for those tablespaces will be created by the server - according to the contents of the <filename>tablespace_map</> file that is - included in the <filename>base.tar</> file. + according to the contents of the <filename>tablespace_map</filename> file that is + included in the <filename>base.tar</filename> file. </para> <para> diff --git a/doc/src/sgml/ref/pg_config-ref.sgml b/doc/src/sgml/ref/pg_config-ref.sgml index 0210f6389dc..b819f3f3457 100644 --- a/doc/src/sgml/ref/pg_config-ref.sgml +++ b/doc/src/sgml/ref/pg_config-ref.sgml @@ -13,7 +13,7 @@ <refnamediv> <refname>pg_config</refname> - <refpurpose>retrieve information about the installed version of <productname>PostgreSQL</></refpurpose> + <refpurpose>retrieve information about the installed version of <productname>PostgreSQL</productname></refpurpose> </refnamediv> <refsynopsisdiv> @@ -24,12 +24,12 @@ </refsynopsisdiv> <refsect1> - <title>Description</> + <title>Description</title> <para> - The <application>pg_config</> utility prints configuration parameters - of the currently installed version of <productname>PostgreSQL</>. It is + The <application>pg_config</application> utility prints configuration parameters + of the currently installed version of <productname>PostgreSQL</productname>. It is intended, for example, to be used by software packages that want to interface - to <productname>PostgreSQL</> to facilitate finding the required header files + to <productname>PostgreSQL</productname> to facilitate finding the required header files and libraries. </para> </refsect1> @@ -39,22 +39,22 @@ <title>Options</title> <para> - To use <application>pg_config</>, supply one or more of the following + To use <application>pg_config</application>, supply one or more of the following options: <variablelist> <varlistentry> - <term><option>--bindir</option></> + <term><option>--bindir</option></term> <listitem> <para> Print the location of user executables. Use this, for example, to find - the <command>psql</> program. This is normally also the location - where the <filename>pg_config</> program resides. + the <command>psql</command> program. This is normally also the location + where the <filename>pg_config</filename> program resides. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--docdir</option></> + <term><option>--docdir</option></term> <listitem> <para> Print the location of documentation files. @@ -63,7 +63,7 @@ </varlistentry> <varlistentry> - <term><option>--htmldir</option></> + <term><option>--htmldir</option></term> <listitem> <para> Print the location of HTML documentation files. @@ -72,7 +72,7 @@ </varlistentry> <varlistentry> - <term><option>--includedir</option></> + <term><option>--includedir</option></term> <listitem> <para> Print the location of C header files of the client interfaces. @@ -81,7 +81,7 @@ </varlistentry> <varlistentry> - <term><option>--pkgincludedir</option></> + <term><option>--pkgincludedir</option></term> <listitem> <para> Print the location of other C header files. @@ -90,7 +90,7 @@ </varlistentry> <varlistentry> - <term><option>--includedir-server</option></> + <term><option>--includedir-server</option></term> <listitem> <para> Print the location of C header files for server programming. @@ -99,7 +99,7 @@ </varlistentry> <varlistentry> - <term><option>--libdir</option></> + <term><option>--libdir</option></term> <listitem> <para> Print the location of object code libraries. @@ -108,7 +108,7 @@ </varlistentry> <varlistentry> - <term><option>--pkglibdir</option></> + <term><option>--pkglibdir</option></term> <listitem> <para> Print the location of dynamically loadable modules, or where @@ -120,18 +120,18 @@ </varlistentry> <varlistentry> - <term><option>--localedir</option></> + <term><option>--localedir</option></term> <listitem> <para> Print the location of locale support files. (This will be an empty string if locale support was not configured when - <productname>PostgreSQL</> was built.) + <productname>PostgreSQL</productname> was built.) </para> </listitem> </varlistentry> <varlistentry> - <term><option>--mandir</option></> + <term><option>--mandir</option></term> <listitem> <para> Print the location of manual pages. @@ -140,7 +140,7 @@ </varlistentry> <varlistentry> - <term><option>--sharedir</option></> + <term><option>--sharedir</option></term> <listitem> <para> Print the location of architecture-independent support files. @@ -149,7 +149,7 @@ |