open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: improve build for non-Latin1 characters

Browse Source 
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
pull/182/head
Bruce Momjian 1 year ago
parent fc7ddededb
commit 641a5b7a14
6 changed files with 56 additions and 36 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 11
      doc/src/sgml/Makefile
  2. 37
      doc/src/sgml/README.non-ASCII
  3. 10
      doc/src/sgml/charset.sgml
  4. 4
      doc/src/sgml/images/genetic-algorithm.svg
  5. 18
      doc/src/sgml/release.sgml
  6. 12
      doc/src/sgml/stylesheet-man.xsl

11
doc/src/sgml/Makefile
Unescape View File

@ -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)
##

37
doc/src/sgml/README.non-ASCII
Unescape View File

@ -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

10
doc/src/sgml/charset.sgml
Unescape View File

@ -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>

4
doc/src/sgml/images/genetic-algorithm.svg
Unescape View File

@ -72,7 +72,7 @@
<title>a4-&gt;end</title>
<path fill="none" stroke="#000000" d="M259,-312.5834C259,-312.5834 259,-54.659 259,-54.659"/>
<polygon fill="#000000" stroke="#000000" points="262.5001,-54.659 259,-44.659 255.5001,-54.6591 262.5001,-54.659"/>
<text text-anchor="middle" x="246" y="-186.6212" font-family="sans-serif" font-size="10.00" fill="#000000">true  </text>
<text text-anchor="middle" x="246" y="-186.6212" font-family="sans-serif" font-size="10.00" fill="#000000">true</text>
</g>
<!-- a5 -->
<g id="node7" class="node">
@ -85,7 +85,7 @@
<title>a4-&gt;a5</title>
<path fill="none" stroke="#000000" d="M144,-298.269C144,-298.269 144,-286.5248 144,-286.5248"/>
<polygon fill="#000000" stroke="#000000" points="147.5001,-286.5248 144,-276.5248 140.5001,-286.5249 147.5001,-286.5248"/>
<text text-anchor="middle" x="127" y="-284.3969" font-family="sans-serif" font-size="10.00" fill="#000000">false   </text>
<text text-anchor="middle" x="127" y="-284.3969" font-family="sans-serif" font-size="10.00" fill="#000000">false</text>
</g>
<!-- a6 -->
<g id="node8" class="node">

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.3 KiB

After

Width:  |  Height:  |  Size: 7.3 KiB

18
doc/src/sgml/release.sgml
Unescape View File

@ -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.

12
doc/src/sgml/stylesheet-man.xsl
Unescape View File

@ -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>

Write Preview
Loading…
Cancel
Save