Re: Improve "3.6. Inheritance" tutorial - Mailing list pgsql-docs

On Fri, 2026-10-02 at 12:23 -0300, Matemática A3K wrote:
> On Fri, Oct 2, 2026 at 3:58 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
> > On Thu, 2026-10-01 at 18:55 +0000, PG Doc comments form wrote:
> > > Page: https://www.postgresql.org/docs/18/tutorial-inheritance.html
> > >
> > > I propose the following modifications: [...]
> >
> > Do I get you right that you don't have any problems with the
> > technical content, but are unhappy about the style?
>
> No, I'm unhappy with both, my suggestions go in both directions.

I must say that I perfer the original style.
But let's discuss the technical content:

> The main technical concern is that querying is not explained on it, it's
> explained on the "details page".
>
> More in concrete, if you add "In PostgreSQL, a table can inherit from zero
> or more other tables, and a query can reference either all rows of a table
> or all rows of a table plus all of its descendant tables. The latter behavior
> is the default." should be a "complete" explanation of the feature.

I think the explanation in the tutorial is quite clear:

  Here the ONLY before cities indicates that the query should be run over
  only the cities table, and not tables below cities in the inheritance
  hierarchy. Many of the commands that we have already discussed — SELECT,
  UPDATE, and DELETE — support this ONLY notation.

A tutorial is not supposed to provide a rigorous definition.  Such a
definition should be in the reference manual.

  And indeed I find in
https://www.postgresql.org/docs/18/sql-select.html

  If ONLY is specified before the table name, only that table is scanned.
  If ONLY is not specified, the table and all its descendant tables
  (if any) are scanned.

I'm happy with the page the way it is...

Yours,
Laurenz Albe