Doc: introduce and document "&zwsp;" for allowing optional line breaks.

We already had a couple of places using zero-width spaces for formatting
hackery, and we're going to need more if we ever want the PDF manuals to
look decent.  But please let's not write hard-coded Unicode escapes.
We can avoid that by using a custom entity, which also provides a place
to put a teeny bit of documentation about what it is and how to use it.

I'd previously posted a patch using "&break;" for this, but on reflection
that would be horrible to grep for.  Instead let's use "&zwsp;", based
on the name of the Unicode symbol ("zero width space").

Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 12d75b476f3ea31f6051f3f188bd98950f7fa066..5e5bfddf7c52c10a529c9703ed0beb235dbe24e2 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2981,7 +2981,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         the result written in hexadecimal
        
        md5('Th\000omas'::bytea)
-       8ab2d3c9689aaf18​b4958c334c82d8b1
+       8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1
       
 
       
@@ -3032,7 +3032,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-224 hash
        
        sha224('abc'::bytea)
-       \x23097d223405d8228642a477bda2​55b32aadbce4bda0b3f7e36c9da7
+       \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7
       
 
       
@@ -3047,7 +3047,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-256 hash
        
        sha256('abc'::bytea)
-       \xba7816bf8f01cfea414140de5dae2223​b00361a396177a9cb410ff61f20015ad
+       \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad
       
 
       
@@ -3062,7 +3062,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-384 hash
        
        sha384('abc'::bytea)
-       \xcb00753f45a35e8bb5a03d699ac65007​272c32ab0eded1631a8b605a43ff5bed​;8086072ba1e7cc2358baeca134c825a7
+       \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7
       
 
       
@@ -3077,7 +3077,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
          SHA-512 hash
        
        sha512('abc'::bytea)
-       \xddaf35a193617abacc417349ae204131​12e6fa4e89a97ea20a9eeee64b55d39a​2192992a274fc1a836ba3c23a3feebbd​;454d4423643ce80e2a9ac94fa54ca49f
+       \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f
       
 
       

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index ba3d6261029a476c8cc86f55cea64f07baf79636..f4a3c7e5e7c88b32e72f0702825a442584dc242d 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -11,6 +11,13 @@
 
 
 
+
+
+
 ]>