Re: Another modest proposal for docs formatting: catalog descriptions
út 2. 6. 2020 v 0:30 odesílatel Tom Lane napsal: > As of HEAD, building the PDF docs for A4 paper draws 538 "contents > ... exceed the available area" warnings. While this is a nice step > forward from where we were (v12 has more than 1500 such warnings), > we're far from done fixing that issue. > > A large chunk of the remaining warnings are about tables that describe > the columns of system catalogs, system views, and information_schema > views. The typical contents of a row in such a table are a field name, > a field data type, possibly a "references" link, and then a description. > Unsurprisingly, this does not work very well for descriptions of more > than a few words. And not infrequently, we *need* more than a few words. > > ISTM this is more or less the same problem we have/had with function > descriptions, and so I'm tempted to solve it in more or less the same > way. Let's redefine the table layout to look like, say, this for > pg_attrdef [1]: > > 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. > > That is, let's go over to something that's more or less like a table-ized > , with the fixed items for an entry all written on the first > line, and then as much description text as we need. The actual markup > would be closely modeled on what we did for function-table entries. > > Thoughts? > I have spotted this change recently at progress monitoring devel docs ( https://www.postgresql.org/docs/devel/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING). Current version seems a little chaotic since there are multiple tables on the same page with 2 mixed layouts. Older layout (for example v12 one - https://www.postgresql.org/docs/12/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) is much easier to read for me. Is this final change? I do not see any problem on this (progress monitoring) page in old layout. Is there any example of problematic page? Maybe there's a different way to solve this. For example instead of in-lining long text as a column description, it should be possible to link to detailed description in custom paragraph or table. See description column at table 27.22. at progress monitoring page for column "phase" for similar approach. > > regards, tom lane > > [1] https://www.postgresql.org/docs/devel/catalog-pg-attrdef.html > > > > >
Re: Another modest proposal for docs formatting: catalog descriptions
=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= writes: > I have spotted this change recently at progress monitoring devel docs ( > https://www.postgresql.org/docs/devel/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING). > Current version seems a little chaotic since there are multiple tables on > the same page with 2 mixed layouts. Older layout (for example v12 one - > https://www.postgresql.org/docs/12/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) > is much easier to read for me. > Is this final change? I do not see any problem on this (progress > monitoring) page in old layout. Is there any example of problematic page? > Maybe there's a different way to solve this. For example instead of > in-lining long text as a column description, it should be possible to link > to detailed description in custom paragraph or table. See description > column at table 27.22. at progress monitoring page for column "phase" for > similar approach. I'm not planning on revisiting that work, no. And converting every table/view description table into two (or more?) tables sure doesn't sound like an improvement. Perhaps there's a case for reformatting the phase-description tables in the progress monitoring section to look more like the view tables. (I hadn't paid much attention to them, since they weren't causing PDF rendering problems.) On the other hand, you could argue that it's good that they don't look like the view tables, since the info they are presenting is fundamentally different. I don't honestly see much wrong with the way it is now. regards, tom lane
Re: Another modest proposal for docs formatting: catalog descriptions
On 6/1/20 6:57 PM, Tom Lane wrote: > =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= writes: >> I have spotted this change recently at progress monitoring devel docs ( >> https://www.postgresql.org/docs/devel/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING). >> Current version seems a little chaotic since there are multiple tables on >> the same page with 2 mixed layouts. Older layout (for example v12 one - >> https://www.postgresql.org/docs/12/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) >> is much easier to read for me. > >> Is this final change? I do not see any problem on this (progress >> monitoring) page in old layout. Is there any example of problematic page? >> Maybe there's a different way to solve this. For example instead of >> in-lining long text as a column description, it should be possible to link >> to detailed description in custom paragraph or table. See description >> column at table 27.22. at progress monitoring page for column "phase" for >> similar approach. > > I'm not planning on revisiting that work, no. And converting every > table/view description table into two (or more?) tables sure doesn't > sound like an improvement. > > Perhaps there's a case for reformatting the phase-description tables > in the progress monitoring section to look more like the view tables. > (I hadn't paid much attention to them, since they weren't causing PDF > rendering problems.) On the other hand, you could argue that it's > good that they don't look like the view tables, since the info they > are presenting is fundamentally different. I don't honestly see much > wrong with the way it is now. I think it looks fine. +1 for leaving it. Jonathan signature.asc Description: OpenPGP digital signature
Re: wal_init_zero and wal_recycle
On 2020/05/29 13:13, Fujii Masao wrote: On 2020/05/28 8:43, Thomas Munro wrote: On Wed, May 27, 2020 at 7:09 PM Simon Riggs wrote: On Wed, 27 May 2020 at 04:27, Fujii Masao wrote: Hi, The group of wal_init_zero and wal_recycle is WAL_SETTINGS in guc.c, but their descriptions are located in "19.6. Replication"/"19.6.1. Sending Servers" section. This seems a documentation bug. They should be located in "19.5. Write Ahead Log"/"19.5.1. Settings". Thought? +1 Thanks! Patch attached. Since they are located just before wal_buffers in postgresql.conf.sample, I moved the descriptions of them also just before that of wal_buffers in "Write Ahead Log"/"Settings" section. Barring any objection, I will commit this patch. Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
