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 1jXBsY-00074D-La for pgsql-hackers@arkaria.postgresql.org; Fri, 08 May 2020 22:54:03 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jXBsX-0007S6-6l for pgsql-hackers@arkaria.postgresql.org; Fri, 08 May 2020 22:54:01 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jXBsW-0007Rt-Mb; Fri, 08 May 2020 22:54:00 +0000 Received: from sss.pgh.pa.us ([66.207.139.130]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jXBsN-000406-J5; Fri, 08 May 2020 22:54:00 +0000 Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1]) by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 048MrabY023611; Fri, 8 May 2020 18:53:36 -0400 From: Tom Lane To: "Jonathan S. Katz" cc: Alvaro Herrera , Fabien COELHO , pgsql-docs@lists.postgresql.org, PostgreSQL Developers Subject: Re: Another modest proposal for docs formatting: catalog descriptions In-reply-to: <14800.1588805800@sss.pgh.pa.us> References: <20200506213810.GA29168@alvherre.pgsql> <14800.1588805800@sss.pgh.pa.us> Comments: In-reply-to Tom Lane message dated "Wed, 06 May 2020 18:56:40 -0400" MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0" Content-ID: <23553.1588978363.0@sss.pgh.pa.us> Date: Fri, 08 May 2020 18:53:36 -0400 Message-ID: <23610.1588978416@sss.pgh.pa.us> List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk ------- =_aaaaaaaaaa0 Content-Type: text/plain; charset="us-ascii" Content-ID: <23553.1588978363.1@sss.pgh.pa.us> Here's a more fully fleshed out draft for this, with stylesheet markup to get extra space around the column type names. I realized that I can probably automate this conversion, unlike the function-table conversion: I'm not feeling any need to editorialize on the column descriptions, so I can probably just extract the data from the SGML programmatically and rebuild it as I want. Seems like it should be a fairly quick process. So, if this seems good from your standpoint, please push up the patch on main.css and then I'll see about doing the edit. (BTW, said patch also removes some no-longer-used detritus from the earlier markup attempt.) regards, tom lane ------- =_aaaaaaaaaa0 Content-Type: text/x-diff; name="catalog-description-prototype-2.patch"; charset="us-ascii" Content-ID: <23553.1588978363.2@sss.pgh.pa.us> Content-Description: catalog-description-prototype-2.patch Content-Transfer-Encoding: quoted-printable diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index ce33df9..e3513ad 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -388,178 +388,251 @@ = <structname>pg_aggregate</structname> Columns - - + - Name - Type - References - Description + + Column Type + + + Description + + - aggfnoid - regproc - pg_pr= oc.oid - pg_proc OID of the aggregate functi= on + + aggfnoid + regproc + (references pg_proc<= /structname>.oid) + + + pg_proc OID of the aggregate function + - aggkind - char - - Aggregate kind: + + aggkind + char + + + Aggregate kind: n for normal aggregates, o for ordered-set aggregates, or h for hypothetical-set aggregate= s - + - aggnumdirectargs - int2 - - Number of direct (non-aggregated) arguments of an ordered-se= t or + + aggnumdirectargs + int2 + + + Number of direct (non-aggregated) arguments of an ordered-set or hypothetical-set aggregate, counting a variadic array as one argum= ent. If equal to pronargs, the aggregate mus= t be variadic and the variadic array describes the aggregated arguments as well = as the final direct arguments. - Always zero for normal aggregates. + Always zero for normal aggregates. + - aggtransfn - regproc - pg_pr= oc.oid - Transition function + + aggtransfn + regproc + (references pg_proc<= /structname>.oid) + + + Transition function + - aggfinalfn - regproc - pg_pr= oc.oid - Final function (zero if none) + + aggfinalfn + regproc + (references pg_proc<= /structname>.oid) + + + Final function (zero if none) + - aggcombinefn - regproc - pg_pr= oc.oid - Combine function (zero if none) + + aggcombinefn + regproc + (references pg_proc<= /structname>.oid) + + + Combine function (zero if none) + - aggserialfn - regproc - pg_pr= oc.oid - Serialization function (zero if none) + + aggserialfn + regproc + (references pg_proc<= /structname>.oid) + + + Serialization function (zero if none) + - aggdeserialfn - regproc - pg_pr= oc.oid - Deserialization function (zero if none) + + aggdeserialfn + regproc + (references pg_proc<= /structname>.oid) + + + Deserialization function (zero if none) + - aggmtransfn - regproc - pg_pr= oc.oid - Forward transition function for moving-aggregate mode (zero = if none) + + aggmtransfn + regproc + (references pg_proc<= /structname>.oid) + + + Forward transition function for moving-aggregate mode (zero if non= e) + - aggminvtransfn - regproc - pg_pr= oc.oid - Inverse transition function for moving-aggregate mode (zero = if none) + + aggminvtransfn + regproc + (references pg_proc<= /structname>.oid) + + + Inverse transition function for moving-aggregate mode (zero if non= e) + - aggmfinalfn - regproc - pg_pr= oc.oid - Final function for moving-aggregate mode (zero if none) + + aggmfinalfn + regproc + (references pg_proc<= /structname>.oid) + + + Final function for moving-aggregate mode (zero if none) + - aggfinalextra - bool - - True to pass extra dummy arguments to aggfinalf= n + + aggfinalextra + bool + + + True to pass extra dummy arguments to aggfinalfn + - aggmfinalextra - bool - - True to pass extra dummy arguments to aggmfinal= fn + + aggmfinalextra + bool + + + True to pass extra dummy arguments to aggmfinalfn + - aggfinalmodify - char - - Whether aggfinalfn modifies the + + aggfinalmodify + char + + + Whether aggfinalfn modifies the transition state value: r if it is read-only, s if the aggtransfn cannot be applied after the aggfinalfn,= or w if it writes on the value - + - aggmfinalmodify - char - - Like aggfinalmodify, but for + + aggmfinalmodify + char + + + Like aggfinalmodify, but for the aggmfinalfn - + - aggsortop - oid - p= g_operator.oid - Associated sort operator (zero if none) + + aggsortop + oid + (references pg_o= perator.oid) + + + Associated sort operator (zero if none) + - aggtranstype - oid - pg_ty= pe.oid - Data type of the aggregate function's internal transition (s= tate) data + + aggtranstype + oid + (references pg_type<= /structname>.oid) + + + Data type of the aggregate function's internal transition (state) = data + - aggtransspace - int4 - - Approximate average size (in bytes) of the transition state - data, or zero to use a default estimate + + aggtransspace + int4 + + + Approximate average size (in bytes) of the transition state + data, or zero to use a default estimate + - aggmtranstype - oid - pg_ty= pe.oid - Data type of the aggregate function's internal transition (s= tate) - data for moving-aggregate mode (zero if none) + + aggmtranstype + oid + (references pg_type<= /structname>.oid) + + + Data type of the aggregate function's internal transition (state) + data for moving-aggregate mode (zero if none) + - aggmtransspace - int4 - - Approximate average size (in bytes) of the transition state = data - for moving-aggregate mode, or zero to use a default estimate + + aggmtransspace + int4 + + + Approximate average size (in bytes) of the transition state data + for moving-aggregate mode, or zero to use a default estimate + - agginitval - text - - + + agginitval + text + + The initial value of the transition state. This is a text field containing the initial value in its external string representation. If this field is null, the transition state value starts out null. - + - aggminitval - text - - + + aggminitval + text + + The initial value of the transition state for moving-aggregate mod= e. This is a text field containing the initial value in its external string representation. If this field is null, the transition stat= e value starts out null. - + diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.x= sl index 5a27346..861e7ed 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -78,6 +78,16 @@ = + + + + + -3.5em + + + + +