Re: PG DOCS - logical replication filtering

On Wed, Apr 13, 2022 at 12:08 AM Euler Taveira <euler(at)eulerto(dot)com> wrote:
>
> On Tue, Apr 12, 2022, at 5:30 AM, Peter Smith wrote:
>
> Not changed. Because in fact, I copied most of this sentence
> (including the uppercase, "operations", "and/or") from existing
> documentation [1]
> e.g. see "The tables added to a publication that publishes UPDATE
> and/or DELETE operations must ..."
> [1] https://www.postgresql.org/docs/current/sql-createpublication.html
>
> Hmm. You are checking the Notes. I'm referring the the publish parameter. IMO
> this sentence should use operations in lowercase letters too because even if
> you create it with uppercase letters, Postgres will provide a lowercase word
> when you dump it.

IIRC the row filter replication identity checking is at run-time based
on the operation (not at DDL time based on the publish_parameter). For
this reason, and also because this is the same format/wording used in
many places already on the create_publication.sgml, I did not change
this formatting. But I did modify [v10] as earlier suggested to
replace the “and/or” with “or”, and also added another word
“operation”.

>
> Yeah, I know the information is the same in the summary and in the
> text. Personally, I find big slabs of technical text difficult to
> digest, so I'd have to spend 5 minutes of careful reading and drawing
> the exact same summary on a piece of paper anyway just to visualize
> what the text says. The summary makes it easy to understand at a
> glance. But I have modified the summary in [v9] to remove the "case"
> and to add other column headings as suggested.
>
> Isn't it better to use a table instead of synopsis?

Modified [v10] as suggested.

>
> Not changed. The readers of this docs page are all users who will be
> familiar with the filter expressions, so I felt the "OR'ed together"
> part will be perfectly clear to the intended audience.
>
> If you want to keep it, change it to "ORed". It is used in indices.sgml. Let's
> keep the consistence.

Modified [v10] as suggested.

>
> But I did not understand your point about “If, for some reason,
> someone decided to change it, this section will contain obsolete
> information”, because IIUC that will be equally true for both the
> explanation and the output, so I did not understand why you say "psql
> output is fine, the explanation is not". It is the business of this
> documentation to help the user to know how and where they can find the
> row filter information they may need to know.
>
> You are describing a psql command here. My point is keep psql explanation in
> the psql section. This section is to describe the row filter feature. If we
> start describing features in other sections, we will have outdated information
> when the referred feature is changed and someone fails to find all references.
> I tend to concentrate detailed explanation in the feature section. If I have to
> add links in other sections, I use "Seee Section 1.23 for details ...".

Modified [v10] so the psql descriptions are now very generic.

>
> Not changed. The publisher and subscriber programlistings are always
> separated. If you are looking at the rendered HTML I think it is quite
> clear that one is at the publisher and one is at the subscriber. OTOH,
> if we omitted creating the tables on the subscriber then I think that
> really would cause some confusion.
>
> The difference is extra space. By default, the CSS does not include a border
> for programlisting. That's why I complained about it. I noticed that the
> website CSS includes it. However, the PDF will not include the border. I would
> add a separate description for the subscriber just to be clear.
>

Modified [v10] as suggested to add a separate description for the subscriber.

> One last suggestion, you are using identifiers in uppercase letters but
> "primary key" is in lowercase.
>

Modified [v10] as suggested to make this uppercase

------
[v10] https://www.postgresql.org/message-id/CAHut%2BPvMEYkCRWDoZSpFnP%2B5SExus7YzWAd%3D6ah9vwkfRhOnSg%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia