Re: Another modest proposal for docs formatting: catalogdescriptions - Mailing list pgsql-docs

From Fabien COELHO
Subject Re: Another modest proposal for docs formatting: catalogdescriptions
Date
Msg-id alpine.DEB.2.22.394.2005060740030.3077@pseudo
Whole thread Raw
In response to Re: Another modest proposal for docs formatting: catalog descriptions  (Tom Lane <tgl@sss.pgh.pa.us>)
List pgsql-docs
Hello Tom,

>>    oid OID
>
> 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.

I found "oid oid" stuttering kind of strange, hence an attempt at 
suggesting something that could distinguish them.

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

Ok. If they are displayed a little differently afterwards that'd may help.

> 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).

In practice the system ensures that the target exists, so it is as-if 
there would be a foreign key enforced?

My point is that using differing syntaxes for the more-or-less the same 
concept does not help user understand the semantics, but maybe that is 
just me.

> I'm not hugely against it but I prefer what I suggested.

Ok!

-- 
Fabien.



pgsql-docs by date:

Previous
From: "Jonathan S. Katz"
Date:
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
Next
From: Jürgen Purtz
Date:
Subject: Re: Documentation - chapter 52, system catalogs