Re: Another modest proposal for docs formatting: catalog descriptions
От | Tom Lane |
---|---|
Тема | Re: Another modest proposal for docs formatting: catalog descriptions |
Дата | |
Msg-id | 1014.1588722172@sss.pgh.pa.us обсуждение исходный текст |
Ответ на | Re: Another modest proposal for docs formatting: catalog descriptions (Tom Lane <tgl@sss.pgh.pa.us>) |
Ответы |
Re: Another modest proposal for docs formatting: catalog descriptions
("Jonathan S. Katz" <jkatz@postgresql.org>)
Re: Another modest proposal for docs formatting: catalog descriptions ("Jonathan S. Katz" <jkatz@postgresql.org>) |
Список | pgsql-docs |
Here's a really quick-n-dirty prototype patch that just converts the pg_aggregate table to the proposed style, plus a screenshot for those who don't feel like actually building the docs with the patch. Looking at the results, it seems like we could really use a bit more horizontal space between the column names and data types, and perhaps also between the types and the (references) annotations. Other than that it looks decent. I don't know what's the cleanest way to add some space there --- I'd rather not have the SGML text do it explicitly. There's room for complaint that this takes up more vertical space than the old way, assuming you have a reasonably wide window. I'm not terribly bothered by that, but maybe someone else will be? I'm inclined to think that that's well worth the benefit that we won't feel compelled to keep column descriptions short. BTW, this being just a test hack, I repurposed the "func_table_entry" and "func_signature" style marker roles. If we do this for real then of course we'd want to use different roles, even if they happen to mark up the same for now. regards, tom lane diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index ce33df9..efb5e64 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -388,178 +388,251 @@ <table> <title><structname>pg_aggregate</structname> Columns</title> - - <tgroup cols="4"> + <tgroup cols="1"> <thead> <row> - <entry>Name</entry> - <entry>Type</entry> - <entry>References</entry> - <entry>Description</entry> + <entry role="func_table_entry"><para role="func_signature"> + Column Type + </para> + <para> + Description + </para></entry> </row> </thead> + <tbody> <row> - <entry><structfield>aggfnoid</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry><structname>pg_proc</structname> OID of the aggregate function</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggfnoid</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + <structname>pg_proc</structname> OID of the aggregate function + </para></entry> </row> <row> - <entry><structfield>aggkind</structfield></entry> - <entry><type>char</type></entry> - <entry></entry> - <entry>Aggregate kind: + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggkind</structfield> + <type>char</type> + </para> + <para> + Aggregate kind: <literal>n</literal> for <quote>normal</quote> aggregates, <literal>o</literal> for <quote>ordered-set</quote> aggregates, or <literal>h</literal> for <quote>hypothetical-set</quote> aggregates - </entry> + </para></entry> </row> <row> - <entry><structfield>aggnumdirectargs</structfield></entry> - <entry><type>int2</type></entry> - <entry></entry> - <entry>Number of direct (non-aggregated) arguments of an ordered-set or + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggnumdirectargs</structfield> + <type>int2</type> + </para> + <para> + Number of direct (non-aggregated) arguments of an ordered-set or hypothetical-set aggregate, counting a variadic array as one argument. If equal to <structfield>pronargs</structfield>, the aggregate must be variadic and the variadic array describes the aggregated arguments as well as the final direct arguments. - Always zero for normal aggregates.</entry> + Always zero for normal aggregates. + </para></entry> </row> <row> - <entry><structfield>aggtransfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Transition function</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggtransfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Transition function + </para></entry> </row> <row> - <entry><structfield>aggfinalfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Final function (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggfinalfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Final function (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggcombinefn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Combine function (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggcombinefn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Combine function (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggserialfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Serialization function (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggserialfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Serialization function (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggdeserialfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Deserialization function (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggdeserialfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Deserialization function (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggmtransfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Forward transition function for moving-aggregate mode (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmtransfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Forward transition function for moving-aggregate mode (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggminvtransfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Inverse transition function for moving-aggregate mode (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggminvtransfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Inverse transition function for moving-aggregate mode (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggmfinalfn</structfield></entry> - <entry><type>regproc</type></entry> - <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> - <entry>Final function for moving-aggregate mode (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmfinalfn</structfield> + <type>regproc</type> + (references <link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Final function for moving-aggregate mode (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggfinalextra</structfield></entry> - <entry><type>bool</type></entry> - <entry></entry> - <entry>True to pass extra dummy arguments to <structfield>aggfinalfn</structfield></entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggfinalextra</structfield> + <type>bool</type> + </para> + <para> + True to pass extra dummy arguments to <structfield>aggfinalfn</structfield> + </para></entry> </row> <row> - <entry><structfield>aggmfinalextra</structfield></entry> - <entry><type>bool</type></entry> - <entry></entry> - <entry>True to pass extra dummy arguments to <structfield>aggmfinalfn</structfield></entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmfinalextra</structfield> + <type>bool</type> + </para> + <para> + True to pass extra dummy arguments to <structfield>aggmfinalfn</structfield> + </para></entry> </row> <row> - <entry><structfield>aggfinalmodify</structfield></entry> - <entry><type>char</type></entry> - <entry></entry> - <entry>Whether <structfield>aggfinalfn</structfield> modifies the + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggfinalmodify</structfield> + <type>char</type> + </para> + <para> + Whether <structfield>aggfinalfn</structfield> modifies the transition state value: <literal>r</literal> if it is read-only, <literal>s</literal> if the <structfield>aggtransfn</structfield> cannot be applied after the <structfield>aggfinalfn</structfield>, or <literal>w</literal> if it writes on the value - </entry> + </para></entry> </row> <row> - <entry><structfield>aggmfinalmodify</structfield></entry> - <entry><type>char</type></entry> - <entry></entry> - <entry>Like <structfield>aggfinalmodify</structfield>, but for + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmfinalmodify</structfield> + <type>char</type> + </para> + <para> + Like <structfield>aggfinalmodify</structfield>, but for the <structfield>aggmfinalfn</structfield> - </entry> + </para></entry> </row> <row> - <entry><structfield>aggsortop</structfield></entry> - <entry><type>oid</type></entry> - <entry><literal><link linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.oid</literal></entry> - <entry>Associated sort operator (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggsortop</structfield> + <type>oid</type> + (references <link linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Associated sort operator (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggtranstype</structfield></entry> - <entry><type>oid</type></entry> - <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry> - <entry>Data type of the aggregate function's internal transition (state) data</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggtranstype</structfield> + <type>oid</type> + (references <link linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Data type of the aggregate function's internal transition (state) data + </para></entry> </row> <row> - <entry><structfield>aggtransspace</structfield></entry> - <entry><type>int4</type></entry> - <entry></entry> - <entry>Approximate average size (in bytes) of the transition state - data, or zero to use a default estimate</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggtransspace</structfield> + <type>int4</type> + </para> + <para> + Approximate average size (in bytes) of the transition state + data, or zero to use a default estimate + </para></entry> </row> <row> - <entry><structfield>aggmtranstype</structfield></entry> - <entry><type>oid</type></entry> - <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry> - <entry>Data type of the aggregate function's internal transition (state) - data for moving-aggregate mode (zero if none)</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmtranstype</structfield> + <type>oid</type> + (references <link linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>) + </para> + <para> + Data type of the aggregate function's internal transition (state) + data for moving-aggregate mode (zero if none) + </para></entry> </row> <row> - <entry><structfield>aggmtransspace</structfield></entry> - <entry><type>int4</type></entry> - <entry></entry> - <entry>Approximate average size (in bytes) of the transition state data - for moving-aggregate mode, or zero to use a default estimate</entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggmtransspace</structfield> + <type>int4</type> + </para> + <para> + Approximate average size (in bytes) of the transition state data + for moving-aggregate mode, or zero to use a default estimate + </para></entry> </row> <row> - <entry><structfield>agginitval</structfield></entry> - <entry><type>text</type></entry> - <entry></entry> - <entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>agginitval</structfield> + <type>text</type> + </para> + <para> 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. - </entry> + </para></entry> </row> <row> - <entry><structfield>aggminitval</structfield></entry> - <entry><type>text</type></entry> - <entry></entry> - <entry> + <entry role="func_table_entry"><para role="func_signature"> + <structfield>aggminitval</structfield> + <type>text</type> + </para> + <para> The initial value of the transition state for moving-aggregate mode. 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. - </entry> + </para></entry> </row> </tbody> </tgroup>
Вложения
В списке pgsql-docs по дате отправления:
Следующее
От: "Jonathan S. Katz"Дата:
Сообщение: Re: Another modest proposal for docs formatting: catalog descriptions