Re: Another modest proposal for docs formatting: catalog descriptions

Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> writes:
> My 0.02€: I'm wondering whether the description could/should match SQL
> syntax, eg:

> oid OID
> adrelid OID REFERENCES pg_class(oid)
> adnum INT2 REFERENCES pg_attribute(attnum)
> …

> Or maybe just uppercase type names, especially when repeated?

Meh. I'm not a fan of overuse of upper case --- it's well established
that that's harder to read than lower or mixed case. And it's definitely
project policy that type names are generally treated as identifiers not
keywords, even if some of them happen to be keywords under the hood.

The markup I had in mind was <structfield> for the field name
and <type> for the type name, but no decoration beyond that.

As for the references, it seems to me that your notation would lead
people to think that there are actual FK constraints in place, which
of course there are not (especially not on the views). I'm not
hugely against it but I prefer what I suggested.

> I guess that reference targets would still be navigable.

Yeah, they'd still have <link> wrappers --- if I recall what those
look like in the documentation sources, they don't need any change
except for addition of the "(references ...)" text.

regards, tom lane