Horton

Thread

Commits

  1. Doc: hack on table 26.1 till it fits in PDF format.

  2. Doc: tweak examples to silence line-too-long PDF build warnings.

  3. Doc: split up wait_event table.

  4. Doc: hack table 13.2 "Conflicting Lock Modes" till it fits in PDF.

  5. Doc: fix remaining over-length entries in SQL keywords table.

  1. Remaining PDF layout issues

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-10T21:31:20Z

    There are something like 140 "exceeds the available area" PDF build
warnings that will remain after the catalog-table reformatting I've
proposed nearby.  I've looked through these and they fall into
two groups:

1. We have lots of overwidth examples.  Using our standard monospaced
font, A4-size paper has room for lines at most 67 characters long, and
many of our examples blow past that.  In practice it seems that FOP will
only complain if there's an uninterrupted run of more than 67 dashes;
otherwise it'll just silently break the lines at some point.  (Hence,
almost all the warnings are about EXPLAIN output; other wide examples
tend to be multi-column query results, and FOP will break those header
lines quietly.)  So a minimum "fix" to silence the warnings would be to
throw in a &zwsp; to allow breaking those header separator lines.  Or we
could just truncate those header lines at 67 characters --- though that
might make the examples look funny in wider windows.  However, if FOP is
whining about the header line, that implies that it's breaking some of
the data lines too, possibly rendering the output less readable than one
could wish.  Should we worry about that? and if so, what could be done
about it?  Since there are lots and lots of places where example text
is getting line-wrapped *without* any nearby warnings, I'm inclined to
write this off as not much of a concern.  But if anyone has ideas about
really fixing it, I'd like to hear them.

2. The other category of problems is tables that are too wide.  The
hacking I've done to date has fixed that for most tables, but we still
have some individual tables with layout issues:

Table 13.2.  Conflicting Lock Modes
Table 26.1.  High Availability, Load Balancing, and Replication Feature Matrix
Table 27.4.  wait_event Description
Table C.1.   SQL Key Words

The trouble with 13.2 is the column headers.  The table cell entries
are just "X"s or empty, but the headers are verbose and do not fit.
Short of a wholesale redesign, the only fix I can see is to abbreviate
the headers.  It looks like abbreviating EXCLUSIVE to EXCL might be
enough, though I've not actually tried it.  That would be kinda
weird-looking when seen in a window where there's plenty of room,
and as far as I know we can't get DocBook to vary the text based on
output format.  Anyone got a better idea?

Table 26.1 has got the identical issue of overly wordy column headers.
TBH, my inclination with this table is not to find a way to fix it
but just to remove it.  It looks to me like it's just restating the
material above it, and it's not even a usefully complete summary because
it omits some of the categories (which got kicked to below it, just
because they didn't fit into the table's worldview).  I also wonder why
"Commercial Solutions" is a category at all.

Table 27.4 is annoying: it could be made to work, just barely, with some
hacking of the column widths and a &zwsp; or two.  But it's not stable
text so I have little faith in the longevity of such a solution,
especially if people keep on inventing long wait event names.  I also
find it not very readable, even in a wide window.  The first idea that
comes to mind is to split it into multiple tables, one per "Wait Event
Type", so that we don't need the lefthand column.  Another idea is to
go over to a format similar to what I've proposed for catalog tables,
with entries like

	Timeout / BaseBackupThrottle
	    Descriptive text here ...
	Timeout / RecoveryApplyDelay
	    Descriptive text here ...

The trouble with table C.1 is that some of the SQL committee's keywords
are too long, even after the hacking I did to give the keywords a wider
column.  One wonders why things like "CURRENT_DEFAULT_TRANSFORM_GROUP"
are keywords at all.  We could do something with spanspec or morerows
to give those specific keywords extra space, but it would look weird
in renderings where there's plenty of room anyway.

We're within hailing distance of zero "exceeds the available area"
warnings, so I'd like to get these things resolved.

Comments, better ideas?

			regards, tom lane

  2. Re: Remaining PDF layout issues

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-12T01:59:30Z

    I wrote:
> Table 27.4 is annoying: it could be made to work, just barely, with some
> hacking of the column widths and a &zwsp; or two.  But it's not stable
> text so I have little faith in the longevity of such a solution,
> especially if people keep on inventing long wait event names.  I also
> find it not very readable, even in a wide window.  The first idea that
> comes to mind is to split it into multiple tables, one per "Wait Event
> Type", so that we don't need the lefthand column.  Another idea is to
> go over to a format similar to what I've proposed for catalog tables,
> with entries like

> 	Timeout / BaseBackupThrottle
> 	    Descriptive text here ...
> 	Timeout / RecoveryApplyDelay
> 	    Descriptive text here ...

Attached is a draft patch that does it the second way.  This looks
reasonably okay to me, although there's no denying that given a reasonably
wide window, the existing layout requires less vertical space.  But
I'm not sure that matters: I have come to the conclusion, after studying
this table, that nobody has ever yet looked at it.  If they had, we would
surely have gotten gripes about the fact that most of the entries are not
in anything resembling alphabetical order.  How in the world would anyone
look something up in this?  I have not changed the ordering in this patch,
but I think it would be a good idea to fix it to be rigidly alphabetical
(including the "type" part).

BTW, for the purposes of this patch I just abused the
func_table_entry/func_signature role values.  We could invent new ones,
but I'm not sure if it's worthwhile for just one table.

			regards, tom lane

  3. Re: Remaining PDF layout issues

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-12T05:10:06Z

    I wrote:
>> Table 27.4 is annoying: it could be made to work, just barely, with some
>> hacking of the column widths and a &zwsp; or two.  But it's not stable
>> text so I have little faith in the longevity of such a solution,
>> especially if people keep on inventing long wait event names.  I also
>> find it not very readable, even in a wide window.  The first idea that
>> comes to mind is to split it into multiple tables, one per "Wait Event
>> Type", so that we don't need the lefthand column.

Here's an attempt at doing it that way.  I think this might be a better
answer, although it's still subject to problems if anyone's logorrhea gets
any worse in naming wait conditions: "SerializablePredicateLockListLock"
is still going to force manually tweaking the column widths.

I sorted the names here, too.

			regards, tom lane