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)
# 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 $<
## 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 $@ $^
##
# 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 $<
# 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)
##
--- /dev/null
+
+
+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
-- 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.
'ab' = U&'a\2063b'
'x-y' = 'x_y'
'g' = 'G'
- 'n' = 'ñ'
+ 'n' = 'ñ'
'y' = 'z'
At every level, even with full normalization off, basic normalization is
- performed. For example, 'á' may be composed of the
+ performed. For example, 'á' may be composed of the
code points U&'\0061\0301' or the single code
point U&'\00E1', and those sequences will be
considered equal even at the identic level. To treat
false
Backwards comparison for the level 2 differences. For example,
- locale und-u-kb sorts 'àe'
- before 'aé'.
+ locale und-u-kb sorts 'àe'
+ before 'aé'.
a4->end
-true
+true
a4->a5
-false
+false
\<[a-z]+_[a-z_]+\> ,
-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.
- %t, in the documentation"/>
- “%t”, in the documentation"/>
- “%t”, in the documentation"/>
- “%t”, in the documentation"/>
- “%t”, in the documentation"/>
- “%t”, in the documentation"/>
+ "%t", in the documentation"/>
+ "%t", in the documentation"/>
+ "%t", in the documentation"/>
+ "%t", in the documentation"/>
+ "%t", in the documentation"/>
+ "%t", in the documentation"/>
projects / postgresql.git / commitdiff
