Re: Poll: are people okay with function/operator table redesign?
Oleksandr Shulgin writes:
> Would it be premature to complain about the not-that-great look of Table
> 9.1 now?
> Compare the two attached images: the screenshot from
> https://www.postgresql.org/docs/devel/functions-comparison.html
> vs the GIMP-assisted pipe dream of mine to align it to the right edge of
> the table cell.
Hmph. I experimented with the attached patch, but at least in my browser
it only reduces the spacing inconsistency, it doesn't eliminate it.
And from a semantic standpoint, this is not nice markup.
Doing better would require substantial foolery with sub-columns and I'm
not even sure that it's possible to fix that way. (We don't have huge
control over inter-column spacing, I don't think.)
On the whole, if this is our worst table problem, I'm happy ;-)
regards, tom lane
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index d9b3598..557a3ac 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -222,7 +222,7 @@ repeat('Pg', 4) PgPgPgPg
-datatype datatype
+datatype datatype
boolean
Less than
@@ -230,7 +230,7 @@ repeat('Pg', 4) PgPgPgPg
-datatype datatype
+datatype datatype
boolean
Greater than
@@ -254,7 +254,7 @@ repeat('Pg', 4) PgPgPgPg
-datatype = datatype
+datatype = datatype
boolean
Equal
Re: Poll: are people okay with function/operator table redesign?
Dean Rasheed writes: > On Mon, 4 May 2020 at 22:22, Tom Lane wrote: >> Now I could have done this example by spelling out all six varieties of >> stddev() separately, and maybe I should've, but it seemed overly bulky >> that way. > FWIW, I prefer having each variety spelled out separately. For > example, I really like the new way that aggregates like sum() and > avg() are displayed. To me, having all the types listed like that is > much more readable than having to read and interpret a piece of free > text. > Similarly, for other functions like gcd(), lcm() and mod(). I think it > would be better to get rid of numeric_type, and just list all the > variants of each function. I had had the same idea to start with, but it didn't survive first contact with table 9.4 (Mathematical Operators). It's not really reasonable to spell out all the variants of + ... especially not if you want to be precise, because then you'd have to list the cross-type variants too. If I counted correctly, there are fourteen variants of binary + that would have to be listed in that table, never mind the other common operators. max() and min() have a similar sort of problem --- the list of variants is just dauntingly long, and it's not that interesting either. I wrote out sum() and avg() the way I did because they have a somewhat irregular mapping from input to output types, so it seemed better to just list the alternatives explicitly. I don't object too much to spelling out the variants of stddev() and variance(), if there's a consensus for that. But getting rid of "numeric_type" entirely seems impractical. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Mon, May 4, 2020 at 11:22 PM Tom Lane wrote: > I've now completed updating chapter 9 for the new layout, > and the results are visible at > https://www.postgresql.org/docs/devel/functions.html > There is more to do --- for instance, various contrib modules > have function/operator tables that should be synced with this > design. But this seemed like a good place to pause and reflect. > Would it be premature to complain about the not-that-great look of Table 9.1 now? Compare the two attached images: the screenshot from https://www.postgresql.org/docs/devel/functions-comparison.html vs the GIMP-assisted pipe dream of mine to align it to the right edge of the table cell. I don't have the faintest idea how to achieve that using SGML at the moment, but it just looks so much nicer to me. ;-) Regards, -- Alex
Re: Poll: are people okay with function/operator table redesign?
On Mon, 4 May 2020 at 22:22, Tom Lane wrote: > > * is also quite sticky about inserting other sorts > of font-changing environments inside it. As an example, it'll let > you include but not , which seems pretty weird > to me. This is problematic in some places where it's desirable to > have text rather than just a type name, for example > > stddev ( numeric_type > ) > double precision > for real or double precision, > otherwise numeric > > Now I could have done this example by spelling out all six varieties of > stddev() separately, and maybe I should've, but it seemed overly bulky > that way. FWIW, I prefer having each variety spelled out separately. For example, I really like the new way that aggregates like sum() and avg() are displayed. To me, having all the types listed like that is much more readable than having to read and interpret a piece of free text. Similarly, for other functions like gcd(), lcm() and mod(). I think it would be better to get rid of numeric_type, and just list all the variants of each function. Regards, Dean
Re: Poll: are people okay with function/operator table redesign?
On 5/4/20 6:39 PM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> On 5/4/20 5:22 PM, Tom Lane wrote: >> It does look better, but things look a bit smushed together on the pgweb >> front. > > Yeah. There's less smushing of function signatures when building the > docs without STYLE=website, so there's something specific to the > website style. I think you'd mentioned that we were intentionally > crimping the space and/or font size within tables? Maybe that could > get un-done now. I hadn't bothered to worry about such details until > we had a reasonable sample of cases to look at, but now would be a > good time. IIRC this was the monospace issue[1], but there are some other things I'm seeing (e.g. the italics) that may be pushing things closer together htan not. Now that round 1 of commits are in, I can take a whack at tightening it up this week. > Another rendering oddity that I'd not bothered to chase down is > the appearance of environments within table cells. > We have a few of those now as a result of migration of material > that had been out-of-line into the table cells; one example is > in json_populate_record, about halfway down this page: > > https://www.postgresql.org/docs/devel/functions-json.html > > The text of the list items seems to be getting indented to the > same extent as a not-in-a-table list does --- > but the bullets aren't indented nearly as much, making for > weird spacing. (There's a short at the top of > the same page that you can compare to.) Looking at the code, I believe this is a pretty straightforward adjustment. I can include it with the aforementioned changes. Jonathan [1] https://www.postgresql.org/message-id/3f8560a6-9044-bdb8-6b3b-68842570d...@postgresql.org signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > On 5/4/20 5:22 PM, Tom Lane wrote: >> I've now completed updating chapter 9 for the new layout, >> and the results are visible at >> https://www.postgresql.org/docs/devel/functions.html > This is already much better. I've skimmed through a few of the pages, I > can say that the aggregates page[1] is WAY easier to read. Yay! Thanks! >> * After experimenting with a few different ways to handle functions with >> multiple OUT parameters, I settled on doing it like this: >> pg_partition_tree ( regclass ) >> setof record >> ( relid regclass, >> parentrelid regclass, >> isleaf boolean, >> level integer ) >> >> This looks nice and I think it's much more intelligible than other >> things I tried --- in particular, including the OUT parameters in >> the function signature seems to me to be mostly confusing. But, >> once again, it's abusing the concept that contains >> the result type. Ideally the output-column list would be inside >> the environment, but DocBook won't allow that >> because of the tags. > It does look better, but things look a bit smushed together on the pgweb > front. Yeah. There's less smushing of function signatures when building the docs without STYLE=website, so there's something specific to the website style. I think you'd mentioned that we were intentionally crimping the space and/or font size within tables? Maybe that could get un-done now. I hadn't bothered to worry about such details until we had a reasonable sample of cases to look at, but now would be a good time. Another rendering oddity that I'd not bothered to chase down is the appearance of environments within table cells. We have a few of those now as a result of migration of material that had been out-of-line into the table cells; one example is in json_populate_record, about halfway down this page: https://www.postgresql.org/docs/devel/functions-json.html The text of the list items seems to be getting indented to the same extent as a not-in-a-table list does --- but the bullets aren't indented nearly as much, making for weird spacing. (There's a short at the top of the same page that you can compare to.) The same weird spacing is visible in a non STYLE=website build, so I think this might be less a CSS issue and more a DocBook issue. On the other hand, it looks fine in the PDF build. So I'm not sure where to look for the cause. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 5/4/20 5:22 PM, Tom Lane wrote:
> I've now completed updating chapter 9 for the new layout,
> and the results are visible at
> https://www.postgresql.org/docs/devel/functions.html
> There is more to do --- for instance, various contrib modules
> have function/operator tables that should be synced with this
> design. But this seemed like a good place to pause and reflect.
This is already much better. I've skimmed through a few of the pages, I
can say that the aggregates page[1] is WAY easier to read. Yay!
>
> After working through the whole chapter, the only aspect of the
> new markup that really doesn't seem to work so well is the use
> of for function result types and example results.
> While I don't think that that's broken in concept, DocBook has
> restrictions on the contents of that are problematic:
>
> * It won't let you put any verbatim-layout environment, such
> as , inside . This is an issue for
> examples for set-returning functions in particular. I've done
> those like this:
>
>
> regexp_matches('foobarbequebaz', 'ba.', 'g')
>
>
> {bar}
> {baz}
>
> (2 rows in result)
>
>
> where the empty environment is just serving to generate a
> right arrow. It looks all right, but it's hardly semantically-based
> markup.
We could apply some CSS on the pgweb front perhaps to help distinguish
at least the results? For the above example, it would be great to
capture the program listing + "2 rows in result" output and format them
similarly, though it appears the "(2 rows in result)" is in its own block.
Anyway, likely not that hard to apply some CSS and make it appear a bit
more distinguished, if that's the general idea.
> * is also quite sticky about inserting other sorts
> of font-changing environments inside it. As an example, it'll let
> you include but not , which seems pretty weird
> to me. This is problematic in some places where it's desirable to
> have text rather than just a type name, for example
>
> stddev ( numeric_type
> )
> double precision
> for real or double precision,
> otherwise numeric
>
> Now I could have done this example by spelling out all six varieties of
> stddev() separately, and maybe I should've, but it seemed overly bulky
> that way. So again is just generating the right arrow.
>
> * After experimenting with a few different ways to handle functions with
> multiple OUT parameters, I settled on doing it like this:
>
> pg_partition_tree ( regclass )
> setof record
> ( relid regclass,
> parentrelid regclass,
> isleaf boolean,
> level integer )
>
> This looks nice and I think it's much more intelligible than other
> things I tried --- in particular, including the OUT parameters in
> the function signature seems to me to be mostly confusing. But,
> once again, it's abusing the concept that contains
> the result type. Ideally the output-column list would be inside
> the environment, but DocBook won't allow that
> because of the tags.
It does look better, but things look a bit smushed together on the pgweb
front. It seems like there's enough structure where one can make some
not-too-zany CSS rules to put a bit more space between elements, but
perhaps wait to hear the decision on the rest of the structural questions.
> So at this point I'm tempted to abandon and go back
> to using a custom entity to generate the right arrow, so that
> the markup would just look like, say,
>
> stddev ( numeric_type
> )
> double precision
> for real or double precision,
> otherwise numeric
>
> Does anyone have a preference on that, or a better alternative?
As long as we can properly style without zany CSS rules, I'm +0 :)
Jonathan
[1] https://www.postgresql.org/docs/devel/functions-aggregate.html
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
I've now completed updating chapter 9 for the new layout,
and the results are visible at
https://www.postgresql.org/docs/devel/functions.html
There is more to do --- for instance, various contrib modules
have function/operator tables that should be synced with this
design. But this seemed like a good place to pause and reflect.
After working through the whole chapter, the only aspect of the
new markup that really doesn't seem to work so well is the use
of for function result types and example results.
While I don't think that that's broken in concept, DocBook has
restrictions on the contents of that are problematic:
* It won't let you put any verbatim-layout environment, such
as , inside . This is an issue for
examples for set-returning functions in particular. I've done
those like this:
regexp_matches('foobarbequebaz', 'ba.', 'g')
{bar}
{baz}
(2 rows in result)
where the empty environment is just serving to generate a
right arrow. It looks all right, but it's hardly semantically-based
markup.
* is also quite sticky about inserting other sorts
of font-changing environments inside it. As an example, it'll let
you include but not , which seems pretty weird
to me. This is problematic in some places where it's desirable to
have text rather than just a type name, for example
stddev ( numeric_type )
double precision
for real or double precision,
otherwise numeric
Now I could have done this example by spelling out all six varieties of
stddev() separately, and maybe I should've, but it seemed overly bulky
that way. So again is just generating the right arrow.
* After experimenting with a few different ways to handle functions with
multiple OUT parameters, I settled on doing it like this:
pg_partition_tree ( regclass )
setof record
( relid regclass,
parentrelid regclass,
isleaf boolean,
level integer )
This looks nice and I think it's much more intelligible than other
things I tried --- in particular, including the OUT parameters in
the function signature seems to me to be mostly confusing. But,
once again, it's abusing the concept that contains
the result type. Ideally the output-column list would be inside
the environment, but DocBook won't allow that
because of the tags.
So at this point I'm tempted to abandon and go back
to using a custom entity to generate the right arrow, so that
the markup would just look like, say,
stddev ( numeric_type )
double precision
for real or double precision,
otherwise numeric
Does anyone have a preference on that, or a better alternative?
regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 11:26 PM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> Clearly I was caught doing a single browser test (Chrome). > > Well, I've not tested anything but Safari, either ... > >> Reverted back to the verbose way sans !important, attached, which >> appears to be the consensus. If you can ACK this, I'll commit. > > This one works for me. Pushed. Thanks! Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > Clearly I was caught doing a single browser test (Chrome). Well, I've not tested anything but Safari, either ... > Reverted back to the verbose way sans !important, attached, which > appears to be the consensus. If you can ACK this, I'll commit. This one works for me. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 10:38 PM, Tom Lane wrote:
> "Jonathan S. Katz" writes:
>> Please see latest attached. I've eliminated the !important, condensed
>> the CSS, and the desultory (yes, my word of the week) testing did not
>> find issues in devel or earlier versions.
>
>> Please let me know if this works for you. If it does, I'll push it up to
>> pgweb.
>
> NAK ... that does *not* work for me.
Learned a new acronym...
> It looks to me like you are expecting that "margin" with four parameters
> will override an outer-level setting of margin-bottom, but that is not
> how my browser is responding. ISTM you need to explicitly set the very
> same parameters in the more-specific rule as in the less-specific rule
> that you want to override.
>
> I get reasonable results with these settings, but not with
> anything more abbreviated:
> In particular, it might look like the multiple padding settings
> in the pre.programlisting rule are redundant ... but they are not, at
> least not with Safari.
Clearly I was caught doing a single browser test (Chrome).
Reverted back to the verbose way sans !important, attached, which
appears to be the consensus. If you can ACK this, I'll commit.
Thanks,
Jonathan
diff --git a/media/css/main.css b/media/css/main.css
index 08ca255..2b4831d 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -625,7 +625,7 @@ ul.actions {
}
#docContent p {
- margin-bottom: 1rem !important;
+ margin-bottom: 1rem;
}
#docContent hr {
@@ -648,7 +648,7 @@ ul.actions {
}
#docContent pre {
- padding: 0.8rem !important;
+ padding: 0.8rem;
}
pre,
@@ -658,7 +658,7 @@ code,
#docContent tt.REPLACEABLE {
font-size: 0.9rem !important;
color: inherit !important;
- background-color: #f8f9fa !important;
+ background-color: #f8f9fa;
border-radius: .25rem;
margin: .6rem 0;
font-weight: 300;
@@ -799,6 +799,27 @@ code,
text-align: left;
}
+#docContent table.table th.func_table_entry p,
+#docContent table.table td.func_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+ text-align: left;
+}
+
+#docContent table.table p.func_signature {
+ text-indent: -3.5em;
+}
+
+#docContent table.table td.func_table_entry pre.programlisting {
+ background-color: inherit;
+ border: 0;
+ margin-bottom: 0.1em;
+ margin-top: 0.1em;
+ padding: 0;
+ padding-left: 4em;
+}
+
/**
* Titles, Navigation
*/
@@ -1059,7 +1080,7 @@ i.fas.fa-search {
pre {
padding: 0.8rem;
border: 1px solid #ced4da;
- margin: 1rem 0 !important;
+ margin: 1rem 0;
}
pre.code {
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes:
> Please see latest attached. I've eliminated the !important, condensed
> the CSS, and the desultory (yes, my word of the week) testing did not
> find issues in devel or earlier versions.
> Please let me know if this works for you. If it does, I'll push it up to
> pgweb.
NAK ... that does *not* work for me.
It looks to me like you are expecting that "margin" with four parameters
will override an outer-level setting of margin-bottom, but that is not
how my browser is responding. ISTM you need to explicitly set the very
same parameters in the more-specific rule as in the less-specific rule
that you want to override.
I get reasonable results with these settings, but not with
anything more abbreviated:
#docContent table.table th.func_table_entry p,
#docContent table.table td.func_table_entry p {
margin-top: 0.1em;
margin-bottom: 0.1em;
padding-left: 4em;
text-align: left;
}
#docContent table.table p.func_signature {
text-indent: -3.5em;
}
#docContent table.table td.func_table_entry pre.programlisting {
background-color: inherit;
border: 0;
margin-top: 0.1em;
margin-bottom: 0.1em;
padding: 0;
padding-left: 4em;
}
In particular, it might look like the multiple padding settings
in the pre.programlisting rule are redundant ... but they are not, at
least not with Safari.
regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 9:22 PM, Jonathan S. Katz wrote:
> On 4/29/20 8:15 PM, Tom Lane wrote:
>> "Jonathan S. Katz" writes:
>>> On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
I'll compromise on the temporary importants, but first I want to see
what's causing the need for it. Do you have a suggestion on a page to test?
>>
>> I haven't yet pushed anything dependent on the new markup, but
>> attached is a draft revision for the JSON section; if you look at
>> the SRFs such as json_array_elements you'll see the issue.
^ This was super helpful. Built locally, and made it really easy to
test. Thanks!
>>> From real quick I got it to here. With the latest copy of the doc builds
>>> it appears to still work as expected, but I need a section with the new
>>> "pre" block to test.
>>
>> Yeah, I see you found the same and settings I did.
>>
>>> I think the "background-color: inherit !important" is a bit odd, and
>>> would like to trace that one down a bit more, but I did not see anything
>>> obvious on my glance through it.
>>
>> I think it's coming from this bit at about main.css:660:
>>
>> pre,
>> code,
>> #docContent kbd,
>> #docContent tt.LITERAL,
>> #docContent tt.REPLACEABLE {
>> font-size: 0.9rem !important;
>> color: inherit !important;
>> background-color: #f8f9fa !important;
>> border-radius: .25rem;
>> margin: .6rem 0;
>> font-weight: 300;
>> }
>>
>> I had to override most of that.
>
> Yeah, I had started toying with that and saw no differences, but I would
> need to test against anything in particular. I'm pretty confident we can
> remove those importants, based on my desultory testing.
>
> I'll try and get the patch built + docs loaded, and see if we can safely
> remove those.
Please see latest attached. I've eliminated the !important, condensed
the CSS, and the desultory (yes, my word of the week) testing did not
find issues in devel or earlier versions.
Please let me know if this works for you. If it does, I'll push it up to
pgweb.
Jonathan
diff --git a/media/css/main.css b/media/css/main.css
index 08ca255..07963f2 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -625,7 +625,7 @@ ul.actions {
}
#docContent p {
- margin-bottom: 1rem !important;
+ margin-bottom: 1rem;
}
#docContent hr {
@@ -648,7 +648,7 @@ ul.actions {
}
#docContent pre {
- padding: 0.8rem !important;
+ padding: 0.8rem;
}
pre,
@@ -658,7 +658,7 @@ code,
#docContent tt.REPLACEABLE {
font-size: 0.9rem !important;
color: inherit !important;
- background-color: #f8f9fa !important;
+ background-color: #f8f9fa;
border-radius: .25rem;
margin: .6rem 0;
font-weight: 300;
@@ -799,6 +799,24 @@ code,
text-align: left;
}
+#docContent table.table th.func_table_entry p,
+#docContent table.table td.func_table_entry p {
+ margin-top: 0.1em 0 0.1em 0;
+ padding-left: 4em;
+ text-align: left;
+}
+
+#docContent table.table p.func_signature {
+ text-indent: -3.5em;
+}
+
+#docContent table.table td.func_table_entry pre.programlisting {
+ background-color: inherit;
+ border: 0;
+ margin: 0.1em 0 0.1em 0;
+ padding: 0 0 0 4em;
+}
+
/**
* Titles, Navigation
*/
@@ -1059,7 +1077,7 @@ i.fas.fa-search {
pre {
padding: 0.8rem;
border: 1px solid #ced4da;
- margin: 1rem 0 !important;
+ margin: 1rem 0;
}
pre.code {
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 8:15 PM, Tom Lane wrote:
> "Jonathan S. Katz" writes:
>> On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
>>> I'll compromise on the temporary importants, but first I want to see
>>> what's causing the need for it. Do you have a suggestion on a page to test?
>
> I haven't yet pushed anything dependent on the new markup, but
> attached is a draft revision for the JSON section; if you look at
> the SRFs such as json_array_elements you'll see the issue.
>
>> From real quick I got it to here. With the latest copy of the doc builds
>> it appears to still work as expected, but I need a section with the new
>> "pre" block to test.
>
> Yeah, I see you found the same and settings I did.
>
>> I think the "background-color: inherit !important" is a bit odd, and
>> would like to trace that one down a bit more, but I did not see anything
>> obvious on my glance through it.
>
> I think it's coming from this bit at about main.css:660:
>
> pre,
> code,
> #docContent kbd,
> #docContent tt.LITERAL,
> #docContent tt.REPLACEABLE {
> font-size: 0.9rem !important;
> color: inherit !important;
> background-color: #f8f9fa !important;
> border-radius: .25rem;
> margin: .6rem 0;
> font-weight: 300;
> }
>
> I had to override most of that.
Yeah, I had started toying with that and saw no differences, but I would
need to test against anything in particular. I'm pretty confident we can
remove those importants, based on my desultory testing.
I'll try and get the patch built + docs loaded, and see if we can safely
remove those.
Jonathan
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
> On 4/29/20 7:29 PM, Tom Lane wrote:
>> After further fooling with this issue, I've determined that
>>
>> (1) I need to be able to use environments within the
>> func_table_entry cells and have them render more-or-less normally.
>> There doesn't seem to be any other good way to render multiline
>> example results for set-returning functions ... but marking such
>> environments up to the extent that the website style normally does
>> is very distracting.
>>
>> (2) I found that adding !important to the func_table_entry rules
>> is enough to override less-general !important rules. So it'd be
>> possible to leave all the existing CSS rules alone, if that makes
>> you feel more comfortable.
>>
>> The attached updated patch reflects both of these conclusions.
>> We could take out some of the !important annotations here if
>> you're willing to delete !important annotations in more-global
>> rules for and/or , but maybe that's something to fool
>> with later. I'd like to get this done sooner ...
>
> My preference would be to figure out the CSS rules that are causing you
> to rely on !important at the table level and just fix that up, rather
> than hacking in too many !important.
>
> I'll compromise on the temporary importants, but first I want to see
> what's causing the need for it. Do you have a suggestion on a page to test?
From real quick I got it to here. With the latest copy of the doc builds
it appears to still work as expected, but I need a section with the new
"pre" block to test.
I think the "background-color: inherit !important" is a bit odd, and
would like to trace that one down a bit more, but I did not see anything
obvious on my glance through it.
How does it look on your end?
Jonathan
diff --git a/media/css/main.css b/media/css/main.css
index 08ca255..db2670a 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -625,7 +625,7 @@ ul.actions {
}
#docContent p {
- margin-bottom: 1rem !important;
+ margin-bottom: 1rem;
}
#docContent hr {
@@ -648,7 +648,7 @@ ul.actions {
}
#docContent pre {
- padding: 0.8rem !important;
+ padding: 0.8rem;
}
pre,
@@ -799,6 +799,27 @@ code,
text-align: left;
}
+#docContent table.table th.func_table_entry p,
+#docContent table.table td.func_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+ padding-left: 4em;
+ text-align: left;
+}
+
+#docContent table.table p.func_signature {
+ text-indent: -3.5em;
+}
+
+#docContent table.table td.func_table_entry pre.programlisting {
+ background-color: inherit !important;
+ border: 0;
+ margin-bottom: 0.1em;
+ margin-top: 0.1em;
+ padding: 0;
+ padding-left: 4em;
+}
+
/**
* Titles, Navigation
*/
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On 4/29/20 7:29 PM, Tom Lane wrote: > After further fooling with this issue, I've determined that > > (1) I need to be able to use environments within the > func_table_entry cells and have them render more-or-less normally. > There doesn't seem to be any other good way to render multiline > example results for set-returning functions ... but marking such > environments up to the extent that the website style normally does > is very distracting. > > (2) I found that adding !important to the func_table_entry rules > is enough to override less-general !important rules. So it'd be > possible to leave all the existing CSS rules alone, if that makes > you feel more comfortable. > > The attached updated patch reflects both of these conclusions. > We could take out some of the !important annotations here if > you're willing to delete !important annotations in more-global > rules for and/or , but maybe that's something to fool > with later. I'd like to get this done sooner ... My preference would be to figure out the CSS rules that are causing you to rely on !important at the table level and just fix that up, rather than hacking in too many !important. I'll compromise on the temporary importants, but first I want to see what's causing the need for it. Do you have a suggestion on a page to test? Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
After further fooling with this issue, I've determined that
(1) I need to be able to use environments within the
func_table_entry cells and have them render more-or-less normally.
There doesn't seem to be any other good way to render multiline
example results for set-returning functions ... but marking such
environments up to the extent that the website style normally does
is very distracting.
(2) I found that adding !important to the func_table_entry rules
is enough to override less-general !important rules. So it'd be
possible to leave all the existing CSS rules alone, if that makes
you feel more comfortable.
The attached updated patch reflects both of these conclusions.
We could take out some of the !important annotations here if
you're willing to delete !important annotations in more-global
rules for and/or , but maybe that's something to fool
with later. I'd like to get this done sooner ...
regards, tom lane
--- main.css.orig 2020-04-29 17:19:24.089511785 -0400
+++ main.css 2020-04-29 19:18:28.082138095 -0400
@@ -799,6 +799,27 @@
text-align: left;
}
+#docContent table.table th.func_table_entry p,
+#docContent table.table td.func_table_entry p {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em !important;
+ padding-left: 4em;
+ text-align: left;
+}
+
+#docContent table.table p.func_signature {
+ text-indent: -3.5em;
+}
+
+#docContent table.table td.func_table_entry pre.programlisting {
+ margin-top: 0.1em !important;
+ margin-bottom: 0.1em !important;
+ padding: 0 !important;
+ padding-left: 4em !important;
+ background-color: inherit !important;
+ border: 0;
+}
+
/**
* Titles, Navigation
*/
Re: Poll: are people okay with function/operator table redesign?
I wrote: > One thing I couldn't help noticing while fooling with this is what > seems to be a bug in the PDF toolchain: any place you try to put > an , you get extra whitespace. Not a lot, but once you > see it, you can't un-see it. It's particularly obvious if one of > two adjacent lines has the extra indentation and the other doesn't. > ... > The only "fix" I've found is to place the at the end > of the signature instead of the beginning. I spent some more time experimenting with this today, and determined that there's no way to fix it by messing with FO layout attributes. The basic problem seems to be that if you write ceiling ceiling ( numeric ) then what you get in the .fo file is ceiling ( numeric ) where the apparently is used as a cross-reference anchor. The trouble with this is that the rules for collapsing adjacent whitespace don't work across the , so no matter what you do you will end up with two spaces not one before the visible text "ceiling". The only way to hide the effects of that with layout attributes is to set whitespace to be ignored altogether within the block, which is quite undesirable. The fix I'm currently considering is to eliminate the extra whitespace run(s) by formatting s within tables this way: char_length character string length length of a character string character string, length char_length ( text ) integer Perhaps it's only worth being anal about this in table cells with multiple function signatures and/or multiple s; in other places the whitespace variation just isn't that noticeable. On the other hand, there's something to be said for having uniform layout of the XML source, which'd suggest having a uniform rule "no whitespace before an within a table cell". Or we could put the s at the end. Or just ignore it, reasoning that the PDF output is never going to look all that great anyway. Thoughts? regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > On 4/27/20 8:49 AM, Tom Lane wrote: >> Other than that point, the main.css patch as I presented it just adds >> some rules that aren't used yet, so it could be pushed as soon as you're >> satisfied about the !important change. It'd probably make sense to >> push it in advance of making the markup changes, so we don't have an >> interval of near-unreadable devel docs. > *nods* I'll ensure to test again and hopefully commit later today. After looking at the JSON function tables, I've concluded that the ability to have more than one function signature per table cell is really rather essential not optional. So I'm going to go ahead and convert all the existing markup to the -based style I proposed on Sunday. Please push the main.css change when you can. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/27/20 8:49 AM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> Great. I do want to do a bit more desultory testing in the older >> versions of the docs, but it can be committed whenever the -docs side is >> ready. > > Other than that point, the main.css patch as I presented it just adds > some rules that aren't used yet, so it could be pushed as soon as you're > satisfied about the !important change. It'd probably make sense to > push it in advance of making the markup changes, so we don't have an > interval of near-unreadable devel docs. *nods* I'll ensure to test again and hopefully commit later today. I forget what I was looking at, but I did see a similar pattern in some other modern software docs, so it seems like this is trending in the right direction. Looking forward to the rollout! Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > Great. I do want to do a bit more desultory testing in the older > versions of the docs, but it can be committed whenever the -docs side is > ready. Other than that point, the main.css patch as I presented it just adds some rules that aren't used yet, so it could be pushed as soon as you're satisfied about the !important change. It'd probably make sense to push it in advance of making the markup changes, so we don't have an interval of near-unreadable devel docs. Still waiting to hear whether this markup approach satisfies Peter's concerns, though. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/26/20 9:44 PM, Tom Lane wrote:
> "Jonathan S. Katz" writes:
>> Can you try
>
>> #docContent p {
>> - margin-bottom: 1rem !important;
>> + margin-bottom: 1rem;
>> }
>
>> and see how it looks?
>
> In some desultory looking around, I couldn't find anyplace in the
> existing text that that changes at all. And it does make the
> revised table markup render the way I want ... so +1.
Great. I do want to do a bit more desultory testing in the older
versions of the docs, but it can be committed whenever the -docs side is
ready.
Thanks,
Jonathan
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes:
> Can you try
> #docContent p {
> - margin-bottom: 1rem !important;
> + margin-bottom: 1rem;
> }
> and see how it looks?
In some desultory looking around, I couldn't find anyplace in the
existing text that that changes at all. And it does make the
revised table markup render the way I want ... so +1.
regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/26/20 3:21 PM, Jonathan S. Katz wrote:
> On 4/26/20 1:40 PM, Tom Lane wrote:
>> I wrote:
>>> Alvaro Herrera writes:
>
>> There is a small problem with getting this to work in the webstyle
>> HTML: somebody decided it would be a great idea to have a global
>> override on paragraph margin-bottom settings. For the purposes of
>> this test I just deleted that from main.css, but I suppose we want
>> some more-nuanced solution in reality.
>
> I have to see why that is. I traced it back to the original "bring doc
> styles up to modern website" patch (66798351) and there is missing
> context. Anyway, I'd like to test it before a wholesale removal (there
> is often a strong correlation between "!important" and "hack", so I'll
> want to further dive into it).
>
> I'll have some time to play around with the CSS tonight.
Can you try
#docContent p {
- margin-bottom: 1rem !important;
+ margin-bottom: 1rem;
}
and see how it looks?
Jonathan
signature.asc
Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On 4/26/20 1:40 PM, Tom Lane wrote: > I wrote: >> Alvaro Herrera writes: > There is a small problem with getting this to work in the webstyle > HTML: somebody decided it would be a great idea to have a global > override on paragraph margin-bottom settings. For the purposes of > this test I just deleted that from main.css, but I suppose we want > some more-nuanced solution in reality. I have to see why that is. I traced it back to the original "bring doc styles up to modern website" patch (66798351) and there is missing context. Anyway, I'd like to test it before a wholesale removal (there is often a strong correlation between "!important" and "hack", so I'll want to further dive into it). I'll have some time to play around with the CSS tonight. Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
Alvaro Herrera writes: > If we're doing nicer markup+CSS for this, then it might make sense to > find a better solution for this kind of entry with multiple signatures > (which was already an issue in the previous version): Yeah, agreed. I would like to be able to have multiple signature blocks in one table cell, which the current hack can't handle. There aren't quite enough cases to make this mandatory, but it would be nicer. It seems do-able if we explicitly mark signature blocks with their own role, say text || anynonarray → text anynonarray || text → text description ... Then the CSS can key off of the role to decide what indentation to apply to the para. While I mostly see how that would work, I'm not very sure about whether we can make it work in the PDF chain too. Not sure whether it'd be worth inventing additional roles to apply to description and example paras, or whether that's just inducing carpal tunnel syndrome to no purpose. We'd want to keep the role label on the s anyway I think, and that context should be enough as long as we don't need different formatting for descriptions and examples. But maybe Peter's notion of "semantic markup" requires it anyway. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
If we're doing nicer markup+CSS for this, then it might make sense to find a better solution for this kind of entry with multiple signatures (which was already an issue in the previous version): text || anynonarray or anynonarray || text → text Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array || operators. If you want to concatenate an array's text equivalent, cast it to text explicitly.) 'Value: ' || 42 → Value: 42 I think it would make sense to split the first line to put each of the two signatures on their own line. So it would look like this: text || anynonarray anynonarray || text → text Converts the non-string input to text, then concatenates the two strings. (The non-string input cannot be of an array type, because that would create ambiguity with the array || operators. If you want to concatenate an array's text equivalent, cast it to text explicitly.) 'Value: ' || 42 → Value: 42 Another example: to_ascii ( string text [, encoding name or integer ] ) → text should be (I think): to_ascii ( string text [, encoding name ] ) → text to_ascii ( string text [, integer ] ) → text -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
Bruce Momjian writes: > On Thu, Apr 23, 2020 at 12:04:01PM -0400, Tom Lane wrote: >> As I said, I'm happy to do the legwork of improving the markup if someone >> will point me in the right direction. But I know next to zip about CSS, >> so it would not be productive for me to do the basic design there --- >> it would take too long and there would probably still be lots to criticize >> in whatever I came up with. > I can do the CSS if you tell me what you want. I think the existing visual appearance is more or less agreed to, so what we want is to reproduce that as closely as possible from some saner markup. The first problem is to agree on what "saner markup" is exactly. We could possibly use margin and vertical-space CSS adjustments starting from just using several s within each table cell (one for signature, one for description, one for each example). I'm not sure whether that meets Peter's desire for "semantic" markup though. It's not any worse than the old way with otherwise-unlabeled s, but it's not better either. Do we want, say, to distinguish descriptions from examples in the markup? If so, will paras with a role attribute do, or does it need to be something else? I'm also not sure whether or not Peter is objecting to the way I used . That seems reasonably semantically-based to me, but since he hasn't stated what his criteria are, I don't know if he thinks so. (I'll admit that it's a bit of an abuse to use that for both function return types and example results.) If that's out then we need some other design for getting the right arrows into place. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Thu, Apr 23, 2020 at 12:04:01PM -0400, Tom Lane wrote: > Peter Eisentraut writes: > > I've played with this a bit, and there are certainly a lot of > > interesting things that you can do with CSS nowadays that would preserve > > some semblance of semantic markup on both the DocBook side and the HTML > > side. > > As I said, I'm happy to do the legwork of improving the markup if someone > will point me in the right direction. But I know next to zip about CSS, > so it would not be productive for me to do the basic design there --- > it would take too long and there would probably still be lots to criticize > in whatever I came up with. I can do the CSS if you tell me what you want. -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
Re: Poll: are people okay with function/operator table redesign?
Peter Eisentraut writes: > I've played with this a bit, and there are certainly a lot of > interesting things that you can do with CSS nowadays that would preserve > some semblance of semantic markup on both the DocBook side and the HTML > side. As I said, I'm happy to do the legwork of improving the markup if someone will point me in the right direction. But I know next to zip about CSS, so it would not be productive for me to do the basic design there --- it would take too long and there would probably still be lots to criticize in whatever I came up with. (I note ruefully that my original design in e894c6183 *was* pretty decent semantic markup, especially if you're willing to accept spanspec identifiers as semantic annotation. But people didn't like the visual result, so now we have better visuals and uglier markup.) > But my conclusion is that this new direction is bad and the old way was > much better. My vote is to keep what we had in PG12. I'm not willing to accept that conclusion. Why are we even bothering to support PDF output, if lots of critical information is going to be illegible? (And even if you figure PDFs should go the way of the dodo, almost any narrow-window presentation has got problems with these tables.) Also, as I've been going through this, I've realized that there are many places in chapter 9 where the documentation is well south of adequate, if not flat-out wrong. Some of it is just that nobody's gone through this material in decades, and some of it is that the existing table layout is so unfriendly to writing more than a couple words of explanation per item. But I'm not willing to abandon the work I've done so far and just hope that in another twenty years somebody will be brave or foolish enough to try again. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 2020-04-19 15:23, Tom Lane wrote: If somebody's got an idea how to obtain this painfully-agreed-to visual appearance from more robust markup, I'm all ears. This stuff is a bit outside my skill set, so I don't claim to have found the best possible implementation. I've played with this a bit, and there are certainly a lot of interesting things that you can do with CSS nowadays that would preserve some semblance of semantic markup on both the DocBook side and the HTML side. We haven't even considered what this new markup would do to non-visual consumers. But my conclusion is that this new direction is bad and the old way was much better. My vote is to keep what we had in PG12. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
On 2020-Apr-20, Tom Lane wrote: > Alvaro Herrera writes: > > There's one with a separate column for the operator, without types, at > > the left (the "with names" example at > > https://postgr.es/m/14380.1587242...@sss.pgh.pa.us ). That seemed > > pretty promising -- not sure why it was discarded. > > Well, I wouldn't say it was discarded --- but there sure wasn't > a groundswell of support. Ah. > Looking at it again, I'd be inclined not to bother with the > morerows trick but just to have an operator name entry in each row. > This table is a bit of an outlier anyway, I'm finding --- very few > of the operator tables have multiple entries per operator name. No disagreement here. 'morerows' attribs are always a messy business. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
Alvaro Herrera writes: > There's one with a separate column for the operator, without types, at > the left (the "with names" example at > https://postgr.es/m/14380.1587242...@sss.pgh.pa.us ). That seemed > pretty promising -- not sure why it was discarded. Well, I wouldn't say it was discarded --- but there sure wasn't a groundswell of support. Looking at it again, I'd be inclined not to bother with the morerows trick but just to have an operator name entry in each row. This table is a bit of an outlier anyway, I'm finding --- very few of the operator tables have multiple entries per operator name. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 2020-Apr-20, Tom Lane wrote: > Victor Yegorov writes: > > While table 9.5 with functions looks quite nice, I quite dislike 9.4 with > > operators. > > Previously, I could lookup operator in the leftmost column and read on. > > Right now I have to look through the whole table (well, not really, but > > still) to find the operator. > > Aside from the alternatives already discussed, There's one with a separate column for the operator, without types, at the left (the "with names" example at https://postgr.es/m/14380.1587242...@sss.pgh.pa.us ). That seemed pretty promising -- not sure why it was discarded. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
Victor Yegorov writes: > While table 9.5 with functions looks quite nice, I quite dislike 9.4 with > operators. BTW, I think a big part of the problem with table 9.4 as it's being rendered in the web style right now is that the type placeholders (numeric_type etc) are being rendered in a ridiculously overemphasized fashion, causing them to overwhelm all else. Do we really want to be rendered that way? I'd think plain italic, comparable to the rendering of , would be more appropriate. I could make this page use for that purpose of course, but it seems like semantically the wrong thing. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
Victor Yegorov writes: > While table 9.5 with functions looks quite nice, I quite dislike 9.4 with > operators. > Previously, I could lookup operator in the leftmost column and read on. > Right now I have to look through the whole table (well, not really, but > still) to find the operator. Aside from the alternatives already discussed, the only other idea that's come to my mind is to write operator entries in a style like || as in: text || text → text Concatenates the two strings. 'Post' || 'greSQL' → PostgreSQL Not sure that that's any better, but it is another alternative. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
вс, 19 апр. 2020 г. в 20:00, Tom Lane : > In the meantime I plan to push forward with the markup approach we've > got. The editorial content should still work if we find a better > markup answer, and I'm willing to do the work of replacing the markup > as long as somebody else figures out what it should be. > I am following this thread as a frequent documentation user. While table 9.5 with functions looks quite nice, I quite dislike 9.4 with operators. Previously, I could lookup operator in the leftmost column and read on. Right now I have to look through the whole table (well, not really, but still) to find the operator. -- Victor Yegorov
Re: Poll: are people okay with function/operator table redesign?
Isaac Morland writes: > If we were only concerned with HTML output then based on the desired > semantics and appearance I would recommend without hesitation. Because > of the need to produce PDF as well and my lack of knowledge of the Postgres > documentation build process, I can't be so certain but I still suspect > to be the best approach. Yeah ... so a part of this problem is to persuade DocBook to generate that. As I mentioned upthread, I did experiment with putting a single-item in each table cell. That works out to an annoying amount of markup overhead, since variablelist is a rather overengineered construct, but I imagine we could live with it. The real problem was the amount of whitespace it wanted to add. We could probably hack our way out of that with CSS for HTML output, but it was quite unclear whether the PDF toolchain could be made to render it reasonably. A desirable solution, perhaps, would be a corresponding to the entire table with rendering customization that produces table-like dividing lines around s. I'm not volunteering to figure out how to do that though, especially not for PDF. In the meantime I plan to push forward with the markup approach we've got. The editorial content should still work if we find a better markup answer, and I'm willing to do the work of replacing the markup as long as somebody else figures out what it should be. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Sun, 19 Apr 2020 at 09:23, Tom Lane wrote: > In any case, I reject the idea that we should just drop the table > markup altogether and use inline variablelists. In most of these > sections there is a very clear separation between the table contents > (with per-function or per-operator details) and the surrounding > commentary, which deals with more general concerns. That's a useful > separation for both readers and authors, so we need to preserve it > in some form, but the standard rendering of variablelists won't. > (Our existing major use of variablelists, in the GUC chapter, works > around this basically by not having any "surrounding commentary" > ... but that solution doesn't work here.) > > There is also value in being able to say things like "see Table m.n > for the available operators for type foo". > The HTML definition list under discussion looks like this: term 1 description 1 term 2 description 2a description 2b So the enclosing element has the same role in the overall document as the , and could be styled to set it apart from the main text and make it clear that it is a single unit (and at least in principle could be included in the "table" numbering). In the function/operator listing use case, there would be one for the description and a for each example. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl If we were only concerned with HTML output then based on the desired semantics and appearance I would recommend without hesitation. Because of the need to produce PDF as well and my lack of knowledge of the Postgres documentation build process, I can't be so certain but I still suspect to be the best approach.
Re: Poll: are people okay with function/operator table redesign?
Peter Eisentraut writes: > This scares me in terms of maintainability of both the toolchain and the > markup. Table formatting is already incredibly fragile, and here we > just keep poking it until it looks a certain way instead of thinking > about semantic markup. That's a fair criticism, but ... > A good old definition list of the kind > synopsis > explanation > example or two > would be much easier to maintain on all fronts. And we could for > example link directly to a function, which is currently not really possible. > If we want to draw a box around this and change the spacing, we can do > that with CSS. ... "we can fix it with CSS" is just as much reliance on toolchain. In any case, I reject the idea that we should just drop the table markup altogether and use inline variablelists. In most of these sections there is a very clear separation between the table contents (with per-function or per-operator details) and the surrounding commentary, which deals with more general concerns. That's a useful separation for both readers and authors, so we need to preserve it in some form, but the standard rendering of variablelists won't. (Our existing major use of variablelists, in the GUC chapter, works around this basically by not having any "surrounding commentary" ... but that solution doesn't work here.) There is also value in being able to say things like "see Table m.n for the available operators for type foo". If somebody's got an idea how to obtain this painfully-agreed-to visual appearance from more robust markup, I'm all ears. This stuff is a bit outside my skill set, so I don't claim to have found the best possible implementation. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 2020-04-17 02:25, Tom Lane wrote: I eventually figured out that the approved way to do per-table-entry customization is to attach "role" properties to the DocBook elements, and then key off the role names in applying formatting changes in the customization layer. So attached is a v3 that handles the desired formatting changes by applying a hanging indent to table contents if the entry is marked with role="functableentry". It may well be possible to do this in a cleaner fashion, but this seems good enough for discussion. This scares me in terms of maintainability of both the toolchain and the markup. Table formatting is already incredibly fragile, and here we just keep poking it until it looks a certain way instead of thinking about semantic markup. A good old definition list of the kind synopsis explanation example or two would be much easier to maintain on all fronts. And we could for example link directly to a function, which is currently not really possible. If we want to draw a box around this and change the spacing, we can do that with CSS. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
On 2020-04-16 08:26, Pierre Giraud wrote: The screenshot attached uses a tag for the descrition/example block. I like this better, but then you don't really need the table because you can just make the whole thing a definition list. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
On 2020-04-13 22:33, Tom Lane wrote: Maybe we're just trying to shoehorn too much information into a single table. Yeah, back at the beginning of this exercise, Alvaro wondered aloud if we should go to something other than tables altogether. I dunno what that'd look like though. Yeah, after reading all this, my conclusion is also, probably tables are not the right solution. A variablelist/definition list would be the next thing to try in my mind. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
so 18. 4. 2020 v 22:36 odesílatel Tom Lane napsal: > Robert Haas writes: > > On Fri, Apr 17, 2020 at 6:30 PM David G. Johnston > > wrote: > >> I feel like writing them as: > >> + (date, integer) -> date > >> makes more sense as they are mainly sorted on the operator symbol as > opposed to the left operand. > > > I thought about that, too, but I think the way Tom did it is better. > > It's much more natural to see it using the syntax with which it will > > actually be invoked. > > Just for the record, I experimented with putting back an "operator name" > column, as attached. I think it could be argued either way whether this > is an improvement or not. > > Some notes: > > * The column seems annoyingly wide, but the only way to make it narrower > is to narrow or eliminate the column title, which could be confusing. > Also, if there's not a fair amount of whitespace, it looks as if the > initial name is part of the signature, which is *really* confusing, > cf second screenshot. (I'm not sure why the vertical rule is rendered > so much more weakly in this case, but it is.) > > * I also tried it with valign="middle" to center the operator name among > its entries. This was *not* an improvement, it largely breaks the > ability to see which entries belong to the name. > first variant looks better, because column with operator is wider. Maybe it can look better if a content will be places to mid point. In left upper corner it is less readable. Regards Pavel > regards, tom lane > >
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 6:30 PM David G. Johnston wrote: > I feel like writing them as: > > + (date, integer) -> date > > makes more sense as they are mainly sorted on the operator symbol as opposed > to the left operand. I thought about that, too, but I think the way Tom did it is better. It's much more natural to see it using the syntax with which it will actually be invoked. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
"David G. Johnston" writes: > On Fri, Apr 17, 2020 at 4:17 PM Tom Lane wrote: >> We do have some postfix operators still ... although it looks like >> there's only one in core. In any case, the signature line is *the* >> thing that is supposed to specify what the syntax is, so I'm not >> too pleased with using an ambiguous notation for it. > Neither: > - (NONE, integer) > nor > ! (integer, NONE) > seem bad, and do make very obvious how they are different. > The left margin scanning ability for the symbol (hey, I have an expression > here that uses @>, what does that do?) seems worth the bit of novelty > required. Meh. If we're worried about that, personally I'd much rather put back the separate left-hand column with just the operator name. We could also experiment with bold-facing the operator names, as somebody suggested upthread. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 4:17 PM Tom Lane wrote: > "David G. Johnston" writes: > > On Fri, Apr 17, 2020 at 4:04 PM Tom Lane wrote: > >> Especially not for unary operators, where > >> ALTER OPERATOR would have us write "- (NONE, integer)". > > > I'd drop the parens for unary and just write "- integer" > > We do have some postfix operators still ... although it looks like > there's only one in core. In any case, the signature line is *the* > thing that is supposed to specify what the syntax is, so I'm not > too pleased with using an ambiguous notation for it. > Neither: - (NONE, integer) nor ! (integer, NONE) seem bad, and do make very obvious how they are different. The left margin scanning ability for the symbol (hey, I have an expression here that uses @>, what does that do?) seems worth the bit of novelty required. David J.
Re: Poll: are people okay with function/operator table redesign?
"David G. Johnston" writes: > On Fri, Apr 17, 2020 at 4:04 PM Tom Lane wrote: >> Especially not for unary operators, where >> ALTER OPERATOR would have us write "- (NONE, integer)". > I'd drop the parens for unary and just write "- integer" We do have some postfix operators still ... although it looks like there's only one in core. In any case, the signature line is *the* thing that is supposed to specify what the syntax is, so I'm not too pleased with using an ambiguous notation for it. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 4:04 PM Tom Lane wrote: > Especially not for unary operators, where > ALTER OPERATOR would have us write "- (NONE, integer)". > I'd drop the parens for unary and just write "- integer" It is a bit geeky but then again SQL writers are not typically computer language novices so operators should be comfortable for them and this isn't that off-the-wall. But I agree with the concern. David J.
Re: Poll: are people okay with function/operator table redesign?
"David G. Johnston" writes: > I feel like writing them as: > + (date, integer) -> date > makes more sense as they are mainly sorted on the operator symbol as > opposed to the left operand. Hmm ... we do use that syntax in some fairly-obscure places like ALTER OPERATOR, but I'm afraid that novice users would just be completely befuddled. Maybe the examples would be enough to clarify, but I'm not convinced. Especially not for unary operators, where ALTER OPERATOR would have us write "- (NONE, integer)". regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 11:38 AM Tom Lane wrote: > Robert Haas writes: > > On Thu, Apr 16, 2020 at 8:25 PM Tom Lane wrote: > >> Attached are screenshots of the same segment of table 9.10 as before > >> and of the initial portion of 9.30, the patch against HEAD to produce > >> these, and a hacky patch on the website's main.css to get it to go > >> along. Without the last you just get all the subsidiary stuff > >> left-justified if you build with STYLE=website, which isn't impossibly > >> unreadable but it's not the desired presentation. > > > These seem very nice, and way more readable than the version with > > which you started the thread. > > I too like the layout result. > Glad you like 'em ;-). Do you have an opinion about what to do > with the operator tables --- ie do we need a column with the operator > name at the left? > > I feel like writing them as: + (date, integer) -> date makes more sense as they are mainly sorted on the operator symbol as opposed to the left operand. I think the description line is beneficial, and easy enough to skim over for the trained eye just looking for a refresher on the example syntax. David J.
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > On Fri, Apr 17, 2020 at 3:58 PM Tom Lane wrote: >> On the other point of dispute about the operator tables: for the >> moment I'm leaning towards keeping the text descriptions. > I mostly suggested nuking them just to try to make the table more > readable. But since you've found another (and better) solution to that > problem, I withdraw that suggestion. Cool, then we're all on the same page. I shall press forward. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 3:58 PM Tom Lane wrote: > On the other point of dispute about the operator tables: for the > moment I'm leaning towards keeping the text descriptions. I mostly suggested nuking them just to try to make the table more readable. But since you've found another (and better) solution to that problem, I withdraw that suggestion. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > On Fri, Apr 17, 2020 at 2:38 PM Tom Lane wrote: >> Glad you like 'em ;-). Do you have an opinion about what to do >> with the operator tables --- ie do we need a column with the operator >> name at the left? > Well, if the first row says date + date -> date, then I don't think we > also need another column to say that we're talking about + > Seems redundant. Well, sure it's redundant, the same way an index is redundant. Question is whether it makes it easier to find what you're after. Comparing this to what is in table 9.30 as of HEAD [1], it does seem like the operator column in the latter is a bit busy/redundant. Perhaps it'd be less so if we used the morerows trick to have only one occurrence of each operator name in the first column. But that would be a little bit of a pain to maintain, so I'm not sure it's worth the trouble. Another advantage of handling functions and operators in exactly the same format is that we won't need to do something weird for tables 9.9 and 9.11, which include both. For the moment I'll press on without including that column; we can add it later without a huge amount of pain if we decide we want it. On the other point of dispute about the operator tables: for the moment I'm leaning towards keeping the text descriptions. Surveying the existing tables, the *only* two that lack text descriptions now are this one and the as-yet-unnumbered table in 9.1 for AND/OR/NOT. (Actually, that one calls itself a truth table not an operator definition table, so maybe we should leave it alone.) While there is a reasonable argument that 9.1 Comparison Operators' descriptions are all obvious, it's hard to make that argument for any other tables. So I think the fact that 9.30 lacked such up to now is an aberration not a good principle to follow. Even in 9.30, the fact that, say, date + integer interprets the integer as so-many-days isn't really so blindingly obvious that it doesn't need documented. In another universe we might've made that count as seconds and had the result type be timestamp, the way it works for date + interval. regards, tom lane [1] https://www.postgresql.org/docs/devel/functions-datetime.html
Re: Poll: are people okay with function/operator table redesign?
On Fri, Apr 17, 2020 at 2:38 PM Tom Lane wrote: > Glad you like 'em ;-). Do you have an opinion about what to do > with the operator tables --- ie do we need a column with the operator > name at the left? Well, if the first row says date + date -> date, then I don't think we also need another column to say that we're talking about + Seems redundant. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > On Thu, Apr 16, 2020 at 8:25 PM Tom Lane wrote: >> Attached are screenshots of the same segment of table 9.10 as before >> and of the initial portion of 9.30, the patch against HEAD to produce >> these, and a hacky patch on the website's main.css to get it to go >> along. Without the last you just get all the subsidiary stuff >> left-justified if you build with STYLE=website, which isn't impossibly >> unreadable but it's not the desired presentation. > These seem very nice, and way more readable than the version with > which you started the thread. Glad you like 'em ;-). Do you have an opinion about what to do with the operator tables --- ie do we need a column with the operator name at the left? regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Thu, Apr 16, 2020 at 8:25 PM Tom Lane wrote: > Attached are screenshots of the same segment of table 9.10 as before > and of the initial portion of 9.30, the patch against HEAD to produce > these, and a hacky patch on the website's main.css to get it to go > along. Without the last you just get all the subsidiary stuff > left-justified if you build with STYLE=website, which isn't impossibly > unreadable but it's not the desired presentation. These seem very nice, and way more readable than the version with which you started the thread. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
v1 is good. I like your v2 even better. If it becomes possible to remove or soften the "inter-row" horizontal line with CSS tricks afterwards, that would be swell, but even without that, I cast my vote to using this table format. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
On 4/14/20 4:52 PM, Tom Lane wrote: Andreas Karlsson writes: That said, I agree with that quite many of our tables right now are ugly, but I prefer ugly to hard to read. For me the mix of having every third row split into two fields makes the tables very hard to read. I have a hard time seeing which rows belong to which function. Did you look at the variants without that discussed downthread? Yeah, I did some of them are quite readable, for example your latest two screenshots of table 9.10. Andreas
Re: Poll: are people okay with function/operator table redesign?
Pierre Giraud writes: > Le 16/04/2020 à 16:43, Tom Lane a écrit : >> Pierre Giraud writes: >>> The screenshot attached uses a tag for the descrition/example block. >> That looks about right, perhaps, but could you be a little clearer about >> how you accomplished that? > Attached you will find the HTML structure with associated styles. > Sorry I haven't tried to do this from the DocBook sources. > I hope this helps though. After a bit of poking at it, I couldn't find another way to do that than using a structure. Which is an annoying amount of markup to be adding to each table cell, but I guess we could live with it. A bigger problem is that docbook applies styles to the structure that, at least by default, add a LOT of vertical space. Doesn't seem real workable unless we can undo that. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
Le 16/04/2020 à 16:43, Tom Lane a écrit :
> Pierre Giraud writes:
>> Le 16/04/2020 à 00:18, Tom Lane a écrit :
>>> The main disadvantage I can see to the v2 design is that we're back
>>> to having two per function, which is inevitably going to result
>>> in PDF builds putting page breaks between those rows. But you can't
>>> have everything ... and maybe we could find a way to discourage such
>>> breaks if we tried.
>
> Further experimentation shows that the PDF toolchain is perfectly willing
> to put a page break *within* a multi-line ; if there is any
> preference to break between rows instead, it's pretty weak. So that
> argument is a red herring and we shouldn't waste time chasing it.
> However, there'd still be some advantage in not being dependent on CSS
> hackery to make it look nice in HTML.
>
> What we're down to wanting, at this point, is basically a para with
> hanging indent.
>
>> What about putting everything into one and use a block with
>> some left padding/margin for description + example.
>> This would solve the PDF page break issue as well as the column
>> separation border one.
>> The screenshot attached uses a tag for the descrition/example block.
>
> That looks about right, perhaps, but could you be a little clearer about
> how you accomplished that?
Attached you will find the HTML structure with associated styles.
Sorry I haven't tried to do this from the DocBook sources.
I hope this helps though.
Regards
# HTML
Function
Description
Example
age(timestamp, timestamp) → interval
Subtract arguments, producing a “symbolic” result that uses years and months, rather
than just days
age(timestamp '2001-04-10', timestamp
'1957-06-13') → 43 years 9 mons 27 days
# CSS
#docContent table.table code.literal {
font-style: italic;
}
code.returnvalue {
font-weight: bold;
}
code.function {
font-weight: bold;
}
.replaceable > code {
font-weight: normal !important;
}
#docContent table.table dl {
margin-left: 30px;
margin-top: 5px;
}
#docContent table.table dl > dd {
margin-bottom: 0;
}
Re: Poll: are people okay with function/operator table redesign?
Pierre Giraud writes: > Le 16/04/2020 à 00:18, Tom Lane a écrit : >> The main disadvantage I can see to the v2 design is that we're back >> to having two per function, which is inevitably going to result >> in PDF builds putting page breaks between those rows. But you can't >> have everything ... and maybe we could find a way to discourage such >> breaks if we tried. Further experimentation shows that the PDF toolchain is perfectly willing to put a page break *within* a multi-line ; if there is any preference to break between rows instead, it's pretty weak. So that argument is a red herring and we shouldn't waste time chasing it. However, there'd still be some advantage in not being dependent on CSS hackery to make it look nice in HTML. What we're down to wanting, at this point, is basically a para with hanging indent. > What about putting everything into one and use a block with > some left padding/margin for description + example. > This would solve the PDF page break issue as well as the column > separation border one. > The screenshot attached uses a tag for the descrition/example block. That looks about right, perhaps, but could you be a little clearer about how you accomplished that? regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
Le 16/04/2020 à 00:18, Tom Lane a écrit : > As I threatened to do earlier, I made a pass at converting table 9.10 > to a couple of the styles under discussion. (This is just a > draft-quality patch, so it might have some minor bugs --- the point > is just to see what these styles look like.) > > I've concluded after looking around that the ideas involving not having > a at all, but just a or the like, are not very > well-advised. That would eliminate, or at least greatly degrade, the > visual distinction between the per-function material and the surrounding > commentary. Which does not seem like a winner to me; for example it > would make it quite hard to skip over the detailed material when you're > just trying to skim the docs. > > We did have a number of people suggesting that just reordering things as > "description, signature, examples" might be a good idea, so I gave that > a try; attached is a rendition of a portion of 9.10 in that style (the > "v1" image). It's not bad, but there's still going to be a lot of > wasted whitespace in tables that include even one long function name. > (9.10's longest is "regexp_split_to_array", so it's showing this problem > significantly.) > > I also experimented with Jonathan's idea of dropping the separate > function name and allowing the function signature to span left into > that column -- see "v2" images. This actually works really well, > and would work even better (IMO) if we could get rid of the inter-row > and inter-column rules within a function entry. I failed to > accomplish that with rowsep/colsep annotations, but from remarks > upthread I suppose there might be a CSS way to accomplish it. (But > the rowsep/colsep annotations *do* work in PDF output, so I kept them; > that means we only need a CSS fix and not some kind of flow-object > magic for PDF.) > > To allow direct comparison of these 9.10 images against the situation > in HEAD, I've also attached an extract of 9.10 as rendered by my > browser with "STYLE=website". As you can see this is *not* quite > identical to how it renders on postgresql.org, so there is still some > unexplained differential in font or margins or something. But if you > look at those three PNGs you can see that either v1 or v2 has a pretty > substantial advantage over HEAD in terms of the amount of space > needed. v2 would be even further ahead if we could eliminate some of > the vertical space around the intra-function row split, which again > might be doable with CSS magic. > > The main disadvantage I can see to the v2 design is that we're back > to having two per function, which is inevitably going to result > in PDF builds putting page breaks between those rows. But you can't > have everything ... and maybe we could find a way to discourage such > breaks if we tried. What about putting everything into one and use a block with some left padding/margin for description + example. This would solve the PDF page break issue as well as the column separation border one. The screenshot attached uses a tag for the descrition/example block. > > Another issue is that v2 won't adapt real well to operator tables; > the operator name won't be at the left. I don't have a lot of faith > in the proposal to fix that with font tricks. Maybe we could stick > to something close to the layout that table 9.30 has in HEAD (ie > repeating the operator name in column 1), since we won't have long > operator names messing up the format. Again, CSS'ing our way > out of the internal lines and extra vertical space within a single > logical table cell would make that layout look nicer. > > On balance I quite like the v2 layout and would prefer to move forward > with that, assuming we can solve the remaining issues via CSS or style > sheets. > > In addition to screenshots, I've attached patches against HEAD that > convert both tables 9.10 and 9.33 into v1 and v2 styles. > > regards, tom lane >
Re: Poll: are people okay with function/operator table redesign?
At Wed, 15 Apr 2020 12:04:34 -0400, Robert Haas wrote in > On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule > wrote: > > st 15. 4. 2020 v 17:43 odesílatel Isaac Morland > > napsal: > >> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud > >> wrote: > >>> The best way to achieve this is to use some styling (font style and > >>> color). > >>> > >>> Attached you will find two different options I worked on very quickly. > >> > >> I really like the first. Just a couple of suggestions I would make: > > > > yes, it is very well readable > > +1. +1. regards. -- Kyotaro Horiguchi NTT Open Source Software Center
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 10:13 AM Tom Lane wrote: > As discussed in the thread at [1], I've been working on redesigning > the tables we use to present SQL functions and operators. The > first installment of that is now up; see tables 9.30 and 9.31 at > > https://www.postgresql.org/docs/devel/functions-datetime.html > > and table 9.33 at > > https://www.postgresql.org/docs/devel/functions-enum.html > > The centering of the headers doesn't do it for me. Too much gap and the data itself is not centered so there is a large disconnect between the headers and the values. The run-on aspect of the left-aligned setup is of some concern but maybe just adding some left padding to the second column - and right padding to the first - can provide the desired negative space without adding so much as to break usability. David J.
Re: Poll: are people okay with function/operator table redesign?
Steven Pousty writes: > Is there a way to get a heavier line between each function? It would be > helpful to have a clearer demarcation of what belongs to each function. The first alternative I posted at https://www.postgresql.org/message-id/31833.1586817876%40sss.pgh.pa.us seems like it would accomplish that pretty well, by having lines *only* between functions. The last couple of things that have been posted seem way more cluttered than that one. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
Is there a way to get a heavier line between each function? It would be helpful to have a clearer demarcation of what belongs to each function. On Wed, Apr 15, 2020 at 9:04 AM Robert Haas wrote: > On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule > wrote: > > st 15. 4. 2020 v 17:43 odesílatel Isaac Morland > napsal: > >> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud > wrote: > >>> The best way to achieve this is to use some styling (font style and > color). > >>> > >>> Attached you will find two different options I worked on very quickly. > >> > >> I really like the first. Just a couple of suggestions I would make: > > > > yes, it is very well readable > > +1. > > -- > Robert Haas > EnterpriseDB: http://www.enterprisedb.com > The Enterprise PostgreSQL Company > > >
Re: Poll: are people okay with function/operator table redesign?
On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule wrote: > st 15. 4. 2020 v 17:43 odesílatel Isaac Morland > napsal: >> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud wrote: >>> The best way to achieve this is to use some styling (font style and color). >>> >>> Attached you will find two different options I worked on very quickly. >> >> I really like the first. Just a couple of suggestions I would make: > > yes, it is very well readable +1. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
st 15. 4. 2020 v 17:43 odesílatel Isaac Morland napsal: > On Wed, 15 Apr 2020 at 11:26, Pierre Giraud > wrote: > > >> The best way to achieve this is to use some styling (font style and >> color). >> >> Attached you will find two different options I worked on very quickly. >> > > I really like the first. Just a couple of suggestions I would make: > yes, it is very well readable Pavel > - leave a space between the function name and (. Regardless of opinions on > what source code should look like, your documentation has space between > each parameter and the next one, and between the ) and the -> and the ->. > and the return type so it seems crowded not to have space between the > function name and the (. > - At this point it's not really a table any more; I would get rid of the > lines, maybe tweak the spacing, and possibly use(definition > list) rather than table-related HTML elements. See > https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl. > > I think the bolding really makes stand out the crucial parts one needs to > find. > >
Re: Poll: are people okay with function/operator table redesign?
On Wed, 15 Apr 2020 at 11:26, Pierre Giraud wrote: > The best way to achieve this is to use some styling (font style and color). > > Attached you will find two different options I worked on very quickly. > I really like the first. Just a couple of suggestions I would make: - leave a space between the function name and (. Regardless of opinions on what source code should look like, your documentation has space between each parameter and the next one, and between the ) and the -> and the ->. and the return type so it seems crowded not to have space between the function name and the (. - At this point it's not really a table any more; I would get rid of the lines, maybe tweak the spacing, and possibly use(definition list) rather than table-related HTML elements. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl. I think the bolding really makes stand out the crucial parts one needs to find.
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 10:13 AM Tom Lane wrote: > As discussed in the thread at [1], I've been working on redesigning > the tables we use to present SQL functions and operators. The > first installment of that is now up; see tables 9.30 and 9.31 at > > https://www.postgresql.org/docs/devel/functions-datetime.html > > and table 9.33 at > > https://www.postgresql.org/docs/devel/functions-enum.html > > As I write this the enum headers are centered horizontally while the datetime ones are left aligned. The centering doesn't do it for me. To much gap and the data itself is not centered so there is a large disconnected between the header and the value. The run-on aspect of the left-aligned setup is of some concern but maybe just adding some left padding to the second column - and right padding to the first - can provide the desired negative space without adding so much as to break usability. (gonna use embedded images here...) [image: image.png] [image: image.png] David J.
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > At any rate, if the price of more clarity and more examples is that > the tables become three times as long and harder to read, I am > somewhat inclined to think that the cure is worse than the disease. I > can readily see how something like table 9.10 (Other String Functions) > might be a mess on a narrow screen or in PDF format, but it's an > extremely useful table on a normal-size screen in HTML format, and > part of what makes it useful is that it's compact. Almost anything we > do is going to remove some of that compactness to save horizontal > space. Maybe that's OK, but it's sure not great. It's nice to be able > to see more on one screen. I dunno, it doesn't look to me like 9.10 is some paragon of efficient use of screen space, even with a wide window. (And my goodness it looks bad if I try a window about half my usual web-browsing width.) Maybe I should go convert that one to see what it looks like in one of the other layouts being discussed. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Tue, Apr 14, 2020 at 11:26 AM Tom Lane wrote: > Well, no it isn't. The main nit I would pick in that claim is that > it's far from obvious that the three examples of float8 * interval > are all talking about the same operator; in fact, a reader would > be very likely to draw the false conclusion that there is an > integer * interval operator. I agree that's not great. I think that could possibly be fixed by showing all three examples in the same cell, and maybe by revising the choice of examples. > I'd like to have more consistency, not less. I do not think it helps > readers to have each page in Chapter 9 have its own idiosyncratic way of > presenting operators/functions. The operator tables are actually almost > that bad, right now --- compare section 9.1 (hasn't even bothered with > a formal ) with tables 9.1, 9.4, 9.9, 9.12, 9.14, 9.30, 9.34, > 9.37, 9.41, 9.44. The variation in level of detail and precision is > striking, and not in a good way. Well, I don't know. Having two or even three formats is not the same as having infinitely many formats, and may be justified if the needs are sufficiently different from each other. At any rate, if the price of more clarity and more examples is that the tables become three times as long and harder to read, I am somewhat inclined to think that the cure is worse than the disease. I can readily see how something like table 9.10 (Other String Functions) might be a mess on a narrow screen or in PDF format, but it's an extremely useful table on a normal-size screen in HTML format, and part of what makes it useful is that it's compact. Almost anything we do is going to remove some of that compactness to save horizontal space. Maybe that's OK, but it's sure not great. It's nice to be able to see more on one screen. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > The v12 version of the "Table 9.30. Date/Time Operators" is not that > wide, and is really quite clear. Well, no it isn't. The main nit I would pick in that claim is that it's far from obvious that the three examples of float8 * interval are all talking about the same operator; in fact, a reader would be very likely to draw the false conclusion that there is an integer * interval operator. This is an aspect of the general problem that we don't have a nice way to deal with multiple examples in the tables. Somebody kluged their way around it here in this particular way, but I'd really like a clearer way, because we need more examples. I would also point out that this table is quite out of step with the rest of the docs in its practice of showing the results as though they were typed literals. Most places that show results just show what you'd expect to see in a psql output column, making it necessary to show the result data type somewhere else. > The new version takes 3 lines per > operator where the old one took one. That's because you've added (1) a > description of the fact that + does addition and - does subtraction, > repeated for each operator, and (2) explicit information about the > input and result types. I don't think either add much, in this case. As I already said, I agree about the text descriptions being of marginal value in this case. I disagree about the explicit datatypes, because the float8 * interval cases already show a hole in that argument, and surely we don't want to require every example to use explicitly-typed literals and nothing but. Besides, what will you do for operators that take anyarray or the like? > For more complicated cases, one thing we could do is ditch the table > and use a with a separate for each > operator. So you could have something like: > ... > But I would only advocate for this style in cases where there is > substantial explaining to be done. I'd like to have more consistency, not less. I do not think it helps readers to have each page in Chapter 9 have its own idiosyncratic way of presenting operators/functions. The operator tables are actually almost that bad, right now --- compare section 9.1 (hasn't even bothered with a formal ) with tables 9.1, 9.4, 9.9, 9.12, 9.14, 9.30, 9.34, 9.37, 9.41, 9.44. The variation in level of detail and precision is striking, and not in a good way. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 4:29 PM Tom Lane wrote: > I wouldn't be averse to dropping the text descriptions for operators > in places where they seem obvious ... but who decides what is obvious? Well, we do. We're smart, right? I don't think it's a good idea to add clutter to table A just because table B needs more details. What matters is whether table A needs more details. The v12 version of the "Table 9.30. Date/Time Operators" is not that wide, and is really quite clear. The new version takes 3 lines per operator where the old one took one. That's because you've added (1) a description of the fact that + does addition and - does subtraction, repeated for each operator, and (2) explicit information about the input and result types. I don't think either add much, in this case. The former doesn't really need to be explained, and the latter was clear enough from the way the examples were presented - everything had explicit types. For more complicated cases, one thing we could do is ditch the table and use a with a separate for each operator. So you could have something like: date + date timestamp Lengthy elocution, including an example. But I would only advocate for this style in cases where there is substantial explaining to be done. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
Andreas Karlsson writes: > That said, I agree with that quite many of our tables right now are > ugly, but I prefer ugly to hard to read. For me the mix of having every > third row split into two fields makes the tables very hard to read. I > have a hard time seeing which rows belong to which function. Did you look at the variants without that discussed downthread? regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/14/20 4:29 PM, Tom Lane wrote: Andreas Karlsson writes: For the old tables I can at least just make the browser window ridiculously wide ro read them. A large part of the point here is to make the tables usable when you don't have that option, as for example in PDF output. Even with a wide window, though, some of our function tables are monstrously ugly. Sure, but I wager the number of people using the HTML version of our documentation on laptops and desktop computers are the biggest group of users. That said, I agree with that quite many of our tables right now are ugly, but I prefer ugly to hard to read. For me the mix of having every third row split into two fields makes the tables very hard to read. I have a hard time seeing which rows belong to which function. Andreas
Re: Poll: are people okay with function/operator table redesign?
Andreas Karlsson writes: > For the old tables I can at least just make the browser window > ridiculously wide ro read them. A large part of the point here is to make the tables usable when you don't have that option, as for example in PDF output. Even with a wide window, though, some of our function tables are monstrously ugly. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 7:13 PM, Tom Lane wrote: As discussed in the thread at [1], I've been working on redesigning the tables we use to present SQL functions and operators. The first installment of that is now up; see tables 9.30 and 9.31 at https://www.postgresql.org/docs/devel/functions-datetime.html and table 9.33 at https://www.postgresql.org/docs/devel/functions-enum.html Before I spend more time on this, I want to make sure that people are happy with this line of attack. Comparing these tables to the way they look in v12, they clearly take more vertical space; but at least to my eye they're less cluttered and more readable. They definitely scale a lot better for cases where a long function description is needed, or where we'd like to have more than one example. Does anyone prefer the old way, or have a better idea? I know that the table headings are a bit weirdly laid out; hopefully that can be resolved [2]. I prefer the old way since I find it very hard to see which fields belong to which function in the new way. I think what confuses my eyes is how some rows are split in half while others are not, especially for those functions where there is only one example output. I do not have any issue reading those with many example outputs. For the old tables I can at least just make the browser window ridiculously wide ro read them. Andreas
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 7:55 PM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> On 4/13/20 7:02 PM, Jonathan S. Katz wrote: >>> Perhaps a counterproposal: We eliminate the content in the leftmost >>> "function column, but leave that there to allow the function name / >>> signature to span the full 3 columns. Then the rest of the info goes >>> below. This will also compress the table height down a bit. >> An attempt at a "POC" of what I'm describing (attached image). > Hmm ... what is determining the width of the left-hand column? > It doesn't seem to have any content, since the function entries > are being spanned across the whole table. > > I think the main practical problem though is that it wouldn't > work nicely for operators, since the key "name" you'd be looking > for would not be at the left of the signature line. I suppose we > don't necessarily have to have the same layout for operators as > for functions, but it feels like it'd be jarringly inconsistent. > > Maybe highlight the item by bolding or colour? cheers andrew -- Andrew Dunstanhttps://www.2ndQuadrant.com PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
Hello Tom, Before I spend more time on this, I want to make sure that people are happy with this line of attack. +1 I like it this way, because the structure is quite readable, which is the point. My 0.02€: Maybe column heander "Example Result" should be simply "Result", because it is already on the same line as "Example" on its left, and "Example | Example Result" looks redundant. Maybe the signature and description lines could be exchanged: I'm more interested and the description first, and the signature just above the example would make sense. I'm wondering whether the function/operator name should be vertically centered in its cell? I'd left it left justified. -- Fabien.
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > On 4/13/20 7:02 PM, Jonathan S. Katz wrote: >> Perhaps a counterproposal: We eliminate the content in the leftmost >> "function column, but leave that there to allow the function name / >> signature to span the full 3 columns. Then the rest of the info goes >> below. This will also compress the table height down a bit. > An attempt at a "POC" of what I'm describing (attached image). Hmm ... what is determining the width of the left-hand column? It doesn't seem to have any content, since the function entries are being spanned across the whole table. I think the main practical problem though is that it wouldn't work nicely for operators, since the key "name" you'd be looking for would not be at the left of the signature line. I suppose we don't necessarily have to have the same layout for operators as for functions, but it feels like it'd be jarringly inconsistent. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 2020-Apr-13, Jonathan S. Katz wrote: > On 4/13/20 7:02 PM, Jonathan S. Katz wrote: > > Perhaps a counterproposal: We eliminate the content in the leftmost > > "function column, but leave that there to allow the function name / > > signature to span the full 3 columns. Then the rest of the info goes > > below. This will also compress the table height down a bit. > > An attempt at a "POC" of what I'm describing (attached image). > > I'm not sure if I 100% like it, but it does reduce the amount of > information we're displaying but conveys all the details (and matches > what we have in the previous version). Ooh, this seems a nice idea -- the indentation seems to be sufficient to tell apart entries from each other. Your point about information reduction refers to the fact that we no longer keep the unadorned name but only the signature, right? That seems an improvement to me now that I look at it. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
I wrote: > I don't think I like the version better than --- it adds > quite a bit of vertical space, more than I was expecting really. Actually, after staring more at HTML-hr.png, what's *really* bothering me about that rendering is that the lines made by are actually wider than the inter-table-cell lines. Surely we want the opposite relationship. Presumably that could be fixed with some css-level adjustments; and maybe the spacing could be tightened up a bit too? I do like having that visual separation, it just needs to be toned down compared to the table cell separators. Reproducing the effect in the PDF build remains an issue, too. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 7:02 PM, Jonathan S. Katz wrote: > On 4/13/20 6:51 PM, Tom Lane wrote: >> "Jonathan S. Katz" writes: >>> I think one thing that was throwing me off was having the function >>> signature before the description. I would recommend flipping them: have >>> the function description first, followed by signature, followed be >>> examples. I think that follows the natural flow more of what one is >>> doing when they look up the function. >> >> The trouble with that is it doesn't work very well when we have >> multiple similarly-named functions with different signatures. >> Consider what the two enum_range() entries in 9.33 will look like, >> for example. I think we need the signature to establish which function >> we're talking about. > > I get that, I just find I'm doing too much thinking looking at it. > > Perhaps a counterproposal: We eliminate the content in the leftmost > "function column, but leave that there to allow the function name / > signature to span the full 3 columns. Then the rest of the info goes > below. This will also compress the table height down a bit. An attempt at a "POC" of what I'm describing (attached image). I'm not sure if I 100% like it, but it does reduce the amount of information we're displaying but conveys all the details (and matches what we have in the previous version). The alignment could be adjusted if need be, too. Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 6:51 PM, Tom Lane wrote: > "Jonathan S. Katz" writes: >> I think one thing that was throwing me off was having the function >> signature before the description. I would recommend flipping them: have >> the function description first, followed by signature, followed be >> examples. I think that follows the natural flow more of what one is >> doing when they look up the function. > > The trouble with that is it doesn't work very well when we have > multiple similarly-named functions with different signatures. > Consider what the two enum_range() entries in 9.33 will look like, > for example. I think we need the signature to establish which function > we're talking about. I get that, I just find I'm doing too much thinking looking at it. Perhaps a counterproposal: We eliminate the content in the leftmost "function column, but leave that there to allow the function name / signature to span the full 3 columns. Then the rest of the info goes below. This will also compress the table height down a bit. >> There are probably some things we can do with shading on the pgweb side >> to make items more distinguishable, I don't think that would be too >> terrible to add. > > Per David's earlier comment, it seems like alternating backgrounds might > be feasible if we can get it down to one per function, as the > version I just posted has. or a classname on the "" when a new function starts or the like. Easy enough to get the CSS to work off of that :) Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
"Jonathan S. Katz" writes: > I think one thing that was throwing me off was having the function > signature before the description. I would recommend flipping them: have > the function description first, followed by signature, followed be > examples. I think that follows the natural flow more of what one is > doing when they look up the function. The trouble with that is it doesn't work very well when we have multiple similarly-named functions with different signatures. Consider what the two enum_range() entries in 9.33 will look like, for example. I think we need the signature to establish which function we're talking about. > There are probably some things we can do with shading on the pgweb side > to make items more distinguishable, I don't think that would be too > terrible to add. Per David's earlier comment, it seems like alternating backgrounds might be feasible if we can get it down to one per function, as the version I just posted has. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
> > Yeah, back at the beginning of this exercise, Alvaro wondered aloud > if we should go to something other than tables altogether. I dunno > what that'd look like though. > It would probably look like our acronyms and glossary pages. Maybe the return example and return values get replaced with a programlisting?
Re: Poll: are people okay with function/operator table redesign?
> > Thinking out loud, it'd also be great if we could add in some anchors as > well, so perhaps in the future on the pgweb side we could add in some > discoverable links that other documentation has -- which in turn people > could click / link to others directly to the function name. > +1
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 1:13 PM, Tom Lane wrote: > As discussed in the thread at [1], I've been working on redesigning > the tables we use to present SQL functions and operators. The > first installment of that is now up; see tables 9.30 and 9.31 at > > https://www.postgresql.org/docs/devel/functions-datetime.html > > and table 9.33 at > > https://www.postgresql.org/docs/devel/functions-enum.html > > Before I spend more time on this, I want to make sure that people > are happy with this line of attack. Comparing these tables to > the way they look in v12, they clearly take more vertical space; > but at least to my eye they're less cluttered and more readable. > They definitely scale a lot better for cases where a long function > description is needed, or where we'd like to have more than one > example. Does anyone prefer the old way, or have a better idea? > > I know that the table headings are a bit weirdly laid out; hopefully > that can be resolved [2]. > [2] https://www.postgresql.org/message-id/6169.1586794603%40sss.pgh.pa.us When evaluating [2], I will admit at first I was very confused about the layout and wasn't exactly sure what you were saying was incorrect in that note. After fixing [2] on my local copy, I started to look at it again. For positives, I do think it's an improvement for readability on mobile. Flow/content aside, it was easier to read and follow what was going on and there was less side scrolling. I think one thing that was throwing me off was having the function signature before the description. I would recommend flipping them: have the function description first, followed by signature, followed be examples. I think that follows the natural flow more of what one is doing when they look up the function. I think that would also benefit larger tables too: instead of having to scroll up to understand how things are laid out, it'd follow said flow. There are probably some things we can do with shading on the pgweb side to make items more distinguishable, I don't think that would be too terrible to add. Thinking out loud, it'd also be great if we could add in some anchors as well, so perhaps in the future on the pgweb side we could add in some discoverable links that other documentation has -- which in turn people could click / link to others directly to the function name. Anyway, change is hard. I'm warming up to it. Jonathan signature.asc Description: OpenPGP digital signature
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 1:57 PM Tom Lane wrote: > Actually ... if we did it like that, then it would be possible to treat > the signature + description + example(s) as one big table cell with line > breaks rather than row-separator bars. > That would help address the > inadequate-visual-separation-between-groups issue, but on the other hand > maybe we'd end up with too little visual separation between the elements > of a function description. > Speaking in terms of HTML if we use instead of we would get the best of both worlds. David J.
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 1:41 PM Tom Lane wrote:
> "David G. Johnston" writes:
> > Can we lightly background color every other rowgroup (i.e., "greenbar")?
>
> If you know how to do that at all, let alone in a maintainable way (ie
> one where inserting a new function doesn't require touching the entries
> for the ones after), let's see it.
>
The nth-child({odd|even}) CSS Selector should provide the desired
functionality, at least for HTML, but the structure will need to modified
so that there is some single element that represents a single rowgroup. I
tried (not too hard) to key off of the presence of the "rowspan" attribute
but that does not seem possible.
https://www.w3schools.com/cssref/sel_nth-child.asp
David J.
Re: Poll: are people okay with function/operator table redesign?
I wrote: > "David G. Johnston" writes: >> I don't think having a separate Result column helps. The additional >> horizontal whitespace distances all relevant context information (at least >> on a wide monitor). Having the example rows mirror the Signature row seems >> like an easier to consume choice. > Interesting idea. I'm afraid that it would not look so great in cases > where the example-plus-result overflows one line, which would inevitably > happen in PDF format. Still, maybe that would be rare enough to not be > a huge problem. In most places it'd be a win to not have to separately > allocate example and result space. Actually ... if we did it like that, then it would be possible to treat the signature + description + example(s) as one big table cell with line breaks rather than row-separator bars. That would help address the inadequate-visual-separation-between-groups issue, but on the other hand maybe we'd end up with too little visual separation between the elements of a function description. A quick google search turned up this suggestion about how to force line breaks in docbook table cells: http://www.sagehill.net/docbookxsl/LineBreaks.html which seems pretty hacky but it should work. Anyone know a better way? regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
"David G. Johnston" writes: > Can we lightly background color every other rowgroup (i.e., "greenbar")? If you know how to do that at all, let alone in a maintainable way (ie one where inserting a new function doesn't require touching the entries for the ones after), let's see it. I agree it'd be a nice solution, if we could make it work, but I don't see how. I'd been imagining instead that we could give a different background color to the first line of each group; which I don't know how to do but it at least seems plausible that a style could be attached to a . > I don't think having a separate Result column helps. The additional > horizontal whitespace distances all relevant context information (at least > on a wide monitor). Having the example rows mirror the Signature row seems > like an easier to consume choice. Interesting idea. I'm afraid that it would not look so great in cases where the example-plus-result overflows one line, which would inevitably happen in PDF format. Still, maybe that would be rare enough to not be a huge problem. In most places it'd be a win to not have to separately allocate example and result space. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
Andrew Dunstan writes: > One thing that did occur to me is that the function/operator name is > essentially redundant, as it's in the signature anyway. Not sure if that > helps us any though. Hm, you have a point there. However, if we drop the lefthand column then there really isn't any visual distinction between the row(s) associated with one function and those of the next. Unless we can find another fix for that aspect (as already discussed in this thread) I doubt it'd be an improvement. > Maybe we're just trying to shoehorn too much information into a single > table. Yeah, back at the beginning of this exercise, Alvaro wondered aloud if we should go to something other than tables altogether. I dunno what that'd look like though. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 11:27 AM Tom Lane wrote: > Isaac Morland writes: > > > - I think there should be much more distinctive lines between the > different > > functions. As it is the fact that the table is groups of 3 lines doesn’t > > jump out at the eye. > > I don't know any easy way to do that. We do already have the grouping > visible in the first column... > Can we lightly background color every other rowgroup (i.e., "greenbar")? I don't think having a separate Result column helps. The additional horizontal whitespace distances all relevant context information (at least on a wide monitor). Having the example rows mirror the Signature row seems like an easier to consume choice. e.g., enum_first(null::rainbow) → red date '2001-09-28' + 7 → 2001-10-05 Its also removes the left alignment in a fixed width column which draws unwanted visual attention. David J.
Re: Poll: are people okay with function/operator table redesign?
Robert Haas writes: > I just wonder if there's too much clutter here. Like, line 1: > date - interval → timestamp > OK, gotcha. Line 2: > Subtract an interval from a date > Well, is that really adding anything non-obvious? Yeah, back in the other thread I said >>> I decided to try converting the date/time operators table too, to >>> see how well this works for that. It's bulkier than before, but >>> also (I think) more precise. I realized that this table actually >>> had three examples already for float8 * interval, but it wasn't >>> at all obvious that they were the same operator. So that aspect >>> is a lot nicer here. On the other hand, it seems like the text >>> descriptions are only marginally useful here. I can imagine that >>> they would be useful in some other operator tables, such as >>> geometric operators, but I'm a bit tempted to leave them out >>> in this particular table. The format would adapt to that easily. I wouldn't be averse to dropping the text descriptions for operators in places where they seem obvious ... but who decides what is obvious? Indeed, we've gotten more than one complaint in the past that some of the geometric and JSON operators require a longer explanation than they've got. So one of the points here was to have a format that could adapt to that. But in this particular table I agree they're marginal. regards, tom lane
Re: Poll: are people okay with function/operator table redesign?
On 4/13/20 1:13 PM, Tom Lane wrote: > As discussed in the thread at [1], I've been working on redesigning > the tables we use to present SQL functions and operators. The > first installment of that is now up; see tables 9.30 and 9.31 at > > https://www.postgresql.org/docs/devel/functions-datetime.html > > and table 9.33 at > > https://www.postgresql.org/docs/devel/functions-enum.html > > Before I spend more time on this, I want to make sure that people > are happy with this line of attack. Comparing these tables to > the way they look in v12, they clearly take more vertical space; > but at least to my eye they're less cluttered and more readable. > They definitely scale a lot better for cases where a long function > description is needed, or where we'd like to have more than one > example. Does anyone prefer the old way, or have a better idea? > > I know that the table headings are a bit weirdly laid out; hopefully > that can be resolved [2]. > > regards, tom lane > > [1] https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us > [2] https://www.postgresql.org/message-id/6169.1586794603%40sss.pgh.pa.us > Gotta say I'm not a huge fan. I appreciate the effort, and I get the problem, but I'm not sure we have a net improvement here. One thing that did occur to me is that the function/operator name is essentially redundant, as it's in the signature anyway. Not sure if that helps us any though. Maybe we're just trying to shoehorn too much information into a single table. cheers andrew -- Andrew Dunstanhttps://www.2ndQuadrant.com PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Poll: are people okay with function/operator table redesign?
On Mon, Apr 13, 2020 at 2:47 PM Tom Lane wrote: > Another possibility, which'd only help in HTML, would be to render > some of the cells with a slightly different background color. > That's beyond my docbook/css skills, but it might be possible. I think some visual distinction would be really helpful, if we can get it. I just wonder if there's too much clutter here. Like, line 1: date - interval → timestamp OK, gotcha. Line 2: Subtract an interval from a date Well, is that really adding anything non-obvious? -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Re: Poll: are people okay with function/operator table redesign?
Alvaro Herrera writes: > One improvement (that I don't know is possible in docbook) would be to > have the inter-logical-row line be slightly thicker than the > intra-logical-row one. That'd make each entry visually more obvious. Yeah, I don't see any way to do that :-(. We could suppress the row lines entirely between the members of the logical group, but that'd almost surely look worse. (I tried to implement this to see, and couldn't get rowsep="0" in a to render the way I expected, so there may be toolchain bugs in the way of it anyway.) We could leave an entirely empty row between logical groups, but that would be really wasteful of vertical space. Another possibility, which'd only help in HTML, would be to render some of the cells with a slightly different background color. That's beyond my docbook/css skills, but it might be possible. regards, tom lane
