From 4b5cc00e25c3abc601f48bfae0cc69a8729cd041 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Thu, 28 Mar 2019 18:50:03 -0500 Subject: [PATCH v1 2/8] review docs for pg12dev --- doc/src/sgml/bloom.sgml | 2 +- doc/src/sgml/catalogs.sgml | 4 ++-- doc/src/sgml/config.sgml | 13 ++++++----- doc/src/sgml/ecpg.sgml | 18 +++++++------- doc/src/sgml/libpq.sgml | 2 +- doc/src/sgml/monitoring.sgml | 30 ++++++++++++------------ doc/src/sgml/perform.sgml | 8 +++---- doc/src/sgml/ref/alter_table.sgml | 4 ++-- doc/src/sgml/ref/create_index.sgml | 4 ++-- doc/src/sgml/ref/pg_rewind.sgml | 15 ++++++------ doc/src/sgml/ref/pgbench.sgml | 6 ++--- doc/src/sgml/ref/reindex.sgml | 2 +- doc/src/sgml/sources.sgml | 48 +++++++++++++++++++------------------- doc/src/sgml/xfunc.sgml | 12 +++++----- 14 files changed, 82 insertions(+), 86 deletions(-) diff --git a/doc/src/sgml/bloom.sgml b/doc/src/sgml/bloom.sgml index 6eeadde..c341b65 100644 --- a/doc/src/sgml/bloom.sgml +++ b/doc/src/sgml/bloom.sgml @@ -65,7 +65,7 @@ Number of bits generated for each index column. Each parameter's name refers to the number of the index column that it controls. The default - is 2 bits and maximum is 4095. Parameters for + is 2 bits and the maximum is 4095. Parameters for index columns not actually used are ignored. diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index f4aabf5..ad4d150 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -3051,7 +3051,7 @@ SCRAM-SHA-256$<iteration count>:&l simplifies ATTACH/DETACH PARTITION operations: the partition dependencies need only be added or removed. Example: a child partitioned index is made partition-dependent - on both the partition table it is on and the parent partitioned + on both the table partition and the parent partitioned index, so that it goes away if either of those is dropped, but not otherwise. The dependency on the parent index is primary, so that if the user tries to drop the child partitioned index, @@ -3114,7 +3114,7 @@ SCRAM-SHA-256$<iteration count>:&l Note that it's quite possible for two objects to be linked by more than one pg_depend entry. For example, a child partitioned index would have both a partition-type dependency on its - associated partition table, and an auto dependency on each column of + associated table partition, and an auto dependency on each column of that table that it indexes. This sort of situation expresses the union of multiple dependency semantics. A dependent object can be dropped without CASCADE if any of its dependencies satisfies diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 9b66e7f..5f6873d 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -112,7 +112,7 @@ For example, 30.1 GB will be converted to 30822 MB not 32319628902 B. If the parameter is of integer type, a final rounding to integer - occurs after any units conversion. + occurs after any unit conversion. @@ -3408,7 +3408,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows current when the base backup was taken. The value latest recovers to the latest timeline found in the archive, which is useful in - a standby server. latest is the default. + a standby server. The default is latest. @@ -3515,7 +3515,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows servers or streaming base backup clients (i.e., the maximum number of simultaneously running WAL sender processes). The default is 10. The value 0 means - replication is disabled. Abrupt streaming client disconnection might + replication is disabled. Abrupt disconnection of a streaming client might leave an orphaned connection slot behind until a timeout is reached, so this parameter should be set slightly higher than the maximum number of expected clients so disconnected clients can immediately @@ -4135,8 +4135,9 @@ ANY num_sync ( bytea - The handling of the bytea type is also similar to - the VARCHAR. The definition on an array of type + The handling of the bytea type is similar to + the VARCHAR. The definition of an array of type bytea is converted into a named struct for every variable. A declaration like: @@ -1220,9 +1220,8 @@ bytea var[180]; struct bytea_var { int len; char arr[180]; } var; - The member arr hosts binary format - data. It also can handle even '\0' as part of - data unlike VARCHAR. + The member arr stores binary format + data, which can include zero bytes, unlike VARCHAR. The data is converted from/to hex format and sent/received by ecpglib. @@ -7571,8 +7570,7 @@ PREPARE name FROM A literal C string or a host variable containing a preparable - statement, one of the SELECT, INSERT, UPDATE, or - DELETE. + statement (SELECT, INSERT, UPDATE, or DELETE). diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index c1d1b6b..06b0076 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1122,7 +1122,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname connect_timeout - Maximum wait for connection, in seconds (write as a decimal integer, + Maximum time to wait while connecting, in seconds (write as a decimal integer, e.g. 10). Zero, negative, or not specified means wait indefinitely. The minimum allowed timeout is 2 seconds, therefore a value of 1 is interpreted as 2. diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index f1df14b..a5bf49c 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -271,13 +271,13 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser Some of the information in the dynamic statistics views shown in is security restricted. - Ordinary users can only see all the information about their own sessions - (sessions belonging to a role that they are a member of). In rows about + Ordinary users can only see all information about their own sessions + (sessions belonging to a role of which they are a member). In rows for other sessions, many columns will be null. Note, however, that the existence of a session and its general properties such as its sessions user and database are visible to all users. Superusers and members of the built-in role pg_read_all_stats (see also ) can see all the information about all sessions. + linkend="default-roles"/>) can see all information about all sessions. @@ -3411,16 +3411,16 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, VACUUM Progress Reporting - Whenever VACUUM is running, the - pg_stat_progress_vacuum view will contain - one row for each backend (including autovacuum worker processes) that is - currently vacuuming. The tables below describe the information + The pg_stat_progress_vacuum view will contain one + row for each backend that is running VACUUM, including + autovacuum worker processes. + The tables below describe the information that will be reported and provide information about how to interpret it. - Progress for VACUUM FULL commands is reported via - pg_stat_progress_cluster - because both VACUUM FULL and CLUSTER - rewrite the table, while regular VACUUM only modifies it - in place. See . + Progress for VACUUM FULL commands is instead reported via + pg_stat_progress_cluster, + because VACUUM FULL rewrites the table, like CLUSTER, + while regular VACUUM modifies it in place. See . +
@@ -3603,9 +3603,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, CLUSTER Progress Reporting - Whenever CLUSTER or VACUUM FULL is - running, the pg_stat_progress_cluster view will - contain a row for each backend that is currently running either command. + The pg_stat_progress_cluster view will contain a + row for each backend that is running either + CLUSTER or VACUUM FULL. The tables below describe the information that will be reported and provide information about how to interpret it. diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index a84be85..65c161b 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -899,10 +899,10 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000 Generally, the EXPLAIN output will display details for every plan node which was generated by the query planner. However, there are cases where the executor is able to determine that certain nodes are - not required; currently, the only node types to support this are the - Append and MergeAppend nodes. These - node types have the ability to discard subnodes which they are able to - determine won't contain any records required by the query. It is possible + not required; currently, the only node types to support this are + Append and MergeAppend, which + are able to discard subnodes when it's deduced that + they will not contain any records required by the query. It is possible to determine that nodes have been removed in this way by the presence of a "Subplans Removed" property in the EXPLAIN output. diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index e360728..679e51a 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -219,7 +219,7 @@ WITH ( MODULUS numeric_literal, REM SET NOT NULL may only be applied to a column - providing none of the records in the table contain a + provided none of the records in the table contain a NULL value for the column. Ordinarily this is checked during the ALTER TABLE by scanning the entire table; however, if a valid CHECK constraint is @@ -642,7 +642,7 @@ WITH ( MODULUS numeric_literal, REM When applied to a partitioned table, nothing is moved, but any partitions created afterwards with CREATE TABLE PARTITION OF will use that tablespace, - unless the TABLESPACE clause is used to override it. + unless overridden by its TABLESPACE clause. diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index d9d95b2..14a557a 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -181,8 +181,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] - Currently, the B-tree and the GiST index access methods supports this - feature. In B-tree and the GiST indexes, the values of columns listed + Currently, only the B-tree and GiST index access methods support this + feature. In B-tree and GiST indexes, the values of columns listed in the INCLUDE clause are included in leaf tuples which correspond to heap tuples, but are not included in upper-level index entries used for tree navigation. diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 53a64ee..cf77552 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -106,15 +106,14 @@ PostgreSQL documentation - pg_rewind will fail immediately if it finds - files it cannot write directly to. This can happen for example when - the source and the target server use the same file mapping for read-only - SSL keys and certificates. If such files are present on the target server + pg_rewind will fail immediately if it experiences + a write error. This can happen for example when + the source and target server use the same file mapping for read-only + SSL keys and certificates. If such files are present on the target server, it is recommended to remove them before running - pg_rewind. After doing the rewind, some of + pg_rewind. After performing the rewind, some of those files may have been copied from the source, in which case it may - be necessary to remove the data copied and restore back the set of links - used before the rewind. + be necessary to remove them and restore the files removed beforehand. @@ -183,7 +182,7 @@ PostgreSQL documentation pg_rewind to return without waiting, which is faster, but means that a subsequent operating system crash can leave the synchronized data folder corrupt. Generally, this option is - useful for testing but should not be used when creating a production + useful for testing but should not be used on a production installation. diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index f11d366..b4c7629 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -474,10 +474,8 @@ pgbench options d - Because in "prepared" mode pgbench reuses - the parse analysis result for the second and subsequent query - iteration, pgbench runs faster in the - prepared mode than in other modes. + pgbench runs faster in prepared mode because the + parse analysis happens only during the first query. The default is simple query protocol. (See diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index e05a76c..a5a6eba 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -241,7 +241,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR Reindexing a single index or table requires being the owner of that index or table. Reindexing a schema or database requires being the - owner of that schema or database. Note that is therefore sometimes + owner of that schema or database. Note specifically that it's possible for non-superusers to rebuild indexes of tables owned by other users. However, as a special exception, when REINDEX DATABASE, REINDEX SCHEMA diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml index 419f753..79f5322 100644 --- a/doc/src/sgml/sources.sgml +++ b/doc/src/sgml/sources.sgml @@ -103,7 +103,7 @@ less -x4 message text. In addition there are optional elements, the most common of which is an error identifier code that follows the SQL spec's SQLSTATE conventions. - ereport itself is just a shell function, that exists + ereport itself is just a shell function that exists mainly for the syntactic convenience of making message generation look like a function call in the C source code. The only parameter accepted directly by ereport is the severity level. @@ -359,7 +359,7 @@ ereport(ERROR, specify suppression of the CONTEXT: portion of a message in the postmaster log. This should only be used for verbose debugging messages where the repeated inclusion of context would bloat the log - volume too much. + too much. @@ -452,8 +452,8 @@ Hint: the addendum enough for error messages. Detail and hint messages can be relegated to a verbose mode, or perhaps a pop-up error-details window. Also, details and hints would normally be suppressed from the server log to save - space. Reference to implementation details is best avoided since users - aren't expected to know the details. + space. References to implementation details are best avoided since users + aren't expected to know them. @@ -504,14 +504,14 @@ Hint: the addendum Use of Quotes - Use quotes always to delimit file names, user-supplied identifiers, and + Always use quotes to delimit file names, user-supplied identifiers, and other variables that might contain words. Do not use them to mark up variables that will not contain words (for example, operator names). There are functions in the backend that will double-quote their own output - at need (for example, format_type_be()). Do not put + as needed (for example, format_type_be()). Do not put additional quotes around the output of such functions. @@ -872,7 +872,7 @@ BETTER: unrecognized node type: 42 from a few platform dependent pieces. - A few features included in the C99 standard are, at this time, not be + A few features included in the C99 standard are, at this time, not permitted to be used in core PostgreSQL code. This currently includes variable length arrays, intermingled declarations and code, // comments, universal @@ -880,16 +880,16 @@ BETTER: unrecognized node type: 42 practices. - Features from later revision of the C standard or compiler specific + Features from later revisions of the C standard or compiler specific features can be used, if a fallback is provided. - For example _StaticAssert() and + For example, _StaticAssert() and __builtin_constant_p are currently used, even though - they are from newer revisions of the C standard and a - GCC extension respectively. If not available - we respectively fall back to using a C99 compatible replacement that - performs the same checks, but emits rather cryptic messages and do not + they are from a newer revision of the C standard and a + GCC extension, respectively. If not available, in the first case, + we fall back to using a C99 compatible replacement that + performs the same checks, but emits rather cryptic messages; in the second case, we do not use __builtin_constant_p. @@ -897,14 +897,14 @@ BETTER: unrecognized node type: 42 Function-Like Macros and Inline Functions - Both, macros with arguments and static inline - functions, may be used. The latter are preferable if there are + Both macros with arguments and static inline + functions may be used. The latter are preferable if there are multiple-evaluation hazards when written as a macro, as e.g. the case with #define Max(x, y) ((x) > (y) ? (x) : (y)) - or when the macro would be very long. In other cases it's only + or when the macro would be very long. In other cases, it's only possible to use macros, or at least easier. For example because expressions of various types need to be passed to the macro. @@ -936,19 +936,19 @@ MemoryContextSwitchTo(MemoryContext context) Writing Signal Handlers - To be suitable to run inside a signal handler code has to be + To be suitable to run inside a signal handler, code has to be written very carefully. The fundamental problem is that, unless blocked, a signal handler can interrupt code at any time. If code - inside the signal handler uses the same state as code outside - chaos may ensue. As an example consider what happens if a signal + inside the signal handler uses the same state as code outside, + chaos may ensue. As an example, consider what happens if a signal handler tries to acquire a lock that's already held in the interrupted code. - Barring special arrangements code in signal handlers may only + Barring special arrangements, code in signal handlers may only call async-signal safe functions (as defined in POSIX) and access variables of type volatile sig_atomic_t. A few - functions in postgres are also deemed signal safe, importantly + functions in postgres are also deemed signal safe; specifically, SetLatch(). @@ -969,9 +969,9 @@ handle_sighup(SIGNAL_ARGS) } errno is saved and restored because - SetLatch() might change it. If that were not done - interrupted code that's currently inspecting errno might see the wrong - value. + SetLatch() might change it. If that were not done, + code interrupted by a signal might see the wrong value of + errno. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 3403269..5c17b10 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3364,11 +3364,11 @@ if (!ptr) - By default, a function is just a black box that the - database system knows very little about the behavior of. However, - that means that queries using the function may be executed much less + By default, a function is a black box that the + database system knows very little about, which + means queries calling the function may be executed less efficiently than they could be. It is possible to supply additional - knowledge that helps the planner optimize function calls. + information that helps the planner optimize function calls. @@ -3381,7 +3381,7 @@ if (!ptr) The parallel safety property (PARALLEL UNSAFE, PARALLEL RESTRICTED, or PARALLEL SAFE) must also be specified if you hope - to use the function in parallelized queries. + queries calling the function to use parallel query. It can also be useful to specify the function's estimated execution cost, and/or the number of rows a set-returning function is estimated to return. However, the declarative way of specifying those two @@ -3393,7 +3393,7 @@ if (!ptr) It is also possible to attach a planner support function to a SQL-callable function (called its target function), and thereby provide - knowledge about the target function that is too complex to be + information about the target function that is too complex to be represented declaratively. Planner support functions have to be written in C (although their target functions might not be), so this is an advanced feature that relatively few people will use. -- 2.1.4