Re: GSoD - a patch for Getting Started tutorial
On Wed, Nov 20, 2019 at 6:13 PM Tom Lane wrote: > Laurenz Albe writes: > > I kind of like the "troubleshooting" section, but I am unsure where > > to set the limit. What is there currently doesn't cover all > > potential causes (e.g., connection via TCP, see Windows), but > > being exhaustive is probably impossible and not even desirable. > Thank you for your feedback! I'll be glad even if some part of this patch improves the getting started experience for novice users, so I can focus on the install and troubleshooting first. I would limit troubleshooting to those issues that might appear when we follow the tutorial. As you've already mentioned, Windows is not covered right now, so once I add it, I can add the Windows-specific connection issues too. However, if we cover Windows, I think it's logical to include PGDG Linux packages as well. > > > On the one hand I can see this section as being helpful for the > > host of people who are having problems connecting, on the other hand > > the true beginner might have trouble understanding explanations > > containing terms like "absolute path" and "Unix-domain sockets". > > As far as that goes, Corey's nearby proposal to add a glossary > could be a great help. We could define such terms there, and > make the tutorial's uses of them be hyperlinks. So maybe we > should get that done first, and then come back to this? > I agree that having links to a glossary can be quite valuable. However, I have some doubts about including each and every computer-related term - should we keep it more DBMS-specific? As for the "absolute path" in particular, I hope the example that follows clarifies things. > > (Side remark: I think the spelling should be "UNIX domain sockets".) > > FWIW, I think we've used the first spelling in most places. > Which is more "correct", I don't know, but I'm pretty sure > that spelling Unix in all-caps has been out of fashion for > a very long time. > Right, I've been following the spelling that seems to be widely used in documentation. My preference is to use it without a hyphen, but then we'd have to change the spelling everywhere in our docs. -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com
Re: GSoD - a patch for Getting Started tutorial
On Tue, Nov 19, 2019 at 11:00 AM Laurenz Albe wrote: > On Mon, 2019-11-18 at 23:35 +0300, Liudmila Mantrova wrote: > > > I am a bit uncomfortable about having details about the workings of > > > binary packages for specific operating systems in the core > documentation. > > > Maybe I'm too sensitive there, but what about having these parts in > the Wiki > > > and linking there from the tutorial? > > > > I also had my doubts about it, but since we are only talking about PGDG > packages that > > the community supports, it's probably OK to have it in docs? Besides, I > believe we > > should be consistent here - if we are hand-holding the user through the > source install, > > we should have a description for binary install as well (which is even > more useful for novices). > > I also think it makes the tutorial self-contained, which seems to > address one of the > > concerns raised in the presentation you are referring to. > > Perhaps you are right, but I wonder if following a link into the Wiki > would be a great hurdle for the novice. > I personally thought that a lot of the complaints in the presentation > were ridiculous, so we need not follow its recommendations slavishly. > i'm all for linking to the download page for the exact install commands (which I did), but i see no harm in mentioning e.g. install/data directories in documentation. It is something I myself went back to when working on this tutorial update, so I believe the user will do too. But let's hope we'll hear other opinions as well before I go and rework it all. > > > Quickly skimming over the text, I have two things to comment: > > > - The RedHat binaries use "trust" authentication by default, not > "peer". > > > > Do you mean PGDG binaries or any other binaries? For a PGDG install on > e.g. RHEL 8, > > peer seems to be the default. > > But now that you mentioned it, I realized that trust is the default for > > source installs and it might be worth adding, too. I'll try to tweak > this part again. > > The binaries for Fedora Linux use "trust". > Fedora 31 seems to be using peer. What am I missing? # dnf install postgresql12-server Last metadata expiration check: 0:03:09 ago on Tue Nov 19 13:11:43 2019. Dependencies resolved. Package Architecture Version Repository Size Installing: postgresql12-server x86_64 12.1-1PGDG.f31 pgdg12 5.1 M Installing dependencies: postgresql12x86_64 12.1-1PGDG.f31 pgdg12 1.5 M postgresql12-libs x86_64 12.1-1PGDG.f31 pgdg12 419 k Transaction Summary Install 3 Packages [root@localhost ~]# /usr/pgsql-12/bin/postgresql-12-setup initdb Initializing database ... OK ... [root@localhost ~]# grep '^local' /var/lib/pgsql/12/data/pg_hba.conf local all all peer local replication all peer > I think that the source installation is covered well enough. > > > > - I couldn't see anything about Windows. > > > I think that particularly on Windows people would need a tutorial > most, > > > not because Windows people are more clueless, but because things work > > > differently there. Many Windows users don't know how to start a > shell. > > > > I think we can extend it with Windows specifics if there are no other > major concerns. > > (But it'll probably take some time for me to try it and figure out the > differences. > > Although I know how to start a shell, I'm sure I'll face other problems. > :)) > > I understand your reluctance. > But if we want to cater for clueless beginners, we cannot omit Windows. > I wouldn't call it reluctance, it'll just take some time to figure out as I'm not a PostgreSQL user myself. Btw, I'll also appreciate your input if you have anything specific in mind about the differences we need to cover. Do I get it right that you suggest adding info on EDB installer to our docs? > > Yours, > Laurenz Albe > -- > Cybertec | https://www.cybertec-postgresql.com > > -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com
Re: GSoD - a patch for Getting Started tutorial
Thank you, Laurenz! On Mon, Nov 18, 2019 at 12:15 PM Laurenz Albe wrote: > On Sun, 2019-11-17 at 00:04 +0300, Liudmila Mantrova wrote: > > This is a good thing; I have seen people complain about the tutorial > ( > https://www.postgresql.eu/events/pgconfeu2019/schedule/session/2735-whats-wrong-with-postgres/ > ). > I really hope that your work doesn't go to waste > > I am a bit uncomfortable about having details about the workings of > binary packages for specific operating systems in the core documentation. > Maybe I'm too sensitive there, but what about having these parts in the > Wiki > and linking there from the tutorial? > I also had my doubts about it, but since we are only talking about PGDG packages that the community supports, it's probably OK to have it in docs? Besides, I believe we should be consistent here - if we are hand-holding the user through the source install, we should have a description for binary install as well (which is even more useful for novices). I also think it makes the tutorial self-contained, which seems to address one of the concerns raised in the presentation you are referring to. > > Quickly skimming over the text, I have two things to comment: > - The RedHat binaries use "trust" authentication by default, not "peer". > Do you mean PGDG binaries or any other binaries? For a PGDG install on e.g. RHEL 8, peer seems to be the default. But now that you mentioned it, I realized that trust is the default for source installs and it might be worth adding, too. I'll try to tweak this part again. > - I couldn't see anything about Windows. > I think that particularly on Windows people would need a tutorial most, > not because Windows people are more clueless, but because things work > differently there. Many Windows users don't know how to start a shell. > I think we can extend it with Windows specifics if there are no other major concerns. (But it'll probably take some time for me to try it and figure out the differences. Although I know how to start a shell, I'm sure I'll face other problems. :)) -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com
GSoD - a patch for Getting Started tutorial
Hi everyone, Some time ago I was selected to participate in Google season of docs program to update the introductory tutorial. Please consider the attached patch for the Getting Started part. Keeping the original information, i tried to make it easy to follow, as well as added installation steps for binary packages. I'll be glad to hear your feedback. Many thanks to Alexander Lakhin for responding to my multiple questions and verifying technical correctness. -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml index 5b73557835..07313dac96 100644 --- a/doc/src/sgml/start.sgml +++ b/doc/src/sgml/start.sgml @@ -3,121 +3,682 @@ Getting Started - - Installation + + Setting up the System -Before you can use PostgreSQL you need -to install it, of course. It is possible that -PostgreSQL is already installed at your -site, either because it was included in your operating system -distribution or because the system administrator already installed -it. If that is the case, you should obtain information from the -operating system documentation or your system administrator about -how to access PostgreSQL. - +To follow this tutorial, you need to have +PostgreSQL installed and configured. +You can install PostgreSQL using one of the +following ways: - -If you are not sure whether PostgreSQL -is already available or whether you can use it for your -experimentation then you can install it yourself. Doing so is not -hard and it can be a good exercise. -PostgreSQL can be installed by any -unprivileged user; no superuser (root) -access is required. - + + + + Install binary packages built by + PGDG. PostgreSQL Global Development Group (PGDG) provides binary + packages for most popular operating systems of the Red Hat family, + SUSE, Debian, and Ubuntu. When you install these packages, some + of the initial server setup is completed automatically. + + + + + Use PostgreSQL binary packages provided in + the operating system distributions. If you choose such packages, + consult your operating system documentation on how to access them + and initialize the database cluster. + + + + + Build PostgreSQL from source + code. It requires more work, but enables you to install + PostgreSQL on supported platforms even if + binary packages that you need are unavailable, perform the installation + without superuser rights, and customize the installation. + + + - -If you are installing PostgreSQL -yourself, then refer to -for instructions on installation, and return to -this guide when the installation is complete. Be sure to follow -closely the section about setting up the appropriate environment -variables. - -If your site administrator has not set things up in the default -way, you might have some more work to do. For example, if the -database server machine is a remote machine, you will need to set -the PGHOST environment variable to the name of the -database server machine. The environment variable -PGPORT might also have to be set. The bottom line is -this: if you try to start an application program and it complains -that it cannot connect to the database, you should consult your -site administrator or, if that is you, the documentation to make -sure that your environment is properly set up. If you did not -understand the preceding paragraph then read the next section. - + + + Avoid experimenting with PostgreSQL + installations on production systems. Depending on the system + configuration, re-installing PostgreSQL + can affect the current database cluster and result in data loss. + + + + +Using PGDG Binary Packages for Linux + + + To install and set up PostgreSQL from binary + packages built by PGDG, follow the instructions below for your + operating system: + + + + +Debian and Ubuntu systems + + + + +RHEL and SUSE systems + + + + + + + +Debian and Ubuntu Systems + + + To set up a PostgreSQL server on Debian or + Ubuntu, you only need to add the PGDG package repository and install the + packages; the rest of the setup is completed automatically. + Depending on the operating system, the commands to add the repository + and install the packages differ, so follow + the instructions provided for your system on the + https://www.postgresql.org/download/;>download page. + + + + For the purposes of this tutorial, it is enough to install + the postgresql-vers
Re: Does 'instead of delete' trigger support modification of OLD
> 8 нояб. 2019 г., в 0:26, Bruce Momjian написал(а): > > First, notice "only", which was missing from the later sentence: > >For INSERT and UPDATE >operations [only], the trigger may modify the >NEW row before returning it. > > which I have now added with my applied patch to all supported releases. > Hi Bruce, I happened to browse recent documentation-related commits and I didn’t see this patch in REL_12_STABLE. Judging by the commit message, it should be applied there too.
fix tags in v12 Release Notes
Hi, Please consider fixing a couple of tagging issues in v12 Release notes discovered during translation. A trivial patch is attached. -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com diff --git a/doc/src/sgml/release-12.sgml b/doc/src/sgml/release-12.sgml index 129787b4c9..19f08cdb7b 100644 --- a/doc/src/sgml/release-12.sgml +++ b/doc/src/sgml/release-12.sgml @@ -608,7 +608,7 @@ Author: Tom Lane Treat object-name columns in the information_schema - views as being of type name not varchar + views as being of type name, not varchar (Tom Lane) @@ -969,7 +969,7 @@ Author: Heikki Linnakangas Reduce the WAL write overhead -of GiST, GIN and +of GiST, GIN, and SP-GiST index creation (Anastasia Lubennikova, Andrey V. Lepikhov) @@ -1288,7 +1288,7 @@ Author: Stephen Frost --> -Allow TOASTed +Allow toasted values to be minimally decompressed (Paul Ramsey) @@ -1305,7 +1305,7 @@ Author: Robert Haas --> -Allow ALTER TABLE .. SET +Allow ALTER TABLE ... SET NOT NULL to avoid unnecessary table scans (Sergei Kornilov) @@ -1323,7 +1323,7 @@ Author: Noah Misch --> -Allow ALTER TABLE .. SET DATA TYPE changing between +Allow ALTER TABLE ... SET DATA TYPE changing between timestamp and timestamptz to avoid a table rewrite when the session time zone is UTC (Noah Misch) @@ -1438,7 +1438,7 @@ Author: Peter Eisentraut Progress is reported in the pg_stat_progress_create_index -system view +system view. @@ -2235,7 +2235,7 @@ Author: Tomas Vondra - This output can also be obtained in + This output can also be obtained when using by setting auto_explain.log_settings. @@ -2620,7 +2620,8 @@ Author: Michael Paquier Add connection parameter - to control libpq's TCP timeout (Ryohei Nagaura) + to control libpq's TCP + timeout (Ryohei Nagaura) @@ -2631,9 +2632,9 @@ Author: Tom Lane --> - Allow libpq (and thus psql) to report only - the SQLSTATE value in error messages (Didier - Gautheron) + Allow libpq (and thus + psql) to report only the + SQLSTATE value in error messages (Didier Gautheron) @@ -2644,7 +2645,7 @@ Author: Tom Lane --> - Add libpq + Add libpq function PQresultMemorySize() to report the memory used by a query result (Lars Kanis, Tom Lane) @@ -2657,7 +2658,7 @@ Author: Peter Eisentraut --> - Remove the no-display/debug flag from libpq's + Remove the no-display/debug flag from libpq's options connection parameter (Peter Eisentraut) @@ -2729,8 +2730,8 @@ Author: Michael Paquier --> - Allow vacuumdb to disable waiting for locks or skipping all-visible - pages (Nathan Bossart) + Allow to disable waiting for locks + or skipping all-visible pages (Nathan Bossart) @@ -2835,9 +2836,12 @@ Author: Tom Lane --> -Improve tab completion of CREATE TABLE, CREATE TRIGGER, -CREATE EVENT TRIGGER, ANALYZE, EXPLAIN, VACUUM, ALTER TABLE, -ALTER INDEX, ALTER DATABASE, ALTER INDEX ALTER COLUMN +Improve tab completion of CREATE TABLE, +CREATE TRIGGER, CREATE EVENT TRIGGER, +ANALYZE, EXPLAIN, +VACUUM, ALTER TABLE, +ALTER INDEX, ALTER DATABASE, +and ALTER INDEX ALTER COLUMN (Dagfinn Ilmari Mannsåker, Tatsuro Yamada, Michaël Paquier, Tom Lane, Justin Pryzby) @@ -2878,8 +2882,8 @@ Author: Tom Lane --> -Improve precision of pgbench's --rate -option (Tom Lane) +Improve precision of pgbench's +--rate option (Tom Lane) @@ -2889,8 +2893,8 @@ Author: Peter Eisentraut 2018-10-15 [5b75a4f82] pgbench: Report errors during run better --> -Improve pgbench's error reporting with clearer messages and return -codes (Peter Eisentraut) +Improve pgbench's error reporting with +clearer messages and return codes (Peter Eisentraut) @@ -3160,7 +3164,7 @@ existin This enables the development of new table access methods, which can optimize storage for different - use-cases. The existing heap access method + use cases. The existing heap access method remains the default.
Re: minor doc fixes for REL_12_STABLE
On Tue, Aug 20, 2019 at 7:48 AM Michael Paquier wrote: > On Mon, Aug 19, 2019 at 05:12:12PM +0300, Liudmila Mantrova wrote: > > Most of the stuff in v12-doc-fixes.patch looks pretty good. I don't > agree with some of the changes in libpq.sgml, as firstterm is used to > outline the different modes of the error verbosity API. Using > firstterm is also more consistent with ErrorContextVisibility. You > are right though that a markup for the default mode goes missing. I > have tweaked a couple of other things, and committed that part to HEAD > and REL_12_STABLE. > You may be right on this one for consistency reasons, but it still looks like a mode name to me, not a new term to be explained. BTW, I believe firstterm is usually used for each term only once, and TERSE appears twice in a single paragraph now. Also firstterm is a translatable element, while literal is not (and e.g. TERSE doesn't look like something to translate in this context). Looks like you have also changed "an SQL" to "a SQL" in some cases (but not everywhere), and I wonder what's the official guidance here for PostgreSQL documentation. I see no consistency, but the first version appears more often, that's why I decided to use it (although I have to admit that I've been looking for something to confirm my personal preference). > > Now, for the second patch... First thanks for helping me with my > laziness and gather all the changes which have been done in the docs > on HEAD (Alexander has done an awesome lot of work recently and going > after each doc change was too much for me). > All the credit should go to Alexander. Thank you for a prompt commit! -- Best regards, Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com
minor doc fixes for REL_12_STABLE
Hi,
Please consider the attached patches that fix some documentation
inconsistencies in REL_12_STABLE branch. The first one contains fixes of
typos and tagging issues that were discovered during new content
translation. The other is a back-patch of fixes already accepted in master
after REL_12_STABLE has been created (originally reported by Alexander
Lakhin in "Fix typos and inconsistencies for HEAD" series).
--
Best regards,
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 0e22dcc31b..5e71a2e865 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -11031,7 +11031,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
kinds
text[]
- Types of exdended statistics enabled for this record
+ Types of extended statistics enabled for this record
diff --git a/doc/src/sgml/custom-scan.sgml b/doc/src/sgml/custom-scan.sgml
index ab9b055d9a..b8963a28eb 100644
--- a/doc/src/sgml/custom-scan.sgml
+++ b/doc/src/sgml/custom-scan.sgml
@@ -83,10 +83,7 @@ typedef struct CustomPath
by nodeToString, so that debugging routines that attempt to
print the custom path will work as designed. methods must
point to a (usually statically allocated) object implementing the required
-custom path methods, of which there is currently only one. The
-LibraryName and SymbolName fields must also
-be initialized so that the dynamic loader can resolve them to locate the
-method table.
+custom path methods, of which there is currently only one.
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index bc8570363c..fa34e5500f 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -5011,7 +5011,7 @@ struct
The fields sqlcaid,
-sqlcabc,
+sqlabc,
sqlerrp, and the remaining elements of
sqlerrd and
sqlwarn currently contain no useful
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4bb5461484..169a01fc1a 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2893,7 +2893,7 @@
- tcvn_to_utf8
+ windows_1258_to_utf8
WIN1258
UTF8
@@ -3061,7 +3061,7 @@
- utf8_to_tcvn
+ utf8_to_windows_1258
UTF8
WIN1258
diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index 44a3b2c03c..beed6521eb 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -696,8 +696,8 @@ my_picksplit(PG_FUNCTION_ARGS)
/*
* Choose where to put the index entries and update unionL and unionR
- * accordingly. Append the entries to either v_spl_left or
- * v_spl_right, and care about the counters.
+ * accordingly. Append the entries to either v-spl_left or
+ * v-spl_right, and care about the counters.
*/
if (my_choice_is_left(unionL, curl, unionR, curr))
@@ -910,7 +910,7 @@ Datum
my_fetch(PG_FUNCTION_ARGS)
{
GISTENTRY *entry = (GISTENTRY *) PG_GETARG_POINTER(0);
-input_data_type *in = DatumGetP(entry->key);
+input_data_type *in = DatumGetPointer(entry->key);
fetched_data_type *fetched_data;
GISTENTRY *retval;
@@ -921,7 +921,7 @@ my_fetch(PG_FUNCTION_ARGS)
* Convert 'fetched_data' into the a Datum of the original datatype.
*/
-/* fill *retval from fetch_data. */
+/* fill *retval from fetched_data. */
gistentryinit(*retval, PointerGetDatum(converted_datum),
entry->rel, entry->page, entry->offset, FALSE);
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index fded8d3b4b..d0f30a075f 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5913,7 +5913,7 @@ int PQendcopy(PGconn *conn);
It should either be issued when the last string has been sent
to the server using PQputline or when the
last string has been received from the server using
- PGgetline. It must be issued or the server
+ PQgetline. It must be issued or the server
will get out of sync with the client. Upon return
from this function, the server is ready to receive the next SQL
command. The return value is 0 on successful completion,
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index ef1556be8f..ae73630a48 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3740,9 +3740,9 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
If no condition name nor SQLSTATE is specified in a
RAISE EXCEPTION command, the default is to use
-RAISE_EXCEPTION (P0001). If no message
-text is specified, the default is to use the condition name or
-SQLSTATE as message text.
+ERRCODE_RAISE_EXCEPTION (P0001).
+If no message text
Re: readability changes to postgres.sgml
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what this is
> about -- not whether the removed little text-pieces were 'true' or not.
>
>
I'm afraid I can't agree that all changes are good enough (e.g. "start with
describing the general syntax of SQL, then how to create
tables.." used to be better with a verb, and "Readers are encouraged
review" is probably too liberal grammar). Changes like "encouraged to look"
vs. the original "should see" can be also challenged as an improvement -
IMHO the original version reads equally well (although it could be more
concise for sure).
That said, I agree we should not hold on to every word just because it was
written - the shorter the docs, the more chances they get to be actually
read. Avoiding assumptions about what's simple may also be beneficial. A
simple concept for one can be new and unclear to another, no matter how
experienced they actually are.
If we want to make these intros more concise, one of the easiest ways to
achieve this is to address the reader directly ("Readers looking for xxx
are encouraged to look" vs. smth like "For xxx, see"). We can also question
the need for some of the provided info - for example, assumptions about
typical user behavior and complexity of the text that follows could
probably be let gone altogether. I don't believe they can actually guide
anyone as they are quite vague anyway (how many are "the first few"
chapters exactly?) That would leave us with the scope of the chapters
described and explicit references to elsewhere (if required for clarity),
making the most valuable parts here more prominent and not-so-easy to skip.
--
Best regards,
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
suspicious wording in pg_rewind docs
Hi everyone, While reviewing docs for [1] I came across a phrase in pg_rewind.sgml that seems confusing: "... The point of divergence can be found either on the target timeline, the source timeline, or their common ancestor. In the typical failover scenario where the target cluster was shut down soon after the divergence, this is not a problem, but if the target cluster ran for a long time after the divergence, the old WAL files might no longer be present. In that case, they can be manually copied from the WAL archive to the |pg_wal| directory, or fetched on startup by configuring primary_conninfo <https://www.postgresql.org/docs/12/runtime-config-replication.html#GUC-PRIMARY-CONNINFO> or restore_command <https://www.postgresql.org/docs/12/runtime-config-wal.html#GUC-RESTORE-COMMAND>. " While beginning of this paragraph talks about scanning target cluster WALs, the "or fetched on startup" part suggests that we are applying the source cluster WALs already, so I would simply remove it from here. To avoid source/target confusion, we could also add another hint that it's target WALs we are talking about. Please consider the attached fix. [1] https://www.postgresql.org/message-id/a3acff50-5a0d-9a2c-b3b2-ee36168955c1%40postgrespro.ru -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 52a1caa..a7e1705 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -66,14 +66,12 @@ PostgreSQL documentation can be found either on the target timeline, the source timeline, or their common ancestor. In the typical failover scenario where the target cluster was shut down soon after the divergence, this is not a problem, but if the - target cluster ran for a long time after the divergence, the old WAL + target cluster ran for a long time after the divergence, its old WAL files might no longer be present. In that case, they can be manually - copied from the WAL archive to the pg_wal directory, or - fetched on startup by configuring or - . The use of - pg_rewind is not limited to failover, e.g. a standby - server can be promoted, run some write transactions, and then rewinded - to become a standby again. + copied from the WAL archive to the pg_wal directory. + The use of pg_rewind is not limited to failover, + e.g. a standby server can be promoted, run some write transactions, and then + get rewound to become a standby again.
Re: misc doc fixes for REL_12_STABLE
On 7/12/19 7:44 AM, Michael Paquier wrote: On Thu, Jul 11, 2019 at 05:49:26PM +0300, Liudmila Mantrova wrote: Please consider a patch that fixes some trivial issues in new doc fragments (a couple of typos/ambiguities and some tags that affect translation). Thanks for the patch. I have one comment. - backups. Moreover, because it writes a backup_label file on the - master, it can cause the master to fail to restart automatically after - a crash. On the other hand, the erroneous removal of a backup_label - file from a backup or standby is a common mistake which can result + backups. Moreover, because it creates a backup label file, as + described below, it can block automatic restart of the master server + after a crash. On the other hand, the erroneous removal of this + file from a backup or standby is a common mistake, which can result in serious data corruption. If it is necessary to use this method, the following steps may be used. Okay, yes that could be a bit confusing for the reader. Nit: I would replace "master" with "primary" while we are in the area. What do you think? But that's the only comment I have, the rest looks good! -- Michael Hi Michael, Changing master to primary was my first inclination, but I saw that we have 8 masters and 4 primaries here. So maybe we should have another consistency patch (that probably goes beyond this chapter). I can prepare one if you like. P.S. I'm not particularly happy about this paragraph either, but that's as far as I could get without twisting the original ideas. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
misc doc fixes for REL_12_STABLE
Hi,
Please consider a patch that fixes some trivial issues in new doc
fragments (a couple of typos/ambiguities and some tags that affect
translation).
--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 9d4c000..2fdbcb4 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -962,10 +962,10 @@ SELECT * FROM pg_stop_backup(false, true);
The process for an exclusive backup is mostly the same as for a
non-exclusive one, but it differs in a few key steps. This type of
backup can only be taken on a primary and does not allow concurrent
- backups. Moreover, because it writes a backup_label file on the
- master, it can cause the master to fail to restart automatically after
- a crash. On the other hand, the erroneous removal of a backup_label
- file from a backup or standby is a common mistake which can result
+ backups. Moreover, because it creates a backup label file, as
+ described below, it can block automatic restart of the master server
+ after a crash. On the other hand, the erroneous removal of this
+ file from a backup or standby is a common mistake, which can result
in serious data corruption. If it is necessary to use this method,
the following steps may be used.
@@ -1025,10 +1025,10 @@ SELECT pg_start_backup('label', true);
As noted above, if the server crashes during the backup it may not be
- possible to restart until the backup_label file has
+ possible to restart until the backup_label file has
been manually deleted from the PGDATA directory. Note
that it is very important to never remove the
- backup_label file when restoring a backup, because
+ backup_label file when restoring a backup, because
this will result in corruption. Confusion about when it is appropriate
to remove this file is a common cause of data corruption when using this
method; be very certain that you remove the file only on an existing
@@ -1075,7 +1075,7 @@ SELECT pg_stop_backup();
lack of disk space, failure to call pg_stop_backup
will leave the server in backup mode indefinitely, causing future backups
to fail and increasing the risk of a restart failure during the time that
- backup_label exists.
+ backup_label exists.
diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml
index f06305d..bf3aebd 100644
--- a/doc/src/sgml/biblio.sgml
+++ b/doc/src/sgml/biblio.sgml
@@ -137,14 +137,11 @@
-SQL Technical Report
+http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip;>SQL Technical Report
Part 6: SQL support for JavaScript Object
Notation (JSON)
-First Edition.
-
-http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip;>.
-
-2017.
+First Edition
+2017
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml
index b27eb6f..0f11897 100644
--- a/doc/src/sgml/ref/alter_foreign_table.sgml
+++ b/doc/src/sgml/ref/alter_foreign_table.sgml
@@ -227,8 +227,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] name
Backward compatibility syntax for removing the oid
- system column. As oid system columns cannot be added anymore, this never
- has an effect.
+ system column. As oid system columns cannot be added
+ anymore, this never has an effect.
diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
index 33706d1..162bafd 100644
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -120,7 +120,7 @@ PostgreSQL documentation
to be written safely to disk. This option causes
pg_checksums to return without waiting, which is
faster, but means that a subsequent operating system crash can leave
-the updated data folder corrupt. Generally, this option is useful
+the updated data directory corrupt. Generally, this option is useful
for testing but should not be used on a production installation.
This option has no effect when using --check.
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 8fa2314..017713f 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -749,7 +749,7 @@ PostgreSQL documentation
--extra-float-digits=ndigits
-Use the specified value of extra_float_digits when dumping
+Use the specified value of extra_float_digits when dumping
floating-point data, instead of the maximum available precision.
Routine dumps made for backup purposes should not use this option.
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/d
Google Season of Docs 2019 - exploration phase
Hi, Somewhat late in the project exploration phase, I'd like to express my interest in the GSoD initiative. I'm currently employed at Postgres Professional as a full-time tech writer, and I see it as a good opportunity to get more involved with the PostgreSQL community. Judging by the scope of suggested projects and several threads in pgsql-docs, a better getting started experience is wanted by many. As I lack technical background, this was (and still is) a major roadblock for me to get deeper understanding of PostgreSQL. I yet have to compose the actual proposal, but I think we should take into account the following threads: * Craig Ringer. Updating the intro for packages - improve usability, reduce new user confusion <https://www.postgresql.org/message-id/flat/CAMsr%2BYG8vtnqtiK-6uLkP9cEmRviUWKWS_RJ_LqTMwf8tWY-Kw%40mail.gmail.com> * Lætitia Avrot. Tutorial section of documentation: enhancements needed <https://www.postgresql.org/message-id/flat/CAB_COdjnQtDcg454fZxSM0u--VvJdTuD2heBsXCskQRpAo%3Dabw%40mail.gmail.com> Another option would be improving the full-text search chapter, which is currently not on the project list, but looks like it can be expanded with advanced full-text search configuration opportunities. Some info on my experience: * Install-related docs I've created for Postgres Professional: https://postgrespro.com/docs/enterprise/11/installation-bin * A summary of my prior experience on LinkedIn: https://www.linkedin.com/in/lmantrov/ -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Re: a small fix for Release notes 11.3
On 5/16/19 7:03 PM, Jonathan S. Katz wrote: On 5/16/19 10:17 AM, Liudmila Mantrova wrote: Hello, Please consider a mini-patch for 11.3 release notes that fixes pg_dump-related wording and also makes Jonathan's name consistent with how it's listed in contributors list. I am flattered by your attention to detail around my name, but I'm ok with it either way as long as my first/last names are spelled correctly :) Thanks, Jonathan No problem, but I hope the other part of the patch is still useful :) -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
a small fix for Release notes 11.3
Hello, Please consider a mini-patch for 11.3 release notes that fixes pg_dump-related wording and also makes Jonathan's name consistent with how it's listed in contributors list. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml index 9c06e1e..1a190f5 100644 --- a/doc/src/sgml/release-11.sgml +++ b/doc/src/sgml/release-11.sgml @@ -424,7 +424,7 @@ Branch: REL9_4_STABLE [8ba485422] 2019-03-23 16:51:26 -0400 pg_dump is also modified to emit - SET xmloption = content while restoring data, + SET xmloption = content, ensuring that dump/restore works even if the prevailing setting is document. @@ -864,7 +864,7 @@ Branch: REL9_4_STABLE [a82c06f40] 2019-04-24 09:05:37 +0900 --> Tighten validation of encoded SCRAM-SHA-256 and MD5 passwords - (Jonathan Katz) + (Jonathan S. Katz)
some grammar fixes for docs
Hi, I have noticed imperfect grammar in a couple of sgml files, please consider a small patch (attached). -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index ee2501b..ef22a48 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -443,7 +443,7 @@ pgbench options d --latency-limit=limit -Transaction which last more than limit milliseconds +Transactions that last more than limit milliseconds are counted and reported separately, as late. diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index d43ef13..7cf9d0e 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -206,7 +206,7 @@ Of the two operator classes for type point, quad_point_ops is the default. kd_point_ops - supports the same operators but uses a different index data structure which + supports the same operators but uses a different index data structure that may offer better performance in some applications. @@ -292,9 +292,9 @@ leaf_consistent additionally returns a boolean result. The methods must not modify any fields of their input structs. In all cases, the output struct is initialized to zeroes before calling the - user-defined method. Optional sixth method compress - accepts datum to be indexed as the only argument and returns value suitable - for physical storage in leaf tuple. + user-defined method. The optional sixth method compress + accepts datum to be indexed as the only argument and returns a value suitable + for physical storage in a leaf tuple. @@ -447,9 +447,9 @@ typedef struct spgChooseOut type that was to be inserted into the index. leafDatum is a value of spgConfigOut.leafType - type which is initially an result of method + type, which is initially a result of method compress applied to datum - when method compress is provided, or same value as + when method compress is provided, or the same value as datum otherwise. leafDatum can change at lower levels of the tree if the choose or picksplit @@ -868,7 +868,7 @@ typedef struct spgLeafConsistentOut Converts the data item into a format suitable for physical storage in a leaf tuple of index page. It accepts spgConfigIn.attType - value and return + value and returns spgConfigOut.leafType value. Output value should not be toasted.
Re: Proposed HTML Documentation Styles
On 10/16/18 5:44 PM, Jonathan S. Katz wrote: On 10/4/18 11:50 AM, Jonathan S. Katz wrote: Hi, As part of the effort to modernize the look and feel of PostgreSQL.org and associated web projects, Sarah & I have worked on applying the new styles to the documentation. The main goals of the project were: - To have the documentation styles match that of the main website - To make the documentation easier to view on mobile devices - To set up the web-based documentation for future usability changes and improvements Thank you everyone for your feedback. We launched the new documentation styles this morning. Please let us know if you find any issues or have any additional feedback. Thanks, Jonathan Hi Jonathan, Thank you for modernizing doc styles! I have noticed a small rendering issue in the Chrome browser. If you follow a link to a bookmark in a different page, it's hidden below the website header. Links within the same page and section-level links appear to work fine. The attached screenshot illustrates the result of navigating to the default_statistics_targetdescription from the https://www.postgresql.org/docs/10/static/planner-stats.html page. I have not tested this thoroughly, but I got the same result on my smartphone in Safari, while having no issues at all in Firefox on Ubuntu. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Re: Misc typos in documentation
On 08/25/2018 10:04 PM, Bruce Momjian wrote:
On Thu, Aug 16, 2018 at 11:25:25AM +0300, Liudmila Mantrova wrote:
On 06/20/2018 05:04 PM, Magnus Hagander wrote:
I have split them in two just in case rn-typos.patch conflicts with any
current work on release-11.sgml, which seems to be going on in more
than one thread. I'll appreciate your feedback if it should have been
done differently.
I have bumped into a couple of similar typos in 9.6 and 10 - the patch based on
REL9_6_STABLE is attached.
I have made the adjustments to 9.6 and 10 as you suggested. I added
quoting to "two" to match other releases:
https://git.postgresql.org/pg/commitdiff/993b5a78adff29fc58e7449cab98bb865b77c663
Thanks.
Thank you, Bruce!
I totally missed those quotes (and your response).
I've just noticed your recent commit, and looks like the typo to be
fixed ("boundries") managed to escape somehow.
Assuming it's not an alternative spelling I'm unaware of, I'm attaching
a smaller version of the patch (based on the current state of
REL_10_STABLE).
--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml
index 8e50f79..edc0813 100644
--- a/doc/src/sgml/pgtrgm.sgml
+++ b/doc/src/sgml/pgtrgm.sgml
@@ -154,7 +154,7 @@
greatest similarity between the first string and any substring of the second
string. However, this function does not add padding to the boundaries of
the extent. Thus, the number of additional characters present in the
- second string is not considered, except for the mismatched word boundries.
+ second string is not considered, except for the mismatched word boundaries.
Re: uncommon syntax in datatype.sgml
On 07/17/2018 01:52 PM, Peter Eisentraut wrote: On 16.07.18 20:42, Liudmila Mantrova wrote: I have noticed uncommon English syntax in datatype.sgml, with two full sentences following a colon in the same paragraph. I don't understand what's wrong with that. Hi Peter, I have brought this up because the backpatch to REL9_6_STABLE and below has lost the capital letter after the colon (commit 037768cf), so I think this phrase is likely to confuse others in a similar way. The current syntax in master is indeed acceptable, e.g. Chicago Manual of Style says: "The colon may sometimes be used instead of a period to introduce a series of related sentences." However, this wording suggests to me that it's not the most common usage, so it can confuse non-native speakers (like me). Alternatively, we could fix the backpatch only. The patch based on REL9_6_STABLE is attached if you decide to choose this path. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 5f45db2..729 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -508,7 +508,7 @@ - We use the following terms below: the + We use the following terms below: The precision of a numeric is the total count of significant digits in the whole number, that is, the number of digits to both sides of the decimal point.
uncommon syntax in datatype.sgml
Hi, I have noticed uncommon English syntax in datatype.sgml, with two full sentences following a colon in the same paragraph. I was inclined to convert these sentences into a list, but this markup seems unpopular in PostgreSQL docs for some reason. Please consider a less invasive patch (attached) that fixes the issue. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 3d36cca..a708100 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -514,7 +514,7 @@ - We use the following terms below: The + Note the following terms used below. The precision of a numeric is the total count of significant digits in the whole number, that is, the number of digits to both sides of the decimal point.
missing replaceable tags in backup.sgml
Hi, One of the new examples in backup.sgml seems to be missing a couple of tags. A trivial patch is attached. -- Liudmila Mantrova Technical writer at Postgres Professional: http://www.postgrespro.com The Russian Postgres Company diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 349834c..982776c 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -141,7 +141,7 @@ psql dbname psql exit with an exit status of 3 if an SQL error occurs: -psql --set ON_ERROR_STOP=on dbname dumpfile +psql --set ON_ERROR_STOP=on dbname dumpfile Either way, you will only have a partially restored database. Alternatively, you can specify that the whole dump should be
