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: 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
ú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
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 desirable for some reason. I'll have to keep > my magnifying glass handy, I suppose. I happened to notice that the font used in the tables get smaller if you make the browser window narrower. So what was happening is that I was using a window that didn't cover the entire screen. If I let the window use my whole screen, the font in the table is the same size than the text outside the table; if I reduce to ~1239 pixels, the font becomes somewhat smaller; if I further reduce to ~953 pixels, it gets really small. Meanwhile, the non-table text keeps the same size the whole time. (The pixel sizes at which changes occur seem to vary with the zoom percentage I use, but the behavior is always there.) Is this something that CSS does somehow? Is this something you expected? Happens with both Brave (a Chromium derivate) and Firefox. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Another modest proposal for docs formatting: catalog descriptions
"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 in the wild. > ...and so I did. Committed[1]. Thanks, I'll push the docs change in a bit. regards, tom lane
Re: Another modest proposal for docs formatting: catalog descriptions
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 (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 in the wild. ...and so I did. Committed[1]. Jonathan [1] https://git.postgresql.org/gitweb/?p=pgweb.git;a=commitdiff;h=93716f2a817dbdae8cccf86bc951b45b68ea52d9 signature.asc Description: OpenPGP digital signature
Re: Another modest proposal for docs formatting: catalog descriptions
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 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 to cover all the cases we are calling out now (there are > a lot of "references" links for attnums and a few other non-OID columns, > plus references links for views which findoidjoins doesn't consider). > So I have pretty high confidence that this info is OK. I'd be too > embarrassed to show anybody the code though ;-) ... it was just a brute > force hack. If it works it works ;) Jonathan signature.asc Description: OpenPGP digital signature
Re: Another modest proposal for docs formatting: catalog descriptions
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 to cover all the cases we are calling out now (there are
a lot of "references" links for attnums and a few other non-OID columns,
plus references links for views which findoidjoins doesn't consider).
So I have pretty high confidence that this info is OK. I'd be too
embarrassed to show anybody the code though ;-) ... it was just a brute
force hack.
regards, tom lane
catalog-reformat.patch.gz
Description: catalog-reformat.patch.gz
--- main.css~ 2020-05-10 12:18:39.773129302 -0400
+++ main.css 2020-05-09 21:46:22.424776849 -0400
@@ -792,13 +792,6 @@
}
/** Formatting for entries in tables of functions: indent all but first line **/
-#docContent table.table th.functableentry,
-#docContent table.table td.functableentry {
- padding-left: 4em;
- text-indent: -3.5em;
- text-align: left;
-}
-
#docContent table.table th.func_table_entry p,
#docContent table.table td.func_table_entry p {
margin-top: 0.1em;
@@ -820,6 +813,38 @@
padding-left: 4em;
}
+/** Formatting for entries in tables of catalog/view columns **/
+#docContent table.table th.catalog_table_entry p,
+#docContent table.table td.catalog_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+ text-align: left;
+}
+
+#docContent table.table th.catalog_table_entry p.column_definition {
+ text-indent: -3.5em;
+ word-spacing: 0.25em;
+}
+
+#docContent table.table td.catalog_table_entry p.column_definition {
+ text-indent: -3.5em;
+}
+
+#docContent table.table p.column_definition code.type {
+ padding-left: 0.25em;
+ padding-right: 0.25em;
+}
+
+#docContent table.table td.catalog_table_entry pre.programlisting {
+ background-color: inherit;
+ border: 0;
+ margin-bottom: 0.1em;
+ margin-top: 0.1em;
+ padding: 0;
+ padding-left: 4em;
+}
+
/**
* Titles, Navigation
*/
Re: Another modest proposal for docs formatting: catalog descriptions
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 put more space between "Column" and "Type" ... but I'm not sure if that would fix it. > If I can suggest more adjustements, maybe the description margin is a too > much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic > opinion is by definition subjective and prone to differ from one person to > the next… This is more Jonathan's department than mine, but I personally prefer more indentation to less --- you want the column names to stick out so you can find them. Anyway, the present indentation is (it looks like) the same as we are using in s, which this layout is based on. regards, tom lane
Re: Another modest proposal for docs formatting: catalog descriptions
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 that look is too heavy-handed. In the attached, I knocked down the extra space from 1em to 0.25em, which makes it quite a bit subtler --- are you any happier with this? Yes, definitely. BTW, I don't think it's very accurate that "attribute names are always one word" --- see the second attachment. Indeed. Here if anything I'm wanting a little more space. I'm fine with 0.25em which allows some breathing without looking awkward. Maybe a little more would still be okay, but not much more. If spacing is discussed, should the layout rather try to align type information, eg: I thought about that, but it seems extremely close to some of the earlier function-table layouts that were so widely panned. The SGML source would have to be a lot uglier too, probably with explicit use of spanspec's on every row. Hmmm, that's the kind of things I was afraid of. It could be done no doubt, but I think people would not see it as an improvement. 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, especially with long attribute names: Column Type Description quite_a_long_attribute and_its_type ... The horizontal distance between "Type" and "and_its_type" is so wide as to hide the clue that the former is describing the later. But maybe aligning would be too ugly. If I can suggest more adjustements, maybe the description margin is a too much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic opinion is by definition subjective and prone to differ from one person to the next… -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
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 the layout rather try to align type information, eg: attributetype description --- foo bla this does this and that ... and here is an example about it --- foo-foo-foo bla-bla whatever bla bla blah bla foo foo foo ... and stuff I'm not sure how achievable it is from a xml & processing point of view, and how desirable it is, I'm just throwing it for consideration. -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
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 "table.table" when doing lookups, > to ensure anything else with class "table" is unaffected). > > There's also not as much control over some of the older documentation as > there are less classes we can bind the CSS too. > > The latest changes should only affect master (devel) and beyond. ... 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 desirable for some reason. I'll have to keep my magnifying glass handy, I suppose. Anyway, it seems or whatever tag has been used in some of these new tables makes the font be larger. Another screenshot is attached to show this. Is this likewise desired? It also shows that the main text body is sized similar to the tagged text, not the table contents text. (The browser is Brave, a Chromium derivative.) -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Another modest proposal for docs formatting: catalog descriptions
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 formatting correct/desirable? 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 "table.table" when doing lookups, to ensure anything else with class "table" is unaffected). There's also not as much control over some of the older documentation as there are less classes we can bind the CSS too. The latest changes should only affect master (devel) and beyond. Jonathan signature.asc Description: OpenPGP digital signature
Re: Another modest proposal for docs formatting: catalog descriptions
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 under the hood. I found "oid oid" stuttering kind of strange, hence an attempt at suggesting something that could distinguish them. The markup I had in mind was for the field name and for the type name, but no decoration beyond that. Ok. If they are displayed a little differently afterwards that'd may help. As for the references, it seems to me that your notation would lead people to think that there are actual FK constraints in place, which of course there are not (especially not on the views). In practice the system ensures that the target exists, so it is as-if there would be a foreign key enforced? My point is that using differing syntaxes for the more-or-less the same concept does not help user understand the semantics, but maybe that is just me. I'm not hugely against it but I prefer what I suggested. Ok! -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
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 expedites things ;) > 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. If each element (i.e. column name, data type) is wrapped in a HTML element with its own class (e.g. a span) it's fairly easy to add that space with CSS. I'm not sure the ramifications for the PDFs though. > 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. I think for reference materials, vertical space is acceptable. It seems to be the "mobile way" of doing things, since people are scrolling down. (And unlike the mailing lists, we don't need to keep the font small ;) Anyway, +1 > 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. Agreed. Thanks, Jonathan signature.asc Description: OpenPGP digital signature
Re: Another modest proposal for docs formatting: catalog descriptions
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 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 under the hood. The markup I had in mind was for the field name and for the type name, but no decoration beyond that. As for the references, it seems to me that your notation would lead people to think that there are actual FK constraints in place, which of course there are not (especially not on the views). I'm not hugely against it but I prefer what I suggested. > I guess that reference targets would still be navigable. Yeah, they'd still have wrappers --- if I recall what those look like in the documentation sources, they don't need any change except for addition of the "(references ...)" text. regards, tom lane
Re: Another modest proposal for docs formatting: catalog descriptions
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.
Re: Another modest proposal for docs formatting: catalog descriptions
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 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? +1. Looks easy enough to read in a plaintext email, and if there are any minor style nuances on the HTML front, I'm confident we'll solve them. Jonathan signature.asc Description: OpenPGP digital signature
Another modest proposal for docs formatting: catalog descriptions
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? regards, tom lane [1] https://www.postgresql.org/docs/devel/catalog-pg-attrdef.html
