mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-11-21 03:13:05 +08:00
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
This commit is contained in:
Bruce Momjian
parent
fc7ddededb
commit
641a5b7a14
@ -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
Normal file
37
doc/src/sgml/README.non-ASCII
Normal 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., Á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
|
||||
@ -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 'Å' = '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&'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' = 'ñ'</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>'á'</literal> may be composed of the
|
||||
code points <literal>U&'\0061\0301'</literal> or the single code
|
||||
point <literal>U&'\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>'àe'</literal>
|
||||
before <literal>'aé'</literal>.
|
||||
</entry>
|
||||
</row>
|
||||
|
||||
|
||||
@ -72,7 +72,7 @@
|
||||
<title>a4->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->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">
|
||||
|
||||
|
Before Width: | Height: | Size: 7.3 KiB After Width: | Height: | Size: 7.3 KiB |
@ -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 Álvaro Herrera
|
||||
|
||||
wrap long lines
|
||||
|
||||
For new features, add links to the documentation sections.
|
||||
|
||||
@ -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, "%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:context>
|
||||
</l:l10n>
|
||||
</l:i18n>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user