WIP docs patch about composite-type behavior

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: pgsql-docs(at)postgreSQL(dot)org
Subject: WIP docs patch about composite-type behavior
Date: 2016-11-20 02:59:30
Message-ID: 16288.1479610770@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

There have been a couple of recent threads bemoaning our lack of clarity
about how references to composite values work, eg
https://www.postgresql.org/message-id/flat/20161029121906.15993.79158%40wrigleys.postgresql.org
https://www.postgresql.org/message-id/flat/CAGwx4BnDQZyJJpzom-UU15wh7s3DQE%3DChEdEDQ2%2Brd5S7S2UNA%40mail.gmail.com
(same instigator but distinct threads)

I suggested that we ought to try to consolidate information about this
in one place, and attached is a WIP patch to that end. Some notes:

* I'm not completely sold on either the new section's title or its
location; but I cannot find a better location.

* Some of the text is borrowed from section 36.4.3 "SQL Functions on
Composite Types", which should probably now be shortened in favor of
linking to this section, but I didn't do that yet. There may be more
places that should get merged in.

* I noticed that there is noplace in Part II that describes RETURNING
clauses as such; there's some material in 7.8.2 "Data-Modifying Statements
in WITH", but that really is assuming that you know what RETURNING does
already, and in any case it fails to explain the clause's use in
standalone statements. This seems like an, um, oversight.

Comments, objections, better ideas? Should this get back-patched?

regards, tom lane

Attachment Content-Type Size
better-composite-types-docs.patch text/x-diff 15.2 KB

Browse pgsql-docs by date

  From Date Subject
Next Message Alexander Law 2016-11-21 11:43:56 Performance optimization for make postgres.epub
Previous Message Tom Lane 2016-11-19 20:34:55 Re: [HACKERS] switching documentation build to XSLT