Re: Another modest proposal for docs formatting: catalog descriptions

2020-06-01 Thread Jonathan S. Katz
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 sinc

Re: Another modest proposal for docs formatting: catalog descriptions

2020-06-01 Thread Tom Lane
=?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 sam

Re: Another modest proposal for docs formatting: catalog descriptions

2020-06-01 Thread Josef Šimánek
ú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.

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-18 Thread Alvaro Herrera
On 2020-May-06, Alvaro Herrera wrote: > ... oh, okay. I guess I was reporting that the font on the new version > seems to have got smaller. Looking at other pages, it appears that the > font is indeed a lot smaller in all tables, including those Tom has been > editing. So maybe this is desirabl

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-13 Thread Tom Lane
"Jonathan S. Katz" writes: > Time slipped a bit (sorry!), but while prepping for the release I > reviewed this. Visually, it looks WAY better. The code checks out too. I > think any tweaks would be primarily around personal preference on the > UI, so it may be better just to commit and get it out

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-13 Thread Jonathan S. Katz
On 5/10/20 2:03 PM, Jonathan S. Katz wrote: > On 5/10/20 12:27 PM, Tom Lane wrote: >> Just FTR, here's a complete patch for this. > > Cool. I'll play around with it tonight once I clear out release work. > Per upthread reference, I believe you've become a CSS maven yourself. Time slipped a bit (

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-10 Thread Jonathan S. Katz
On 5/10/20 12:27 PM, Tom Lane wrote: > Just FTR, here's a complete patch for this. Cool. I'll play around with it tonight once I clear out release work. Per upthread reference, I believe you've become a CSS maven yourself. > I successfully regenerated > the column names, types, and ordering from

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-10 Thread Tom Lane
Just FTR, here's a complete patch for this. I successfully regenerated the column names, types, and ordering from the system catalogs, and plugged the descriptions back into that by dint of parsing them out of the XML. The "references" data was based on findoidjoins' results plus hand additions t

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-09 Thread Tom Lane
Fabien COELHO writes: > Possibly. I'm a little at odds with Type not being above types, but far on > the left, so that you cannot really "see" that it is about the format, Yeah, agreed. We can adjust the space in the header independently of what's in the table entries, so it'd be possible to p

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-09 Thread Fabien COELHO
Hello Tom, Here's a more fully fleshed out draft for this, with stylesheet markup to get extra space around the column type names. I find this added spacing awkward, espacially as attribute names are always one word anyway. I prefer the non spaced approach. It's certainly arguable that tha

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-08 Thread Fabien COELHO
Hello Tom, Here's a more fully fleshed out draft for this, with stylesheet markup to get extra space around the column type names. I find this added spacing awkward, espacially as attribute names are always one word anyway. I prefer the non spaced approach. If spacing is discussed, should

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-06 Thread Alvaro Herrera
On 2020-May-06, Jonathan S. Katz wrote: > I know that 9.6 uses a different subset of the styles, and I recall the > text being blue during the original conversion. For example, the "table" > in the 9.6 docs has a class of "CALSTABLE" whereas in master, it is > "table" (and we operate off of it as

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-06 Thread Jonathan S. Katz
On 5/6/20 5:18 PM, Alvaro Herrera wrote: > Hello > > I think the recent changes to CSS might have broken things in the XSLT > build; apparently the SGML tooling did things differently. Compare the > screenshot of tables 67.2 and 67.3 ... 9.6 on the left, master on the > right. Is the latter form

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-05 Thread Fabien COELHO
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

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-05 Thread Jonathan S. Katz
On 5/5/20 7:42 PM, Tom Lane wrote: > 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. Not opposed to building the docs, but the screenshot ex

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-05 Thread Tom Lane
Fabien COELHO writes: > 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? Meh. I'm n

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-04 Thread Fabien COELHO
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

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-04 Thread Jonathan S. Katz
On 5/4/20 9:52 PM, Tom Lane wrote: > 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 ch