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

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.

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

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

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

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.

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

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

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

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

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

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.

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

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.

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

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

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

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]https://git.postgresql.org/gitweb/?p=pgweb.git;a=commitdiff;h=93716f2a817dbdae8cccf86bc951b45b68ea52d9.

Jonathan

[1]: https://git.postgresql.org/gitweb/?p=pgweb.git;a=commitdiff;h=93716f2a817dbdae8cccf86bc951b45b68ea52d9
https://git.postgresql.org/gitweb/?p=pgweb.git;a=commitdiff;h=93716f2a817dbdae8cccf86bc951b45b68ea52d9

"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