Remaining PDF layout issues
От | Tom Lane |
---|---|
Тема | Remaining PDF layout issues |
Дата | |
Msg-id | 6916.1589146280@sss.pgh.pa.us обсуждение исходный текст |
Ответы |
Re: Remaining PDF layout issues
(Tom Lane <tgl@sss.pgh.pa.us>)
|
Список | pgsql-docs |
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
В списке pgsql-docs по дате отправления:
Предыдущее
От: "Jonathan S. Katz"Дата:
Сообщение: Re: Another modest proposal for docs formatting: catalog descriptions