Re: Another modest proposal for docs formatting: catalog descriptions

[Tom Lane]

Just FTR, here's a complete patch for this.  I successfully regenerated
the column names, types, and ordering from the system catalogs, and
plugged the descriptions back into that by dint of parsing them out of
the XML.  The "references" data was based on findoidjoins' results plus
hand additions to cover all the cases we are calling out now (there are
a lot of "references" links for attnums and a few other non-OID columns,
plus references links for views which findoidjoins doesn't consider).
So I have pretty high confidence that this info is OK.  I'd be too
embarrassed to show anybody the code though ;-) ... it was just a brute
force hack.

regards, tom lane



catalog-reformat.patch.gz
Description: catalog-reformat.patch.gz
--- main.css~	2020-05-10 12:18:39.773129302 -0400
+++ main.css	2020-05-09 21:46:22.424776849 -0400
@@ -792,13 +792,6 @@
 }
 
 /** Formatting for entries in tables of functions: indent all but first line **/
-#docContent table.table th.functableentry,
-#docContent table.table td.functableentry {
-	padding-left: 4em;
-	text-indent: -3.5em;
-	text-align: left;
-}
-
 #docContent table.table th.func_table_entry p,
 #docContent table.table td.func_table_entry p {
   margin-top: 0.1em;
@@ -820,6 +813,38 @@
   padding-left: 4em;
 }
 
+/** Formatting for entries in tables of catalog/view columns **/
+#docContent table.table th.catalog_table_entry p,
+#docContent table.table td.catalog_table_entry p {
+  margin-top: 0.1em;
+  margin-bottom: 0.1em;
+  padding-left: 4em;
+  text-align: left;
+}
+
+#docContent table.table th.catalog_table_entry p.column_definition {
+  text-indent: -3.5em;
+  word-spacing: 0.25em;
+}
+
+#docContent table.table td.catalog_table_entry p.column_definition {
+  text-indent: -3.5em;
+}
+
+#docContent table.table p.column_definition code.type {
+  padding-left: 0.25em;
+  padding-right: 0.25em;
+}
+
+#docContent table.table td.catalog_table_entry pre.programlisting {
+  background-color: inherit;
+  border: 0;
+  margin-bottom: 0.1em;
+  margin-top: 0.1em;
+  padding: 0;
+  padding-left: 4em;
+}
+
 /**
  * Titles, Navigation
  */

Re: Another modest proposal for docs formatting: catalog descriptions

[Jonathan S. Katz]

On 5/10/20 12:27 PM, Tom Lane wrote:
> Just FTR, here's a complete patch for this. 

Cool. I'll play around with it tonight once I clear out release work.
Per upthread reference, I believe you've become a CSS maven yourself.

> I successfully regenerated
> the column names, types, and ordering from the system catalogs, and
> plugged the descriptions back into that by dint of parsing them out of
> the XML.  The "references" data was based on findoidjoins' results plus
> hand additions to cover all the cases we are calling out now (there are
> a lot of "references" links for attnums and a few other non-OID columns,
> plus references links for views which findoidjoins doesn't consider).
> So I have pretty high confidence that this info is OK.  I'd be too
> embarrassed to show anybody the code though ;-) ... it was just a brute
> force hack.
If it works it works ;)

Jonathan



signature.asc
Description: OpenPGP digital signature

Remaining PDF layout issues

[Tom Lane]

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

Getting rid of "Unresolved ID reference" in PDF builds

[Tom Lane]

Our PDF docs build has a couple of dozen complaints like

WARNING: Destination: Unresolved ID reference "sql-altercollation-notes-title" 
found.

These are due to cross-reference links like this:

  See  below.

They seem to render as desired, so it's not clear why we're getting the
warnings, but nonetheless we are.  I experimented and found that it seems
to work just as well, with no warnings, if we use xreflabels instead;
that is,

@@ -93,16 +93,15 @@ ALTER COLLATION name SET SCHEMA 
new_sche
 
  
   Update the collation's version.
-  See  below.
+  See  below.
  
 

   
  
 
- 
-  Notes
+ 
+  Notes
 
   
When using collations provided by the ICU library, the ICU-specific version

Since the xreflabel method is already used in our docs, in many more
places than the id-on-a-title method is, I propose we just get rid
of all of these in favor of xreflabels.  Does anyone know a reason
to keep these?

There are also a couple of similar warnings

WARNING: Page 230: Unresolved ID reference "function-decode" found.
WARNING: Page 230: Unresolved ID reference "function-encode" found.

that stem from trying to use an "id" on a table .  While that
seems to work and produce a live link in the HTML build, it fails
to work at all in the PDF build.  We'd previously discovered that
it works in both builds if you stick the "id" on an 
instead:

@@ -4355,9 +4355,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 
'three');
   
  
 
- 
+ 
   
-   
+   
 encode

encode ( bytes 
bytea,

so I propose doing that.

regards, tom lane

Re: 【memory barrier】Should we update the README.barrier description.

[Simon Riggs]

On Sun, 10 May 2020 at 02:01, postgresql_2...@163.com <
postgresql_2...@163.com> wrote:

> Hi
>
> When I read the introduction of Weaknesses of Memory Barriers in
> README.barrier, the following maybe out-of-date now.
>
> Even very simple write operations often require additional synchronization.
> For example, it's not safe for multiple writers to simultaneously execute
> this code (supposing x is a pointer into shared memory):
>
> x->foo++;
>
> Although this may compile down to a single machine-language instruction,
> the CPU will execute that instruction by reading the current value of foo,
> adding one to it, and then storing the result back to the original address.
> If two CPUs try to do this simultaneously, both may do their reads before
> either one does their writes.  *Eventually we might be able to use an
> atomic
> fetch-and-add instruction for this specific case on architectures that
> support
> it, but we can't rely on that being available everywhere, and we currently
> have no support for it at all.  Use a lock.*
>


> Now, the postgres has support atomic operation and use it


Yes, those docs can change now.


> in some cases we
> have not use the lock.
>

Which code does not use the lock?

-- 
Simon Riggshttp://www.2ndQuadrant.com/

Mission Critical Databases