Re: three small improvements for "Composite Types" page

On Fri, Apr 12, 2024 at 1:20 PM Anton Voloshin <a(dot)voloshin(at)postgrespro(dot)ru>
wrote:

> Hello,
>
> While reading "Composite Types" manual page I've noticed that it is
> somewhat hard to follow by trying out given examples. I suggest three
> small changes which would make this page a little easier to follow for
> me:
>
> 1. Clarify "different kind" by adding a link to a section of "create
> type" page
>
> > Note that the AS keyword is essential; without it, the system will
> think a different kind of CREATE TYPE command is meant, and you will get
> odd syntax errors.
>
>

> Here there is no link to CREATE TYPE, so it's not so easy to go there to
> see what is that "different kind" of CREATE TYPE. I suggest to add an
> anchor for the "Base Types" section there and link the words "different
> kind" there.
>

I'd much prefer to leave "different kind" alone and turn the immediately
following, first-on-the-page, instance of CREATE TYPE into a link.

2. make first mention of CREATE TABLE a link

>
> > The syntax is comparable to CREATE TABLE, except ...
>
> It would be useful if this CREATE TABLE (first on this page) would
> become a link.
>

I'm not all that convinced of that particular usefulness but also don't see
it hurting either.

> 3. Simplify CREATE TABLE example to make it self-sufficient
>
> One of the examples on the same "Composite Types" page is an example of
> CREATE TABLE:
>
> CREATE TABLE inventory_item (
> name text,
> supplier_id integer REFERENCES suppliers,
> price numeric CHECK (price > 0)
> );
>
> This example is not self-sufficient: it requires one to have "suppliers"
> table with specific column to work as given.

Agreed.

David J.