David, I have some suggestions. but first i want to show how the current version of doc may look like for new readers. and why. I am sure that it looks pretty logical if you KNOW how it works, but it is not so clear if you WANT to learn that from documentation.
explanation: first sentence: "they will only find target rows that were committed as of the command start time." how a naive user (me) read that: "okay. at the start of command we find only committed rows. LETS SEE WHAT HAPPENS NEXT!". second sentence: "The search condition of the command (the WHERE clause) is re-evaluated to see if the updated version of the row still matches the search condition." how it looks: "The command will be RE-EVALUATED for all rows in the current snapshot (i.e. against new state of db after first updater commits) to RE-CHECK the WHERE condition. AT THE SAME TIME (AS AN EFFECT) we see if the updated version of the row still matches the search condition." For me RE-evaluating is an ACTION and "to see..that still matches" is ONE of the accompanying options. As if I said: "I mowed all the grass to avoid seeing the dandelions again." suggestion: change sentence: "The search condition of the command (the WHERE clause) is re-evaluated to see if the updated version of the row still matches the search condition." with sentence: "The search condition of the command (the WHERE clause) is re-evaluated only for updated versions of rows to see if they still match the search condition. Note that this is different from re-executing the command." I tried to explain as best I could. Of course, I dare not insist on anything. thanks! On Wed, 18 Aug 2021 at 03:47, David G. Johnston <david.g.johns...@gmail.com> wrote: > On Tue, Aug 17, 2021 at 4:17 PM radiodiversion <radiodivers...@gmail.com> > wrote: > >> I still think it would be great if this doc point was worded a little >> differently in new editions. >> >> > Suggestions are welcome. > > Without some idea of why you seemed to miss the two seemingly obvious > references that I pointed out (including a fragment you quoted) it's hard > to decide what might be an improvement. It's unappealing to consider > rewriting the documentation based upon the experiences of a sample size of > one without a clear rationale. > > David J. > > -- with best regards, radiodiversion
