doc: improve build for non-Latin1 characters

Add README.non-ASCII to explain non-ASCII doc behavior; some text moved
from release.sgml.

Change UTF8 SGML characters to use HTML entities.

Remove unnecessary UTF8 spaces.

Add SVG file check for check-nbsp target.

Add dummy 'pdf' Makefile target.

Reported-by: Yugo Nagata

Discussion: https://postgr.es/m/20241011114122.c90f8a871462da36f2e2afeb@sraoss.co.jp

Backpatch-through: master

Author: bmomjian

doc/src/sgml/Makefile

@@ -59,7 +59,7 @@ GENERATED_SGML = version.sgml \
 	features-supported.sgml features-unsupported.sgml errcodes-table.sgml \
 	keywords-table.sgml targets-meson.sgml wait_event_types.sgml
 
-ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
+ALL_SGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
 
 ALL_IMAGES := $(wildcard $(srcdir)/images/*.svg)
 
@@ -68,7 +68,7 @@ ALL_IMAGES := $(wildcard $(srcdir)/images/*.svg)
 # we're at it, also resolve all entities (that is, copy all included
 # files into one big file).  This helps tools that don't understand
 # vpath builds (such as dbtoepub).
-postgres-full.xml: postgres.sgml $(ALLSGML)
+postgres-full.xml: postgres.sgml $(ALL_SGML)
 	$(XMLLINT) $(XMLINCLUDE) --output $@ --noent --valid $<
 
 
@@ -143,11 +143,12 @@ postgres.txt: postgres.html
 ## Print
 ##
 
-postgres.pdf:
+postgres.pdf pdf:
 	$(error Invalid target;  use postgres-A4.pdf or postgres-US.pdf as targets)
 
 XSLTPROC_FO_FLAGS += --stringparam img.src.path '$(srcdir)/'
 
+# XSL Formatting Objects (FO), https://en.wikipedia.org/wiki/XSL_Formatting_Objects
 %-A4.fo: stylesheet-fo.xsl %-full.xml
 	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $^
 
@@ -194,7 +195,7 @@ MAKEINFO = makeinfo
 ##
 
 # Quick syntax check without style processing
-check: postgres.sgml $(ALLSGML) check-tabs check-nbsp
+check: postgres.sgml $(ALL_SGML) check-tabs check-nbsp
 	$(XMLLINT) $(XMLINCLUDE) --noout --valid $<
 
 
@@ -264,7 +265,7 @@ check-tabs:
 # Use perl command because non-GNU grep or sed could not have hex escape sequence.
 check-nbsp:
 	@ ( $(PERL) -ne '/\xC2\xA0/ and print("$$ARGV:$$_"),$$n++; END {exit($$n>0)}' \
-	  $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml $(srcdir)/*.xsl) ) || \
+	  $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml $(srcdir)/images/*.svg $(srcdir)/*.xsl $(srcdir)/images/*.xsl) ) || \
 	(echo "Non-breaking spaces appear in SGML/XML files" 1>&2;  exit 1)
 
 ##

doc/src/sgml/README.non-ASCII

@@ -0,0 +1,37 @@
+<!-- doc/src/sgml/README.non-ASCII -->
+
+Representation of non-ASCII characters
+--------------------------------------
+
+Find non-ASCII characters using:
+
+        grep --recursive --color='auto' -P '[\x80-\xFF]' .
+
+Convert to HTML4 named entity (&) escapes
+-----------------------------------------
+
+We support several output formats:
+
+*  html (supports all Unicode characters)
+*  man (supports all Unicode characters)
+*  pdf (supports only Latin-1 characters)
+*  info
+
+While some output formatting tools support all Unicode characters,
+others only support Latin-1 characters.  Specifically, the PDF rendering
+engine can only display Latin-1 characters;  non-Latin-1 Unicode
+characters are displayed as "###".
+
+Therefore, in the SGML files, we only use Latin-1 characters.  We
+typically encode these characters as HTML entities, e.g., &Aacute;lvaro.
+It is also possible to safely represent Latin-1 characters in UTF8
+encoding for all output formats.
+
+Do not use UTF numeric character escapes (&#nnn;).
+
+HTML entities
+        official:      http://www.w3.org/TR/html4/sgml/entities.html
+        one page:      http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
+        other lists:   http://www.zipcon.net/~swhite/docs/computers/browsers/entities.html
+                       http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
+                       https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

doc/src/sgml/charset.sgml

@@ -1225,7 +1225,7 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
 <programlisting>
 -- ignore differences in accents and case
 CREATE COLLATION ignore_accent_case (provider = icu, deterministic = false, locale = 'und-u-ks-level1');
-SELECT 'Å' = 'A' COLLATE ignore_accent_case; -- true
+SELECT '&Aring;' = 'A' COLLATE ignore_accent_case; -- true
 SELECT 'z' = 'Z' COLLATE ignore_accent_case; -- true
 
 -- upper case letters sort before lower case.
@@ -1282,7 +1282,7 @@ SELECT 'w;x*y-z' = 'wxyz' COLLATE num_ignore_punct; -- true
          <entry><literal>'ab' = U&amp;'a\2063b'</literal></entry>
          <entry><literal>'x-y' = 'x_y'</literal></entry>
          <entry><literal>'g' = 'G'</literal></entry>
-         <entry><literal>'n' = 'ñ'</literal></entry>
+         <entry><literal>'n' = '&ntilde;'</literal></entry>
          <entry><literal>'y' = 'z'</literal></entry>
         </row>
        </thead>
@@ -1346,7 +1346,7 @@ SELECT 'w;x*y-z' = 'wxyz' COLLATE num_ignore_punct; -- true
 
     <para>
      At every level, even with full normalization off, basic normalization is
-     performed. For example, <literal>'á'</literal> may be composed of the
+     performed. For example, <literal>'&aacute;'</literal> may be composed of the
      code points <literal>U&amp;'\0061\0301'</literal> or the single code
      point <literal>U&amp;'\00E1'</literal>, and those sequences will be
      considered equal even at the <literal>identic</literal> level. To treat
@@ -1430,8 +1430,8 @@ SELECT 'x-y' = 'x_y' COLLATE level4; -- false
          <entry><literal>false</literal></entry>
          <entry>
           Backwards comparison for the level 2 differences. For example,
-          locale <literal>und-u-kb</literal> sorts <literal>'àe'</literal>
-          before <literal>'aé'</literal>.
+          locale <literal>und-u-kb</literal> sorts <literal>'&agrave;e'</literal>
+          before <literal>'a&eacute;'</literal>.
          </entry>
         </row>
 

doc/src/sgml/images/genetic-algorithm.svg

@@ -16,24 +16,6 @@ pg_[A-Za-z0-9_]+                <application>, <structname>
 \<[a-z]+_[a-z_]+\>              <varname>, <structfield>
                                 <systemitem class="osname">
 
-non-ASCII characters            find using grep -P '[\x80-\xFF]' or
-                                  (remove 'X') grep -X-color='auto' -P -n "[\x80-\xFF]"
-                                convert to HTML4 named entity (&) escapes
-
-        official:      http://www.w3.org/TR/html4/sgml/entities.html
-        one page:      http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
-        other lists:   http://www.zipcon.net/~swhite/docs/computers/browsers/entities.html
-                       http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
-                       https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
-
-        We cannot use UTF8 because rendering engines have to
-        support the referenced characters.
-
-        Do not use numeric _UTF_ numeric character escapes (&#nnn;),
-        we can only use Latin1.
-
-        Example: Alvaro Herrera is &Aacute;lvaro Herrera
-
 wrap long lines
 
 For new features, add links to the documentation sections.

doc/src/sgml/release.sgml

@@ -213,12 +213,12 @@
     <!-- Slight rephrasing to indicate that missing sections are found
          in the documentation. -->
     <l:context name="xref-number-and-title">
-      <l:template name="chapter" text="Chapter %n, %t, in the documentation"/>
-      <l:template name="sect1" text="Section %n, “%t”, in the documentation"/>
-      <l:template name="sect2" text="Section %n, “%t”, in the documentation"/>
-      <l:template name="sect3" text="Section %n, “%t”, in the documentation"/>
-      <l:template name="sect4" text="Section %n, “%t”, in the documentation"/>
-      <l:template name="sect5" text="Section %n, “%t”, in the documentation"/>
+      <l:template name="chapter" text="Chapter %n, &quot;%t&quot;, in the documentation"/>
+      <l:template name="sect1" text="Section %n, &quot;%t&quot;, in the documentation"/>
+      <l:template name="sect2" text="Section %n, &quot;%t&quot;, in the documentation"/>
+      <l:template name="sect3" text="Section %n, &quot;%t&quot;, in the documentation"/>
+      <l:template name="sect4" text="Section %n, &quot;%t&quot;, in the documentation"/>
+      <l:template name="sect5" text="Section %n, &quot;%t&quot;, in the documentation"/>
     </l:context>
   </l:l10n>
 </l:i18n>