Horton

Thread

Commits

  1. Doc: reformat catalog/view description tables.

  1. Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-05T01:52:29Z

    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
<variablelist>, 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

  2. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-05T02:12:15Z

    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
> <variablelist>, 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

  3. Re: Another modest proposal for docs formatting: catalog descriptions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-05-05T05:52:08Z

    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.

  4. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-05T14:27:53Z

    Fabien COELHO <coelho@cri.ensmp.fr> 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 <structfield> for the field name
and <type> 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 <link> 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

  5. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-05T23:42:52Z

    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

  6. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-06T00:27:46Z

    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

  7. Re: Another modest proposal for docs formatting: catalog descriptions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-05-06T05:52:08Z

    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 <structfield> for the field name
> and <type> 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.

  8. Re: Another modest proposal for docs formatting: catalog descriptions

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-05-06T21:18:36Z

    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?

Thanks

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  9. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-06T21:24:13Z

    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

  10. Re: Another modest proposal for docs formatting: catalog descriptions

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-05-06T21:38:10Z

    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 <computeroutput> 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 <computeroutput> tagged text,
not the table contents text.  (The browser is Brave, a Chromium
derivative.)

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  11. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-06T22:56:40Z

    Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> ... 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.

Huh, browser specific maybe?  The font doesn't seem any smaller to me,
using Safari.

> Anyway, it seems <computeroutput> 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 <computeroutput> tagged text,
> not the table contents text.  (The browser is Brave, a Chromium
> derivative.)

I'm not getting that, either; to me it looks as attached.  I agree
what you're seeing is not as-intended.

			regards, tom lane

  12. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-08T22:53:36Z

    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

  13. Re: Another modest proposal for docs formatting: catalog descriptions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-05-09T06:54:10Z

    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:

   attribute        type
   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.

  14. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-09T15:34:24Z

    Fabien COELHO <coelho@cri.ensmp.fr> writes:
>> 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?

BTW, I don't think it's very accurate that "attribute names are
always one word" --- see the second attachment.  Here if anything
I'm wanting a little more space.

> 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.  It could be done no doubt, but I think
people would not see it as an improvement.

			regards, tom lane

  15. Re: Another modest proposal for docs formatting: catalog descriptions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2020-05-09T17:30:11Z

    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.

  16. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-09T18:09:01Z

    Fabien COELHO <coelho@cri.ensmp.fr> 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 <variablelist>s, which this layout is based on.

			regards, tom lane

  17. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-10T16:27:23Z

    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

  18. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-10T18:03:32Z

    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

  19. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-14T02:27:33Z

    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

  20. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-14T02:52:29Z

    "Jonathan S. Katz" <jkatz@postgresql.org> 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

  21. Re: Another modest proposal for docs formatting: catalog descriptions

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-05-18T20:11:29Z

    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 Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  22. Re: Another modest proposal for docs formatting: catalog descriptions

    Josef Šimánek <josef.simanek@gmail.com> — 2020-06-01T22:40:09Z

    út 2. 6. 2020 v 0:30 odesílatel Tom Lane <tgl@sss.pgh.pa.us> 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
> <variablelist>, 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
>
>
>
>
>

  23. Re: Another modest proposal for docs formatting: catalog descriptions

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-06-01T22:57:55Z

    =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> 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

  24. Re: Another modest proposal for docs formatting: catalog descriptions

    Jonathan S. Katz <jkatz@postgresql.org> — 2020-06-01T23:17:17Z

    On 6/1/20 6:57 PM, Tom Lane wrote:
> =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> 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