Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jVqV7-00072t-St for pgsql-docs@arkaria.postgresql.org; Tue, 05 May 2020 05:52:17 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jVqV6-0001VD-Qh for pgsql-docs@arkaria.postgresql.org; Tue, 05 May 2020 05:52:16 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jVqV6-0001V2-Kq; Tue, 05 May 2020 05:52:16 +0000 Received: from courriel-2.mines-paristech.fr ([77.158.173.19] helo=antispam-1.ensmp.fr) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jVqV3-0002ds-FO; Tue, 05 May 2020 05:52:15 +0000 Received: from smtp-4.mines-paristech.fr (smtp-4.ensmp.fr [77.158.173.143]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by antispam-1.ensmp.fr (antispam.mines-paristech.fr) with ESMTPS id 3823B56D12; Tue, 5 May 2020 07:52:10 +0200 (CEST) Received: from pseudo (27.237.219.88.rev.sfr.net [88.219.237.27]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp-4.mines-paristech.fr (Postfix) with ESMTPSA id C6CD02C0191; Tue, 5 May 2020 07:52:09 +0200 (CEST) Date: Tue, 5 May 2020 07:52:08 +0200 (CEST) From: Fabien COELHO X-X-Sender: fabien@pseudo To: Tom Lane cc: pgsql-docs@lists.postgresql.org, PostgreSQL Developers Subject: Re: Another modest proposal for docs formatting: catalog descriptions In-Reply-To: <12984.1588643549@sss.pgh.pa.us> Message-ID: References: <12984.1588643549@sss.pgh.pa.us> User-Agent: Alpine 2.22 (DEB 394 2020-01-19) MIME-Version: 1.0 Content-Type: multipart/mixed; BOUNDARY="2056645051-109835698-1588657719=:175044" Content-ID: X-CLAMAV-SCAN: ok X-VRSPAM-SCORE: 0 X-VRSPAM-STATE: legit X-VRSPAM-CAUSE: gggruggvucftvghtrhhoucdtuddrgeduhedrjeehgdelkecutefuodetggdotefrucfrrhhofhhilhgvmecuggftfghnshhusghstghrihgsvgenuceurghilhhouhhtmecufedttdenucenucfjughrpeffhffvufgjkfhffgggtgesmhdtreertderjeenucfhrhhomhephfgrsghivghnucevqffgnffjqfcuoegtohgvlhhhohestghrihdrvghnshhmphdrfhhrqeenucggtffrrghtthgvrhhnpedvhefgteeuleefgeekkeffleegfeevtdfgjeehvefgheetkeehhfejjeeuheetudenucfkphepkeekrddvudelrddvfeejrddvjeenucfrrghrrghmpehmohguvgepshhmthhpohhuth X-VRSPAM-EXTCAUSE: mhhouggvpehsmhhtphhouhht List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --2056645051-109835698-1588657719=:175044 Content-Type: text/plain; CHARSET=UTF-8; format=flowed Content-Transfer-Encoding: 8BIT Content-ID: Hello Tom, > oid oid > Row identifier > > adrelid oid (references pg_class.oid) > The table this column belongs to > > adnum int2 (references pg_attribute.attnum) > The number of the column > > adbin pg_node_tree > The column default value, in nodeToString() representation. Use > pg_get_expr(adbin, adrelid) to convert it to an SQL expression. > > Thoughts? +1 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? oid OID adrelid OID (references pg_class.oid) adnum INT2 (references pg_attribute.attnum) … I guess that reference targets would still be navigable. -- Fabien. --2056645051-109835698-1588657719=:175044--