From bbaf9e8f840acb8e4a52dc1809bd2c9b320e9df8 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 18 Jun 2017 14:01:45 -0400 Subject: [PATCH] Documentation spell checking and markup improvements --- doc/src/sgml/adminpack.sgml | 2 +- doc/src/sgml/amcheck.sgml | 4 +-- doc/src/sgml/config.sgml | 16 ++++++------ doc/src/sgml/ddl.sgml | 11 ++++---- doc/src/sgml/extend.sgml | 2 +- doc/src/sgml/func.sgml | 12 ++++----- doc/src/sgml/generic-wal.sgml | 2 +- doc/src/sgml/maintenance.sgml | 2 +- doc/src/sgml/monitoring.sgml | 4 +-- doc/src/sgml/perform.sgml | 2 +- doc/src/sgml/plperl.sgml | 2 +- doc/src/sgml/pltcl.sgml | 2 +- doc/src/sgml/ref/create_policy.sgml | 4 +-- doc/src/sgml/ref/create_statistics.sgml | 4 +-- doc/src/sgml/ref/create_table.sgml | 4 +-- doc/src/sgml/ref/explain.sgml | 2 +- doc/src/sgml/ref/pg_dumpall.sgml | 13 ++++++---- doc/src/sgml/release-10.sgml | 34 ++++++++++++------------- doc/src/sgml/user-manag.sgml | 2 +- doc/src/sgml/xfunc.sgml | 4 +-- 20 files changed, 66 insertions(+), 62 deletions(-) diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 98736cb7c4..fddf90c4a5 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -152,7 +152,7 @@ integer Alternate name for pg_rotate_logfile(), but note that it - returns integer 0 or 1 rather than boolean + returns integer 0 or 1 rather than boolean diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 893a5b41d9..dd71dbd679 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -215,7 +215,7 @@ ORDER BY c.relpages DESC LIMIT 10; - Filesystem or storage subsystem faults where checksums happen to + File system or storage subsystem faults where checksums happen to simply not be enabled. @@ -223,7 +223,7 @@ ORDER BY c.relpages DESC LIMIT 10; shared memory buffer at the time of verification if there is only a shared buffer hit when accessing the block. Consequently, amcheck does not necessarily examine data read from the - filesystem at the time of verification. Note that when checksums are + file system at the time of verification. Note that when checksums are enabled, amcheck may raise an error due to a checksum failure when a corrupt block is read into a buffer. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index ac1cf471f2..0b943f4c63 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1908,10 +1908,10 @@ include_dir 'conf.d' Whenever more than bgwriter_flush_after bytes have - been written by the bgwriter, attempt to force the OS to issue these + been written by the background writer, attempt to force the OS to issue these writes to the underlying storage. Doing so will limit the amount of dirty data in the kernel's page cache, reducing the likelihood of - stalls when an fsync is issued at the end of a checkpoint, or when + stalls when an fsync is issued at the end of a checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads that are bigger than @@ -2029,7 +2029,7 @@ include_dir 'conf.d' pool of processes established by , limited by . Note that the requested - number of workers may not actually be available at runtime. If this + number of workers may not actually be available at run time. If this occurs, the plan will run with fewer workers than expected, which may be inefficient. The default value is 2. Setting this value to 0 disables parallel query execution. @@ -2090,7 +2090,7 @@ include_dir 'conf.d' been written by a single backend, attempt to force the OS to issue these writes to the underlying storage. Doing so will limit the amount of dirty data in the kernel's page cache, reducing the - likelihood of stalls when an fsync is issued at the end of a + likelihood of stalls when an fsync is issued at the end of a checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads @@ -2270,7 +2270,7 @@ include_dir 'conf.d' For reliable recovery when changing fsync off to on, it is necessary to force all modified buffers in the kernel to durable storage. This can be done while the cluster - is shutdown or while fsync is on by running initdb + is shutdown or while fsync is on by running initdb --sync-only, running sync, unmounting the file system, or rebooting the server. @@ -2700,7 +2700,7 @@ include_dir 'conf.d' have been written while performing a checkpoint, attempt to force the OS to issue these writes to the underlying storage. Doing so will limit the amount of dirty data in the kernel's page cache, reducing - the likelihood of stalls when an fsync is issued at the end of the + the likelihood of stalls when an fsync is issued at the end of the checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads @@ -3460,7 +3460,7 @@ ANY num_sync ( divided by the absolute value of this setting. The default is -2, which keeps - the behaviour from previous versions of PostgreSQL. + the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf file or on the server command line. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index ec015e93d0..b05a9c2150 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1769,13 +1769,13 @@ UPDATE 1 All of the policies constructed thus far have been permissive policies, meaning that when multiple policies are applied they are combined using - the "OR" boolean operator. While permissive policies can be constructed + the OR Boolean operator. While permissive policies can be constructed to only allow access to rows in the intended cases, it can be simpler to combine permissive policies with restrictive policies (which the records - must pass and which are combined using the "AND" boolean operator). + must pass and which are combined using the AND Boolean operator). Building on the example above, we add a restrictive policy to require - the administrator to be connected over a local unix socket to access the - records of the passwd table: + the administrator to be connected over a local Unix socket to access the + records of the passwd table: @@ -2971,7 +2971,8 @@ VALUES ('Albany', NULL, NULL, 'NY'); CREATE TABLE nor is it possible to add columns to partitions after-the-fact using ALTER TABLE. Tables may be added as a partition with ALTER TABLE ... ATTACH PARTITION - only if their columns exactly match the parent, including oids. + only if their columns exactly match the parent, including any + oid column. diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index c4f211bc02..b96ef389a2 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1207,7 +1207,7 @@ include $(PGXS) NO_INSTALLCHECK - don't define an installcheck target, useful e.g. if tests require special configuration, or don't use pg_regress + don't define an installcheck target, useful e.g. if tests require special configuration, or don't use pg_regress diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 7452d7cfa6..e073f7b57c 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1302,7 +1302,7 @@ transformation functions radians() and degrees() shown earlier. However, using the degree-based trigonometric functions is preferred, - as that way avoids roundoff error for special cases such + as that way avoids round-off error for special cases such as sind(30). @@ -9571,7 +9571,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple tsvector reduce each string value in the document to a tsvector, and then - concatentate those in document order to produce a single tsvector + concatenate those in document order to produce a single tsvector to_tsvector('english', '{"a": "The Fat Rats"}'::json) 'fat':2 'rat':3 @@ -9744,7 +9744,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple unnest(tsvector, OUT lexeme text, OUT positions smallint[], OUT weights text) setof record - expand a tsvector to a set of rows + expand a tsvector to a set of rows unnest('fat:2,4 cat:3 rat:5A'::tsvector) (cat,{3},{D}) ... @@ -17675,7 +17675,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); txid_current_if_assigned() bigint - same as txid_current() but returns null instead of assigning an xid if none is already assigned + same as txid_current() but returns null instead of assigning a new transaction ID if none is already assigned txid_current_snapshot() @@ -17705,7 +17705,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); txid_status(bigint) txid_status - report the status of the given xact - committed, aborted, in progress, or NULL if the txid is too old + report the status of the given transaction: committed, aborted, in progress, or null if the transaction ID is too old @@ -18592,7 +18592,7 @@ postgres=# select pg_start_backup('label_goes_here'); the backup_label and tablespace_map are returned in the result of the function, and should be written to files in the backup (and not in the data directory). There is an optional second - parameter of type boolean. If false, the pg_stop_backup + parameter of type boolean. If false, the pg_stop_backup will return immediately after the backup is completed without waiting for WAL to be archived. This behavior is only useful for backup software which independently monitors WAL archiving. Otherwise, WAL diff --git a/doc/src/sgml/generic-wal.sgml b/doc/src/sgml/generic-wal.sgml index 147d456d34..dfa78c5ca2 100644 --- a/doc/src/sgml/generic-wal.sgml +++ b/doc/src/sgml/generic-wal.sgml @@ -35,7 +35,7 @@ — register a buffer to be modified within the current generic WAL record. This function returns a pointer to a temporary copy of the buffer's page, where modifications should be made. (Do not modify the - buffer's contents directly.) The third argument is a bitmask of flags + buffer's contents directly.) The third argument is a bit mask of flags applicable to the operation. Currently the only such flag is GENERIC_XLOG_FULL_IMAGE, which indicates that a full-page image rather than a delta update should be included in the WAL record. diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml index 65a64c85ec..fe1e0ed2b3 100644 --- a/doc/src/sgml/maintenance.sgml +++ b/doc/src/sgml/maintenance.sgml @@ -594,7 +594,7 @@ SELECT datname, age(datfrozenxid) FROM pg_database; scans every page in the table that is not already all-frozen, it should set age(relfrozenxid) to a value just a little more than the vacuum_freeze_min_age setting - that was used (more by the number of transcations started since the + that was used (more by the number of transactions started since the VACUUM started). If no relfrozenxid-advancing VACUUM is issued on the table until autovacuum_freeze_max_age is reached, an autovacuum will soon diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 9ff5eea038..be3dc672bc 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1143,7 +1143,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser userlock - Waiting to acquire a userlock. + Waiting to acquire a user lock. advisory @@ -1244,7 +1244,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser BtreePage - Waiting for the page number needed to continue a parallel btree scan to become available. + Waiting for the page number needed to continue a parallel B-tree scan to become available. ExecuteGather diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index b4b8f8dcb8..924f6091ba 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -1214,7 +1214,7 @@ SELECT * FROM zipcodes WHERE city = 'San Francisco' AND zip = '90210'; In many practical situations, this assumption is usually satisfied; for example, there might be a GUI in the application that only allows - selecting compatible city and zipcode values to use in a query. + selecting compatible city and ZIP code values to use in a query. But if that's not the case, functional dependencies may not be a viable option. diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index dd2ffbc6ce..37a3557d61 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1335,7 +1335,7 @@ DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl; - Initialization will happen in the postmaster if the plperl library is + Initialization will happen in the postmaster if the plperl library is included in , in which case extra consideration should be given to the risk of destabilizing the postmaster. The principal reason for making use of this feature diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index ba4af2aec5..acd4dd69d3 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -882,7 +882,7 @@ CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE PROCEDURE tclsnit first word identifies the subsystem or library reporting the error; beyond that the contents are left to the individual subsystem or library. For database errors reported by PL/Tcl commands, the first - word is POSTGRES, the second word is the Postgres + word is POSTGRES, the second word is the PostgreSQL version number, and additional words are field name/value pairs providing detailed information about the error. Fields SQLSTATE, condition, diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml index 3b24e5e95e..c0dfe1ea4b 100644 --- a/doc/src/sgml/ref/create_policy.sgml +++ b/doc/src/sgml/ref/create_policy.sgml @@ -126,7 +126,7 @@ CREATE POLICY name ON Specify that the policy is to be created as a permissive policy. All permissive policies which are applicable to a given query will - be combined together using the boolean "OR" operator. By creating + be combined together using the Boolean OR operator. By creating permissive policies, administrators can add to the set of records which can be accessed. Policies are permissive by default. @@ -139,7 +139,7 @@ CREATE POLICY name ON Specify that the policy is to be created as a restrictive policy. All restrictive policies which are applicable to a given query will - be combined together using the boolean "AND" operator. By creating + be combined together using the Boolean AND operator. By creating restrictive policies, administrators can reduce the set of records which can be accessed as all restrictive policies must be passed for each record. diff --git a/doc/src/sgml/ref/create_statistics.sgml b/doc/src/sgml/ref/create_statistics.sgml index f319a6ea9c..deda21fec7 100644 --- a/doc/src/sgml/ref/create_statistics.sgml +++ b/doc/src/sgml/ref/create_statistics.sgml @@ -152,14 +152,14 @@ CREATE STATISTICS s1 (dependencies) ON a, b FROM t1; ANALYZE t1; --- now the rowcount estimate is more accurate: +-- now the row count estimate is more accurate: EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); Without functional-dependency statistics, the planner would assume that the two WHERE conditions are independent, and would multiply their selectivities together to arrive at a much-too-small - rowcount estimate. + row count estimate. With such statistics, the planner recognizes that the WHERE conditions are redundant and does not underestimate the rowcount. diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index bc014d0879..b15c19d3d0 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -443,8 +443,8 @@ FROM ( { numeric_literal | PostgreSQL.), but for list partitioning, the partition key must consist of a single column or - expression. If no btree operator class is specified when creating a - partitioned table, the default btree operator class for the datatype will + expression. If no B-tree operator class is specified when creating a + partitioned table, the default B-tree operator class for the datatype will be used. If there is none, an error will be reported. diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 6d909f1a97..4219180943 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -201,7 +201,7 @@ ROLLBACK; SUMMARY - Include summary information (eg: totalled timing information) after the + Include summary information (e.g., totaled timing information) after the query plan. Summary information is included by default when ANALYZE is used but otherwise is not included by default, but can be enabled using this option. Planning time in diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 2ab570ad4c..aa944a2e92 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -345,11 +345,14 @@ PostgreSQL documentation - Do not dump passwords for roles. When restored, roles will have a NULL - password and authentication will always fail until the password is reset. - Since password values aren't needed when this option is specified we - use the catalog view pg_roles in preference to pg_authid, since access - to pg_authid may be restricted by security policy. + Do not dump passwords for roles. When restored, roles will have a + null password, and password authentication will always fail until the + password is set. Since password values aren't needed when this option + is specified, the role information is read from the catalog + view pg_roles instead + of pg_authid. Therefore, this option also + helps if access to pg_authid is restricted by + some security policy. diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml index 1918149333..67d0c5499f 100644 --- a/doc/src/sgml/release-10.sgml +++ b/doc/src/sgml/release-10.sgml @@ -52,7 +52,7 @@ --> pg_upgrade-ed hash indexes from previous major - Postgres versions must be rebuilt. + PostgreSQL versions must be rebuilt. @@ -277,7 +277,7 @@ Changing this from the default value caused queries referencing parent tables to not include children tables. The SQL standard requires such behavior and this has been the default since - Postgres 7.1. + PostgreSQL 7.1. @@ -308,7 +308,7 @@ Users needing dump support for pre-8.0 servers need to use dump - binaries from Postgres 9.6. + binaries from PostgreSQL 9.6. @@ -323,7 +323,7 @@ This removes configure's @@ -336,7 +336,7 @@ - This protocol hasn't had client support since Postgres 6.3. + This protocol hasn't had client support since PostgreSQL 6.3. @@ -350,7 +350,7 @@ This removes compatibility with the contrib version of full text - search that shipped in pre-8.3 Postgres versions. + search that shipped in pre-8.3 PostgreSQL versions. @@ -412,12 +412,12 @@ 2017-02-19 [0414b26ba] Add optimizer and executor support for parallel index-on --> - Support parallel btree index scans (Rahila Syed, Amit Kapila, + Support parallel B-tree index scans (Rahila Syed, Amit Kapila, Robert Haas, Rafia Sabih) - Allows btree index pages to be checked by separate parallel + Allows B-tree index pages to be checked by separate parallel workers. @@ -735,7 +735,7 @@ 2017-01-15 [0777f7a2e] Fix matching of boolean index columns to sort ordering. --> - Improve planner matching of boolean indexes (Tom Lane) + Improve planner matching of boolean indexes (Tom Lane) @@ -824,7 +824,7 @@ 2017-03-29 [f90d23d0c] Implement SortSupport for macaddr data type --> - Improve sort performance of the macaddr data type (Brandur Leach) + Improve sort performance of the macaddr data type (Brandur Leach) @@ -1217,7 +1217,7 @@ 2017-04-05 [68ea2b7f9] Reduce lock level for CREATE STATISTICS --> - Reduce locking required to change table params (Simon Riggs, + Reduce locking required to change table parameters (Simon Riggs, Fabrízio Mello) @@ -1337,7 +1337,7 @@ This allows more fine-grained replication options, including - replication between different major versions of Postgres and + replication between different major versions of PostgreSQL and selective-table replication. @@ -2127,7 +2127,7 @@ - The ecpg version now matches the Postgres distribution version + The ecpg version now matches the PostgreSQL distribution version number. @@ -2427,7 +2427,7 @@ Temporary replication slots will be used by default when - pg_basebackup uses wal streaming with default + pg_basebackup uses WAL streaming with default options. @@ -2525,7 +2525,7 @@ Major versions will now increase just the first number, and minor releases will increase just the second number. A third number - will no longer be used in Postgres version numbers. + will no longer be used in PostgreSQL version numbers. @@ -2670,7 +2670,7 @@ 2017-04-06 [510074f9f] Remove use of Jade and DSSSL --> - Use XSLT to build the Postgres documentation (Peter + Use XSLT to build the PostgreSQL documentation (Peter Eisentraut) @@ -2785,7 +2785,7 @@ --> Add amcheck which can - check the validity of btree indexes (Peter Geoghegan) + check the validity of B-tree indexes (Peter Geoghegan) diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index 914f1505ab..46989f0169 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -527,7 +527,7 @@ DROP ROLE doomed_role; pg_stat_scan_tables - Execute monitoring functions that may take AccessShareLocks on tables, + Execute monitoring functions that may take ACCESS SHARE locks on tables, potentially for a long time. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 1a6c3b9bc2..cd6dd840ba 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2354,7 +2354,7 @@ CREATE FUNCTION concat_text(text, text) RETURNS text the system should automatically assume a null result if any input value is null. By doing this, we avoid having to check for null inputs in the function code. Without this, we'd have to check for null values - explicitly, using PG_ARGISNULL(). + explicitly, using PG_ARGISNULL(). @@ -3086,7 +3086,7 @@ CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer, - The directory contrib/tablefunc + The directory contrib/tablefunc module in the source distribution contains more examples of set-returning functions. -- 2.40.0