diff options
| author | Peter Eisentraut | 2017-11-23 14:39:47 +0000 |
|---|---|---|
| committer | Peter Eisentraut | 2017-11-23 14:44:28 +0000 |
| commit | 3c49c6facb22cdea979f5d1465ba53f972d32163 (patch) | |
| tree | a7da6a95fdb79a3fa313fb74afda16b746f8704e | |
| parent | 2f8d6369e60a244f28e0c93b8a02e73758322915 (diff) | |
Convert documentation to DocBook XML
Since some preparation work had already been done, the only source
changes left were changing empty-element tags like <xref linkend="foo">
to <xref linkend="foo"/>, and changing the DOCTYPE.
The source files are still named *.sgml, but they are actually XML files
now. Renaming could be considered later.
In the build system, the intermediate step to convert from SGML to XML
is removed. Everything is build straight from the source files again.
The OpenSP (or the old SP) package is no longer needed.
The documentation toolchain instructions are updated and are much
simpler now.
Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
346 files changed, 4257 insertions, 4585 deletions
diff --git a/config/docbook.m4 b/config/docbook.m4 index f9307f329e..34b829eade 100644 --- a/config/docbook.m4 +++ b/config/docbook.m4 @@ -1,18 +1,18 @@ # config/docbook.m4 -# PGAC_PROG_NSGMLS -# ---------------- -AC_DEFUN([PGAC_PROG_NSGMLS], -[PGAC_PATH_PROGS(NSGMLS, [onsgmls nsgmls])]) +# PGAC_PATH_XMLLINT +# ----------------- +AC_DEFUN([PGAC_PATH_XMLLINT], +[PGAC_PATH_PROGS(XMLLINT, xmllint)]) # PGAC_CHECK_DOCBOOK(VERSION) # --------------------------- AC_DEFUN([PGAC_CHECK_DOCBOOK], -[AC_REQUIRE([PGAC_PROG_NSGMLS]) -AC_CACHE_CHECK([for DocBook V$1], [pgac_cv_check_docbook], -[cat >conftest.sgml <<EOF -<!doctype book PUBLIC "-//OASIS//DTD DocBook V$1//EN"> +[AC_REQUIRE([PGAC_PATH_XMLLINT]) +AC_CACHE_CHECK([for DocBook XML V$1], [pgac_cv_check_docbook], +[cat >conftest.xml <<EOF +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V$1//EN" "http://www.oasis-open.org/docbook/xml/$1/docbookx.dtd"> <book> <title>test</title> <chapter> @@ -27,13 +27,13 @@ EOF pgac_cv_check_docbook=no -if test -n "$NSGMLS"; then - $NSGMLS -s conftest.sgml 1>&AS_MESSAGE_LOG_FD 2>&1 +if test -n "$XMLLINT"; then + $XMLLINT --noout --valid conftest.xml 1>&AS_MESSAGE_LOG_FD 2>&1 if test $? -eq 0; then pgac_cv_check_docbook=yes fi fi -rm -f conftest.sgml]) +rm -f conftest.xml]) have_docbook=$pgac_cv_check_docbook AC_SUBST([have_docbook]) @@ -630,12 +630,10 @@ vpath_build PG_VERSION_NUM PROVE FOP -OSX XSLTPROC -XMLLINT DBTOEPUB have_docbook -NSGMLS +XMLLINT TCL_SHLIB_LD_LIBS TCL_SHARED_BUILD TCL_LIB_SPEC @@ -16132,19 +16130,19 @@ fi # # Check for DocBook and tools # -if test -z "$NSGMLS"; then - for ac_prog in onsgmls nsgmls +if test -z "$XMLLINT"; then + for ac_prog in xmllint do # Extract the first word of "$ac_prog", so it can be a program name with args. set dummy $ac_prog; ac_word=$2 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 $as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_path_NSGMLS+:} false; then : +if ${ac_cv_path_XMLLINT+:} false; then : $as_echo_n "(cached) " >&6 else - case $NSGMLS in + case $XMLLINT in [\\/]* | ?:[\\/]*) - ac_cv_path_NSGMLS="$NSGMLS" # Let the user override the test with a path. + ac_cv_path_XMLLINT="$XMLLINT" # Let the user override the test with a path. ;; *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR @@ -16154,7 +16152,7 @@ do test -z "$as_dir" && as_dir=. for ac_exec_ext in '' $ac_executable_extensions; do if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_NSGMLS="$as_dir/$ac_word$ac_exec_ext" + ac_cv_path_XMLLINT="$as_dir/$ac_word$ac_exec_ext" $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 break 2 fi @@ -16165,35 +16163,35 @@ IFS=$as_save_IFS ;; esac fi -NSGMLS=$ac_cv_path_NSGMLS -if test -n "$NSGMLS"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 -$as_echo "$NSGMLS" >&6; } +XMLLINT=$ac_cv_path_XMLLINT +if test -n "$XMLLINT"; then + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5 +$as_echo "$XMLLINT" >&6; } else { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 $as_echo "no" >&6; } fi - test -n "$NSGMLS" && break + test -n "$XMLLINT" && break done else - # Report the value of NSGMLS in configure's output in all cases. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for NSGMLS" >&5 -$as_echo_n "checking for NSGMLS... " >&6; } - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 -$as_echo "$NSGMLS" >&6; } + # Report the value of XMLLINT in configure's output in all cases. + { $as_echo "$as_me:${as_lineno-$LINENO}: checking for XMLLINT" >&5 +$as_echo_n "checking for XMLLINT... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5 +$as_echo "$XMLLINT" >&6; } fi -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook V4.2" >&5 -$as_echo_n "checking for DocBook V4.2... " >&6; } +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XML V4.2" >&5 +$as_echo_n "checking for DocBook XML V4.2... " >&6; } if ${pgac_cv_check_docbook+:} false; then : $as_echo_n "(cached) " >&6 else - cat >conftest.sgml <<EOF -<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> + cat >conftest.xml <<EOF +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <book> <title>test</title> <chapter> @@ -16208,13 +16206,13 @@ EOF pgac_cv_check_docbook=no -if test -n "$NSGMLS"; then - $NSGMLS -s conftest.sgml 1>&5 2>&1 +if test -n "$XMLLINT"; then + $XMLLINT --noout --valid conftest.xml 1>&5 2>&1 if test $? -eq 0; then pgac_cv_check_docbook=yes fi fi -rm -f conftest.sgml +rm -f conftest.xml fi { $as_echo "$as_me:${as_lineno-$LINENO}: result: $pgac_cv_check_docbook" >&5 $as_echo "$pgac_cv_check_docbook" >&6; } @@ -16276,60 +16274,6 @@ $as_echo_n "checking for DBTOEPUB... " >&6; } $as_echo "$DBTOEPUB" >&6; } fi -if test -z "$XMLLINT"; then - for ac_prog in xmllint -do - # Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 -$as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_path_XMLLINT+:} false; then : - $as_echo_n "(cached) " >&6 -else - case $XMLLINT in - [\\/]* | ?:[\\/]*) - ac_cv_path_XMLLINT="$XMLLINT" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_XMLLINT="$as_dir/$ac_word$ac_exec_ext" - $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done - done -IFS=$as_save_IFS - - ;; -esac -fi -XMLLINT=$ac_cv_path_XMLLINT -if test -n "$XMLLINT"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5 -$as_echo "$XMLLINT" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi - - - test -n "$XMLLINT" && break -done - -else - # Report the value of XMLLINT in configure's output in all cases. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for XMLLINT" >&5 -$as_echo_n "checking for XMLLINT... " >&6; } - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5 -$as_echo "$XMLLINT" >&6; } -fi - if test -z "$XSLTPROC"; then for ac_prog in xsltproc do @@ -16384,60 +16328,6 @@ $as_echo_n "checking for XSLTPROC... " >&6; } $as_echo "$XSLTPROC" >&6; } fi -if test -z "$OSX"; then - for ac_prog in osx sgml2xml sx -do - # Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 -$as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_path_OSX+:} false; then : - $as_echo_n "(cached) " >&6 -else - case $OSX in - [\\/]* | ?:[\\/]*) - ac_cv_path_OSX="$OSX" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_OSX="$as_dir/$ac_word$ac_exec_ext" - $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done - done -IFS=$as_save_IFS - - ;; -esac -fi -OSX=$ac_cv_path_OSX -if test -n "$OSX"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $OSX" >&5 -$as_echo "$OSX" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi - - - test -n "$OSX" && break -done - -else - # Report the value of OSX in configure's output in all cases. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for OSX" >&5 -$as_echo_n "checking for OSX... " >&6; } - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $OSX" >&5 -$as_echo "$OSX" >&6; } -fi - if test -z "$FOP"; then for ac_prog in fop do diff --git a/configure.in b/configure.in index 3f26f038d6..d9c4a50b4b 100644 --- a/configure.in +++ b/configure.in @@ -2091,12 +2091,10 @@ fi # # Check for DocBook and tools # -PGAC_PROG_NSGMLS +PGAC_PATH_XMLLINT PGAC_CHECK_DOCBOOK(4.2) PGAC_PATH_PROGS(DBTOEPUB, dbtoepub) -PGAC_PATH_PROGS(XMLLINT, xmllint) PGAC_PATH_PROGS(XSLTPROC, xsltproc) -PGAC_PATH_PROGS(OSX, [osx sgml2xml sx]) PGAC_PATH_PROGS(FOP, fop) # diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index df77a142e4..f122b4187f 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -37,15 +37,7 @@ ifndef FOP FOP = $(missing) fop endif -SGMLINCLUDE = -D . -D $(srcdir) - -ifndef NSGMLS -NSGMLS = $(missing) nsgmls -endif - -ifndef OSX -OSX = $(missing) osx -endif +XMLINCLUDE = --path . ifndef XMLLINT XMLLINT = $(missing) xmllint @@ -63,19 +55,6 @@ GENERATED_SGML = version.sgml \ ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) -# Enable some extra warnings -# -wfully-tagged needed to throw a warning on missing tags -# for older tool chains, 2007-08-31 -# -wnet catches XML-style empty-element tags like <xref linkend="abc"/>. -override SPFLAGS += -wall -wno-unused-param -wfully-tagged -wnet -# Additional warnings for XML compatibility. The conditional is meant -# to detect whether we are using OpenSP rather than the ancient -# original SP. -override SPFLAGS += -wempty -ifneq (,$(filter o%,$(notdir $(OSX)))) -override SPFLAGS += -wdata-delim -winstance-ignore-ms -winstance-include-ms -winstance-param-entity -endif - ## ## Man pages @@ -83,9 +62,9 @@ endif man distprep-man: man-stamp -man-stamp: stylesheet-man.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^ +man-stamp: stylesheet-man.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $(wordlist 1,2,$^) touch $@ @@ -136,27 +115,8 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ -INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ - - -## -## SGML->XML conversion -## - -# For obscure reasons, GNU make 3.81 complains about circular dependencies -# if we try to do "make all" in a VPATH build without the explicit -# $(srcdir) on the postgres.sgml dependency in this rule. GNU make bug? -postgres.xml: $(srcdir)/postgres.sgml $(ALLSGML) - $(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $< >[email protected] - $(call mangle-xml,book) - -define mangle-xml -$(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \ - -e '$$_ .= qq{<!DOCTYPE $(1) PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\n} if $$. == 1;' \ - <[email protected] > $@ -endef +INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.sgml $(ALLSGML) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ ## @@ -169,20 +129,20 @@ endif html: html-stamp -html-stamp: stylesheet.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ +html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^) cp $(srcdir)/stylesheet.css html/ touch $@ -htmlhelp: stylesheet-hh.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $^ +htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^) # single-page HTML -postgres.html: stylesheet-html-nochunk.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $^ +postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^) # single-page text postgres.txt: postgres.html @@ -196,13 +156,13 @@ postgres.txt: postgres.html postgres.pdf: $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) -%-A4.fo: stylesheet-fo.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ +%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^) -%-US.fo: stylesheet-fo.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ +%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^) %.pdf: %.fo $(FOP) -fo $< -pdf $@ @@ -213,7 +173,7 @@ postgres.pdf: ## epub: postgres.epub -postgres.epub: postgres.xml +postgres.epub: postgres.sgml $(ALLSGML) $(XMLLINT) --noout --valid $< $(DBTOEPUB) $< @@ -226,7 +186,8 @@ DB2X_TEXIXML = db2x_texixml DB2X_XSLTPROC = db2x_xsltproc MAKEINFO = makeinfo -%.texixml: %.xml +%.texixml: %.sgml $(ALLSGML) + $(XMLLINT) --noout --valid $< $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@ %.texi: %.texixml @@ -242,7 +203,7 @@ MAKEINFO = makeinfo # Quick syntax check without style processing check: postgres.sgml $(ALLSGML) check-tabs - $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< + $(XMLLINT) $(XMLINCLUDE) --noout --valid $< ## @@ -312,7 +273,7 @@ check-tabs: # This allows removing some files from the distribution tarballs while # keeping the dependencies satisfied. -.SECONDARY: postgres.xml $(GENERATED_SGML) +.SECONDARY: $(GENERATED_SGML) .SECONDARY: INSTALL.html INSTALL.xml .SECONDARY: postgres-A4.fo postgres-US.fo @@ -326,8 +287,6 @@ clean: rm -f *.fo *.pdf # generated SGML files rm -f $(GENERATED_SGML) -# SGML->XML conversion - rm -f postgres.xml *.tmp # HTML Help rm -f htmlhelp.hhp toc.hhc index.hhk # EPUB diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index b27a4a325d..1197eefbf3 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -16,9 +16,9 @@ </para> <para> - The functions shown in <xref linkend="functions-adminpack-table"> provide + The functions shown in <xref linkend="functions-adminpack-table"/> provide write access to files on the machine hosting the server. (See also the - functions in <xref linkend="functions-admin-genfile-table">, which + functions in <xref linkend="functions-admin-genfile-table"/>, which provide read-only access.) Only files within the database cluster directory can be accessed, but either a relative or absolute path is allowable. @@ -107,18 +107,18 @@ </indexterm> <para> <function>pg_logdir_ls</function> returns the start timestamps and path - names of all the log files in the <xref linkend="guc-log-directory"> - directory. The <xref linkend="guc-log-filename"> parameter must have its + names of all the log files in the <xref linkend="guc-log-directory"/> + directory. The <xref linkend="guc-log-filename"/> parameter must have its default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>) to use this function. </para> <para> The functions shown - in <xref linkend="functions-adminpack-deprecated-table"> are deprecated + in <xref linkend="functions-adminpack-deprecated-table"/> are deprecated and should not be used in new applications; instead use those shown - in <xref linkend="functions-admin-signal-table"> - and <xref linkend="functions-admin-genfile-table">. These functions are + in <xref linkend="functions-admin-signal-table"/> + and <xref linkend="functions-admin-genfile-table"/>. These functions are provided in <filename>adminpack</filename> only for compatibility with old versions of <application>pgAdmin</application>. </para> diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index bf87df4dcb..ae5f3fac75 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -18,12 +18,12 @@ <para> This chapter will on occasion refer to examples found in <xref - linkend="tutorial-sql"> to change or improve them, so it will be + linkend="tutorial-sql"/> to change or improve them, so it will be useful to have read that chapter. Some examples from this chapter can also be found in <filename>advanced.sql</filename> in the tutorial directory. This file also contains some sample data to load, which is not - repeated here. (Refer to <xref linkend="tutorial-sql-intro"> for + repeated here. (Refer to <xref linkend="tutorial-sql-intro"/> for how to use the file.) </para> </sect1> @@ -37,7 +37,7 @@ </indexterm> <para> - Refer back to the queries in <xref linkend="tutorial-join">. + Refer back to the queries in <xref linkend="tutorial-join"/>. Suppose the combined listing of weather records and city location is of particular interest to your application, but you do not want to type the query each time you need it. You can create a @@ -82,7 +82,7 @@ SELECT * FROM myview; <para> Recall the <classname>weather</classname> and <classname>cities</classname> tables from <xref - linkend="tutorial-sql">. Consider the following problem: You + linkend="tutorial-sql"/>. Consider the following problem: You want to make sure that no one can insert rows in the <classname>weather</classname> table that do not have a matching entry in the <classname>cities</classname> table. This is called @@ -129,7 +129,7 @@ DETAIL: Key (city)=(Berkeley) is not present in table "cities". <para> The behavior of foreign keys can be finely tuned to your application. We will not go beyond this simple example in this - tutorial, but just refer you to <xref linkend="ddl"> + tutorial, but just refer you to <xref linkend="ddl"/> for more information. Making correct use of foreign keys will definitely improve the quality of your database applications, so you are strongly encouraged to learn about them. @@ -447,7 +447,7 @@ FROM empsalary; <para> There are options to define the window frame in other ways, but this tutorial does not cover them. See - <xref linkend="syntax-window-functions"> for details. + <xref linkend="syntax-window-functions"/> for details. </para> </footnote> Here is an example using <function>sum</function>: @@ -554,10 +554,10 @@ SELECT sum(salary) OVER w, avg(salary) OVER w <para> More details about window functions can be found in - <xref linkend="syntax-window-functions">, - <xref linkend="functions-window">, - <xref linkend="queries-window">, and the - <xref linkend="sql-select"> reference page. + <xref linkend="syntax-window-functions"/>, + <xref linkend="functions-window"/>, + <xref linkend="queries-window"/>, and the + <xref linkend="sql-select"/> reference page. </para> </sect1> @@ -692,7 +692,7 @@ SELECT name, altitude <para> Although inheritance is frequently useful, it has not been integrated with unique constraints or foreign keys, which limits its usefulness. - See <xref linkend="ddl-inherit"> for more detail. + See <xref linkend="ddl-inherit"/> for more detail. </para> </note> </sect1> diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 0dd68f0ba1..852e260c09 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -31,7 +31,7 @@ index scans themselves, which may be user-defined operator class code. For example, B-Tree index verification relies on comparisons made with one or more B-Tree support function 1 routines. See <xref - linkend="xindex-support"> for details of operator class support + linkend="xindex-support"/> for details of operator class support functions. </para> <para> @@ -192,7 +192,7 @@ ORDER BY c.relpages DESC LIMIT 10; index that is ordered using an affected collation, simply because <emphasis>indexed</emphasis> values might happen to have the same absolute ordering regardless of the behavioral inconsistency. See - <xref linkend="locale"> and <xref linkend="collation"> for + <xref linkend="locale"/> and <xref linkend="collation"/> for further details about how <productname>PostgreSQL</productname> uses operating system locales and collations. </para> @@ -210,7 +210,7 @@ ORDER BY c.relpages DESC LIMIT 10; logical inconsistency to be introduced. One obvious testing strategy is to call <filename>amcheck</filename> functions continuously when running the standard regression tests. See <xref - linkend="regress-run"> for details on running the tests. + linkend="regress-run"/> for details on running the tests. </para> </listitem> <listitem> @@ -263,7 +263,7 @@ ORDER BY c.relpages DESC LIMIT 10; There is no general method of repairing problems that <filename>amcheck</filename> detects. An explanation for the root cause of an invariant violation should be sought. <xref - linkend="pageinspect"> may play a useful role in diagnosing + linkend="pageinspect"/> may play a useful role in diagnosing corruption that <filename>amcheck</filename> detects. A <command>REINDEX</command> may not be effective in repairing corruption. </para> diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml index d49901c690..53f8049df3 100644 --- a/doc/src/sgml/arch-dev.sgml +++ b/doc/src/sgml/arch-dev.sgml @@ -7,7 +7,7 @@ <title>Author</title> <para> This chapter originated as part of - <xref linkend="sim98">, Stefan Simkovics' + <xref linkend="sim98"/>, Stefan Simkovics' Master's Thesis prepared at Vienna University of Technology under the direction of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr. </para> @@ -136,7 +136,7 @@ <para> The client process can be any program that understands the <productname>PostgreSQL</productname> protocol described in - <xref linkend="protocol">. Many clients are based on the + <xref linkend="protocol"/>. Many clients are based on the C-language library <application>libpq</application>, but several independent implementations of the protocol exist, such as the Java <application>JDBC</application> driver. @@ -317,7 +317,7 @@ <para> The query rewriter is discussed in some detail in - <xref linkend="rules">, so there is no need to cover it here. + <xref linkend="rules"/>, so there is no need to cover it here. We will only point out that both the input and the output of the rewriter are query trees, that is, there is no change in the representation or level of semantic detail in the trees. Rewriting @@ -347,8 +347,8 @@ involving large numbers of join operations. In order to determine a reasonable (not necessarily optimal) query plan in a reasonable amount of time, <productname>PostgreSQL</productname> uses a <firstterm>Genetic - Query Optimizer</firstterm> (see <xref linkend="geqo">) when the number of joins - exceeds a threshold (see <xref linkend="guc-geqo-threshold">). + Query Optimizer</firstterm> (see <xref linkend="geqo"/>) when the number of joins + exceeds a threshold (see <xref linkend="guc-geqo-threshold"/>). </para> </note> @@ -438,7 +438,7 @@ </para> <para> - If the query uses fewer than <xref linkend="guc-geqo-threshold"> + If the query uses fewer than <xref linkend="guc-geqo-threshold"/> relations, a near-exhaustive search is conducted to find the best join sequence. The planner preferentially considers joins between any two relations for which there exist a corresponding join clause in the @@ -454,7 +454,7 @@ <para> When <varname>geqo_threshold</varname> is exceeded, the join sequences considered are determined by heuristics, as described - in <xref linkend="geqo">. Otherwise the process is the same. + in <xref linkend="geqo"/>. Otherwise the process is the same. </para> <para> diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index 9187f6e02e..f4d4a610ef 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -128,7 +128,7 @@ CREATE TABLE tictactoe ( <para> (These kinds of array constants are actually only a special case of the generic type constants discussed in <xref - linkend="sql-syntax-constants-generic">. The constant is initially + linkend="sql-syntax-constants-generic"/>. The constant is initially treated as a string and passed to the array input conversion routine. An explicit type specification might be necessary.) </para> @@ -192,7 +192,7 @@ INSERT INTO sal_emp expressions; for instance, string literals are single quoted, instead of double quoted as they would be in an array literal. The <literal>ARRAY</literal> constructor syntax is discussed in more detail in - <xref linkend="sql-syntax-array-constructors">. + <xref linkend="sql-syntax-array-constructors"/>. </para> </sect2> @@ -616,7 +616,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR However, this quickly becomes tedious for large arrays, and is not helpful if the size of the array is unknown. An alternative method is - described in <xref linkend="functions-comparisons">. The above + described in <xref linkend="functions-comparisons"/>. The above query could be replaced by: <programlisting> @@ -644,7 +644,7 @@ SELECT * FROM WHERE pay_by_quarter[s] = 10000; </programlisting> - This function is described in <xref linkend="functions-srf-subscripts">. + This function is described in <xref linkend="functions-srf-subscripts"/>. </para> <para> @@ -657,8 +657,8 @@ SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; </programlisting> This and other array operators are further described in - <xref linkend="functions-array">. It can be accelerated by an appropriate - index, as described in <xref linkend="indexes-types">. + <xref linkend="functions-array"/>. It can be accelerated by an appropriate + index, as described in <xref linkend="indexes-types"/>. </para> <para> @@ -755,7 +755,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 or backslashes disables this and allows the literal string value <quote>NULL</quote> to be entered. Also, for backward compatibility with pre-8.2 versions of <productname>PostgreSQL</productname>, the <xref - linkend="guc-array-nulls"> configuration parameter can be turned + linkend="guc-array-nulls"/> configuration parameter can be turned <literal>off</literal> to suppress recognition of <literal>NULL</literal> as a NULL. </para> @@ -797,7 +797,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}'); with a data type whose input routine also treated backslashes specially, <type>bytea</type> for example, we might need as many as eight backslashes in the command to get one backslash into the stored array element.) - Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be + Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting"/>) can be used to avoid the need to double backslashes. </para> </note> @@ -805,7 +805,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}'); <tip> <para> The <literal>ARRAY</literal> constructor syntax (see - <xref linkend="sql-syntax-array-constructors">) is often easier to work + <xref linkend="sql-syntax-array-constructors"/>) is often easier to work with than the array-literal syntax when writing array values in SQL commands. In <literal>ARRAY</literal>, individual element values are written the same way they would be written when not members of an array. diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 9221d2dfb6..bd3ef7128d 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -18,7 +18,7 @@ <para> In order to function, this module must be loaded via - <xref linkend="guc-shared-preload-libraries"> in <filename>postgresql.conf</filename>. + <xref linkend="guc-shared-preload-libraries"/> in <filename>postgresql.conf</filename>. </para> <sect2> diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index 240098c82f..08b67f2600 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -10,7 +10,7 @@ <para> The <filename>auto_explain</filename> module provides a means for logging execution plans of slow statements automatically, without - having to run <xref linkend="sql-explain"> + having to run <xref linkend="sql-explain"/> by hand. This is especially helpful for tracking down un-optimized queries in large applications. </para> @@ -25,8 +25,8 @@ LOAD 'auto_explain'; (You must be superuser to do that.) More typical usage is to preload it into some or all sessions by including <literal>auto_explain</literal> in - <xref linkend="guc-session-preload-libraries"> or - <xref linkend="guc-shared-preload-libraries"> in + <xref linkend="guc-session-preload-libraries"/> or + <xref linkend="guc-shared-preload-libraries"/> in <filename>postgresql.conf</filename>. Then you can track unexpectedly slow queries no matter when they happen. Of course there is a price in overhead for that. diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 39bb25c8e2..9d8e69056f 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -32,7 +32,7 @@ commands that, when fed back to the server, will recreate the database in the same state as it was at the time of the dump. <productname>PostgreSQL</productname> provides the utility program - <xref linkend="app-pgdump"> for this purpose. The basic usage of this + <xref linkend="app-pgdump"/> for this purpose. The basic usage of this command is: <synopsis> pg_dump <replaceable class="parameter">dbname</replaceable> > <replaceable class="parameter">outfile</replaceable> @@ -79,7 +79,7 @@ pg_dump <replaceable class="parameter">dbname</replaceable> > <replaceable cl environment variable <envar>PGUSER</envar>. Remember that <application>pg_dump</application> connections are subject to the normal client authentication mechanisms (which are described in <xref - linkend="client-authentication">). + linkend="client-authentication"/>). </para> <para> @@ -120,9 +120,9 @@ psql <replaceable class="parameter">dbname</replaceable> < <replaceable class class="parameter">dbname</replaceable></literal>). <application>psql</application> supports options similar to <application>pg_dump</application> for specifying the database server to connect to and the user name to use. See - the <xref linkend="app-psql"> reference page for more information. + the <xref linkend="app-psql"/> reference page for more information. Non-text file dumps are restored using the <xref - linkend="app-pgrestore"> utility. + linkend="app-pgrestore"/> utility. </para> <para> @@ -178,13 +178,13 @@ pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> | <para> After restoring a backup, it is wise to run <xref - linkend="sql-analyze"> on each + linkend="sql-analyze"/> on each database so the query optimizer has useful statistics; - see <xref linkend="vacuum-for-statistics"> - and <xref linkend="autovacuum"> for more information. + see <xref linkend="vacuum-for-statistics"/> + and <xref linkend="autovacuum"/> for more information. For more advice on how to load large amounts of data into <productname>PostgreSQL</productname> efficiently, refer to <xref - linkend="populate">. + linkend="populate"/>. </para> </sect2> @@ -196,7 +196,7 @@ pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> | and it does not dump information about roles or tablespaces (because those are cluster-wide rather than per-database). To support convenient dumping of the entire contents of a database - cluster, the <xref linkend="app-pg-dumpall"> program is provided. + cluster, the <xref linkend="app-pg-dumpall"/> program is provided. <application>pg_dumpall</application> backs up each database in a given cluster, and also preserves cluster-wide data such as role and tablespace definitions. The basic usage of this command is: @@ -308,8 +308,8 @@ pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceabl pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">filename</replaceable> </programlisting> - See the <xref linkend="app-pgdump"> and <xref - linkend="app-pgrestore"> reference pages for details. + See the <xref linkend="app-pgdump"/> and <xref + linkend="app-pgrestore"/> reference pages for details. </para> </formalpara> @@ -345,7 +345,7 @@ pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable <para> An alternative backup strategy is to directly copy the files that <productname>PostgreSQL</productname> uses to store the data in the database; - <xref linkend="creating-cluster"> explains where these files + <xref linkend="creating-cluster"/> explains where these files are located. You can use whatever method you prefer for doing file system backups; for example: @@ -369,7 +369,7 @@ tar -cf backup.tar /usr/local/pgsql/data an atomic snapshot of the state of the file system, but also because of internal buffering within the server). Information about stopping the server can be found in - <xref linkend="server-shutdown">. Needless to say, you + <xref linkend="server-shutdown"/>. Needless to say, you also need to shut down the server before restoring the data. </para> </listitem> @@ -428,10 +428,10 @@ tar -cf backup.tar /usr/local/pgsql/data If simultaneous snapshots are not possible, one option is to shut down the database server long enough to establish all the frozen snapshots. Another option is to perform a continuous archiving base backup (<xref - linkend="backup-base-backup">) because such backups are immune to file + linkend="backup-base-backup"/>) because such backups are immune to file system changes during the backup. This requires enabling continuous archiving just during the backup process; restore is done using - continuous archive recovery (<xref linkend="backup-pitr-recovery">). + continuous archive recovery (<xref linkend="backup-pitr-recovery"/>). </para> <para> @@ -591,11 +591,11 @@ tar -cf backup.tar /usr/local/pgsql/data </para> <para> - To enable WAL archiving, set the <xref linkend="guc-wal-level"> + To enable WAL archiving, set the <xref linkend="guc-wal-level"/> configuration parameter to <literal>replica</literal> or higher, - <xref linkend="guc-archive-mode"> to <literal>on</literal>, + <xref linkend="guc-archive-mode"/> to <literal>on</literal>, and specify the shell command to use in the <xref - linkend="guc-archive-command"> configuration parameter. In practice + linkend="guc-archive-command"/> configuration parameter. In practice these settings will always be placed in the <filename>postgresql.conf</filename> file. In <varname>archive_command</varname>, @@ -705,7 +705,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 than through SQL operations. You might wish to keep the configuration files in a location that will be backed up by your regular file system backup procedures. See - <xref linkend="runtime-config-file-locations"> for how to relocate the + <xref linkend="runtime-config-file-locations"/> for how to relocate the configuration files. </para> @@ -715,7 +715,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 where it does so), there could be a long delay between the completion of a transaction and its safe recording in archive storage. To put a limit on how old unarchived data can be, you can set - <xref linkend="guc-archive-timeout"> to force the server to switch + <xref linkend="guc-archive-timeout"/> to force the server to switch to a new WAL segment file at least that often. Note that archived files that are archived early due to a forced switch are still the same length as completely full files. It is therefore unwise to set a very @@ -729,13 +729,13 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 <function>pg_switch_wal</function> if you want to ensure that a just-finished transaction is archived as soon as possible. Other utility functions related to WAL management are listed in <xref - linkend="functions-admin-backup-table">. + linkend="functions-admin-backup-table"/>. </para> <para> When <varname>wal_level</varname> is <literal>minimal</literal> some SQL commands are optimized to avoid WAL logging, as described in <xref - linkend="populate-pitr">. If archiving or streaming replication were + linkend="populate-pitr"/>. If archiving or streaming replication were turned on during execution of one of these statements, WAL would not contain enough information for archive recovery. (Crash recovery is unaffected.) For this reason, <varname>wal_level</varname> can only be changed at @@ -753,11 +753,11 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 <para> The easiest way to perform a base backup is to use the - <xref linkend="app-pgbasebackup"> tool. It can create + <xref linkend="app-pgbasebackup"/> tool. It can create a base backup either as regular files or as a tar archive. If more - flexibility than <xref linkend="app-pgbasebackup"> can provide is + flexibility than <xref linkend="app-pgbasebackup"/> can provide is required, you can also make a base backup using the low level API - (see <xref linkend="backup-lowlevel-base-backup">). + (see <xref linkend="backup-lowlevel-base-backup"/>). </para> <para> @@ -791,7 +791,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 <para> The backup history file is just a small text file. It contains the - label string you gave to <xref linkend="app-pgbasebackup">, as well as + label string you gave to <xref linkend="app-pgbasebackup"/>, as well as the starting and ending times and WAL segments of the backup. If you used the label to identify the associated dump file, then the archived history file is enough to tell you which dump file to @@ -814,7 +814,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 <para> The procedure for making a base backup using the low level APIs contains a few more steps than - the <xref linkend="app-pgbasebackup"> method, but is relatively + the <xref linkend="app-pgbasebackup"/> method, but is relatively simple. It is very important that these steps are executed in sequence, and that the success of a step is verified before proceeding to the next step. @@ -830,7 +830,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 A non-exclusive low level backup is one that allows other concurrent backups to be running (both those started using the same backup API and those started using - <xref linkend="app-pgbasebackup">). + <xref linkend="app-pgbasebackup"/>). </para> <para> <orderedlist> @@ -859,7 +859,7 @@ SELECT pg_start_backup('label', false, false); required for the checkpoint will be spread out over a significant period of time, by default half your inter-checkpoint interval (see the configuration parameter - <xref linkend="guc-checkpoint-completion-target">). This is + <xref linkend="guc-checkpoint-completion-target"/>). This is usually what you want, because it minimizes the impact on query processing. If you want to start the backup as soon as possible, change the second parameter to <literal>true</literal>, which will @@ -879,7 +879,7 @@ SELECT pg_start_backup('label', false, false); <application>pg_dumpall</application>). It is neither necessary nor desirable to stop normal operation of the database while you do this. See - <xref linkend="backup-lowlevel-base-backup-data"> for things to + <xref linkend="backup-lowlevel-base-backup-data"/> for things to consider during this backup. </para> </listitem> @@ -989,7 +989,7 @@ SELECT pg_start_backup('label'); required for the checkpoint will be spread out over a significant period of time, by default half your inter-checkpoint interval (see the configuration parameter - <xref linkend="guc-checkpoint-completion-target">). This is + <xref linkend="guc-checkpoint-completion-target"/>). This is usually what you want, because it minimizes the impact on query processing. If you want to start the backup as soon as possible, use: @@ -1007,7 +1007,7 @@ SELECT pg_start_backup('label', true); <application>pg_dumpall</application>). It is neither necessary nor desirable to stop normal operation of the database while you do this. See - <xref linkend="backup-lowlevel-base-backup-data"> for things to + <xref linkend="backup-lowlevel-base-backup-data"/> for things to consider during this backup. </para> <para> @@ -1119,7 +1119,7 @@ SELECT pg_stop_backup(); <filename>pg_snapshots/</filename>, <filename>pg_stat_tmp/</filename>, and <filename>pg_subtrans/</filename> (but not the directories themselves) can be omitted from the backup as they will be initialized on postmaster startup. - If <xref linkend="guc-stats-temp-directory"> is set and is under the data + If <xref linkend="guc-stats-temp-directory"/> is set and is under the data directory then the contents of that directory can also be omitted. </para> @@ -1221,7 +1221,7 @@ SELECT pg_stop_backup(); <listitem> <para> Create a recovery command file <filename>recovery.conf</filename> in the cluster - data directory (see <xref linkend="recovery-config">). You might + data directory (see <xref linkend="recovery-config"/>). You might also want to temporarily modify <filename>pg_hba.conf</filename> to prevent ordinary users from connecting until you are sure the recovery was successful. </para> @@ -1310,7 +1310,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' at the start of recovery for a file named something like <filename>00000001.history</filename>. This is also normal and does not indicate a problem in simple recovery situations; see - <xref linkend="backup-timelines"> for discussion. + <xref linkend="backup-timelines"/> for discussion. </para> <para> @@ -1440,7 +1440,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' <para> As with base backups, the easiest way to produce a standalone - hot backup is to use the <xref linkend="app-pgbasebackup"> + hot backup is to use the <xref linkend="app-pgbasebackup"/> tool. If you include the <literal>-X</literal> parameter when calling it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is @@ -1548,7 +1548,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' <tip> <para> When using an <varname>archive_command</varname> script, it's desirable - to enable <xref linkend="guc-logging-collector">. + to enable <xref linkend="guc-logging-collector"/>. Any messages written to <systemitem>stderr</systemitem> from the script will then appear in the database server log, allowing complex configurations to be diagnosed easily if they fail. @@ -1567,7 +1567,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' <itemizedlist> <listitem> <para> - If a <xref linkend="sql-createdatabase"> + If a <xref linkend="sql-createdatabase"/> command is executed while a base backup is being taken, and then the template database that the <command>CREATE DATABASE</command> copied is modified while the base backup is still in progress, it is @@ -1580,7 +1580,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' <listitem> <para> - <xref linkend="sql-createtablespace"> + <xref linkend="sql-createtablespace"/> commands are WAL-logged with the literal absolute path, and will therefore be replayed as tablespace creations with the same absolute path. This might be undesirable if the log is being @@ -1603,8 +1603,8 @@ archive_command = 'local_backup_script.sh "%p" "%f"' your system hardware and software, the risk of partial writes might be small enough to ignore, in which case you can significantly reduce the total volume of archived logs by turning off page - snapshots using the <xref linkend="guc-full-page-writes"> - parameter. (Read the notes and warnings in <xref linkend="wal"> + snapshots using the <xref linkend="guc-full-page-writes"/> + parameter. (Read the notes and warnings in <xref linkend="wal"/> before you do so.) Turning off page snapshots does not prevent use of the logs for PITR operations. An area for future development is to compress archived WAL data by removing diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index 0b092f6e49..4bc2b696b3 100644 --- a/doc/src/sgml/bgworker.sgml +++ b/doc/src/sgml/bgworker.sgml @@ -286,6 +286,6 @@ typedef struct BackgroundWorker <para> The maximum number of registered background workers is limited by - <xref linkend="guc-max-worker-processes">. + <xref linkend="guc-max-worker-processes"/>. </para> </chapter> diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index b7483df4c0..23c0e05ed6 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -95,7 +95,7 @@ <para> The core <productname>PostgreSQL</productname> distribution includes the <acronym>BRIN</acronym> operator classes shown in - <xref linkend="brin-builtin-opclasses-table">. + <xref linkend="brin-builtin-opclasses-table"/>. </para> <para> @@ -590,7 +590,7 @@ typedef struct BrinOpcInfo To write an operator class for a data type that implements a totally ordered set, it is possible to use the minmax support procedures alongside the corresponding operators, as shown in - <xref linkend="brin-extensibility-minmax-table">. + <xref linkend="brin-extensibility-minmax-table"/>. All operator class members (procedures and operators) are mandatory. </para> @@ -648,7 +648,7 @@ typedef struct BrinOpcInfo To write an operator class for a complex data type which has values included within another type, it's possible to use the inclusion support procedures alongside the corresponding operators, as shown - in <xref linkend="brin-extensibility-inclusion-table">. It requires + in <xref linkend="brin-extensibility-inclusion-table"/>. It requires only a single additional function, which can be written in any language. More functions can be defined for additional functionality. All operators are optional. Some operators require other operators, as shown as @@ -821,7 +821,7 @@ typedef struct BrinOpcInfo additional data types to be supported by defining extra sets of operators. Inclusion operator class operator strategies are dependent on another operator strategy as shown in - <xref linkend="brin-extensibility-inclusion-table">, or the same + <xref linkend="brin-extensibility-inclusion-table"/>, or the same operator strategy as themselves. They require the dependency operator to be defined with the <literal>STORAGE</literal> data type as the left-hand-side argument and the other supported data type to be the diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index ef60a58631..da881a7737 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -27,7 +27,7 @@ <title>Overview</title> <para> - <xref linkend="catalog-table"> lists the system catalogs. + <xref linkend="catalog-table"/> lists the system catalogs. More detailed documentation of each catalog follows below. </para> @@ -567,8 +567,8 @@ <para> New aggregate functions are registered with the <xref - linkend="sql-createaggregate"> - command. See <xref linkend="xaggr"> for more information about + linkend="sql-createaggregate"/> + command. See <xref linkend="xaggr"/> for more information about writing aggregate functions and the meaning of the transition functions, etc. </para> @@ -588,7 +588,7 @@ relation access methods. There is one row for each access method supported by the system. Currently, only indexes have access methods. The requirements for index - access methods are discussed in detail in <xref linkend="indexam">. + access methods are discussed in detail in <xref linkend="indexam"/>. </para> <table> @@ -649,7 +649,7 @@ methods. That data is now only directly visible at the C code level. However, <function>pg_index_column_has_property()</function> and related functions have been added to allow SQL queries to inspect index access - method properties; see <xref linkend="functions-info-catalog-table">. + method properties; see <xref linkend="functions-info-catalog-table"/>. </para> </note> @@ -1034,7 +1034,7 @@ <entry> <structfield>attstattarget</structfield> controls the level of detail of statistics accumulated for this column by - <xref linkend="sql-analyze">. + <xref linkend="sql-analyze"/>. A zero value indicates that no statistics should be collected. A negative value says to use the system default statistics target. The exact meaning of positive values is data type-dependent. @@ -1270,7 +1270,7 @@ </para> <para> - <xref linkend="user-manag"> contains detailed information about user and + <xref linkend="user-manag"/> contains detailed information about user and privilege management. </para> @@ -1356,7 +1356,7 @@ <entry><type>bool</type></entry> <entry> Role bypasses every row level security policy, see - <xref linkend="ddl-rowsecurity"> for more information. + <xref linkend="ddl-rowsecurity"/> for more information. </entry> </row> @@ -1964,8 +1964,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -2015,7 +2015,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l The catalog <structname>pg_collation</structname> describes the available collations, which are essentially mappings from an SQL name to operating system locale categories. - See <xref linkend="collation"> for more information. + See <xref linkend="collation"/> for more information. </para> <table> @@ -2424,7 +2424,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_conversion</structname> describes - encoding conversion procedures. See <xref linkend="sql-createconversion"> + encoding conversion procedures. See <xref linkend="sql-createconversion"/> for more information. </para> @@ -2516,8 +2516,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_database</structname> stores information about the available databases. Databases are created with the <xref - linkend="sql-createdatabase"> command. - Consult <xref linkend="managing-databases"> for details about the meaning + linkend="sql-createdatabase"/> command. + Consult <xref linkend="managing-databases"/> for details about the meaning of some of the parameters. </para> @@ -2675,8 +2675,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -3053,7 +3053,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_description</structname> stores optional descriptions (comments) for each database object. Descriptions can be manipulated - with the <xref linkend="sql-comment"> command and viewed with + with the <xref linkend="sql-comment"/> command and viewed with <application>psql</application>'s <literal>\d</literal> commands. Descriptions of many built-in system objects are provided in the initial contents of <structname>pg_description</structname>. @@ -3208,7 +3208,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_event_trigger</structname> stores event triggers. - See <xref linkend="event-triggers"> for more information. + See <xref linkend="event-triggers"/> for more information. </para> <table> @@ -3258,7 +3258,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>char</type></entry> <entry></entry> <entry> - Controls in which <xref linkend="guc-session-replication-role"> modes + Controls in which <xref linkend="guc-session-replication-role"/> modes the event trigger fires. <literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>D</literal> = trigger is disabled, @@ -3291,7 +3291,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_extension</structname> stores information - about the installed extensions. See <xref linkend="extend-extensions"> + about the installed extensions. See <xref linkend="extend-extensions"/> for details about extensions. </para> @@ -3463,8 +3463,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -3559,8 +3559,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -4011,8 +4011,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> The initial access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -4034,8 +4034,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_language</structname> registers languages in which you can write functions or stored procedures. - See <xref linkend="sql-createlanguage"> - and <xref linkend="xplang"> for more information about language handlers. + See <xref linkend="sql-createlanguage"/> + and <xref linkend="xplang"/> for more information about language handlers. </para> <table> @@ -4117,7 +4117,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry> This references a function that is responsible for executing <quote>inline</quote> anonymous code blocks - (<xref linkend="sql-do"> blocks). + (<xref linkend="sql-do"/> blocks). Zero if inline blocks are not supported. </entry> </row> @@ -4139,8 +4139,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -4279,8 +4279,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -4346,8 +4346,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -4377,7 +4377,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - Operator classes are described at length in <xref linkend="xindex">. + Operator classes are described at length in <xref linkend="xindex"/>. </para> <table> @@ -4481,8 +4481,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_operator</structname> stores information about operators. - See <xref linkend="sql-createoperator"> - and <xref linkend="xoper"> for more information. + See <xref linkend="sql-createoperator"/> + and <xref linkend="xoper"/> for more information. </para> <table> @@ -4639,7 +4639,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - Operator families are described at length in <xref linkend="xindex">. + Operator families are described at length in <xref linkend="xindex"/>. </para> <table> @@ -5040,8 +5040,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_proc</structname> stores information about functions (or procedures). - See <xref linkend="sql-createfunction"> - and <xref linkend="xfunc"> for more information. + See <xref linkend="sql-createfunction"/> + and <xref linkend="xfunc"/> for more information. </para> <para> @@ -5106,7 +5106,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>float4</type></entry> <entry></entry> <entry>Estimated execution cost (in units of - <xref linkend="guc-cpu-operator-cost">); if <structfield>proretset</structfield>, + <xref linkend="guc-cpu-operator-cost"/>); if <structfield>proretset</structfield>, this is cost per row returned</entry> </row> @@ -5130,7 +5130,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>regproc</type></entry> <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> <entry>Calls to this function can be simplified by this other function - (see <xref linkend="xfunc-transform-functions">)</entry> + (see <xref linkend="xfunc-transform-functions"/>)</entry> </row> <row> @@ -5359,8 +5359,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -5390,7 +5390,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_publication</structname> contains all publications created in the database. For more on publications see - <xref linkend="logical-replication-publication">. + <xref linkend="logical-replication-publication"/>. </para> <table> @@ -5475,7 +5475,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_publication_rel</structname> contains the mapping between relations and publications in the database. This is a - many-to-many mapping. See also <xref linkend="view-pg-publication-tables"> + many-to-many mapping. See also <xref linkend="view-pg-publication-tables"/> for a more user-friendly view of this information. </para> @@ -5605,7 +5605,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The <structname>pg_replication_origin</structname> catalog contains all replication origins created. For more on replication origins - see <xref linkend="replication-origins">. + see <xref linkend="replication-origins"/>. </para> <table> @@ -5705,7 +5705,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>char</type></entry> <entry></entry> <entry> - Controls in which <xref linkend="guc-session-replication-role"> modes + Controls in which <xref linkend="guc-session-replication-role"/> modes the rule fires. <literal>O</literal> = rule fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>D</literal> = rule is disabled, @@ -5765,8 +5765,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_seclabel</structname> stores security labels on database objects. Security labels can be manipulated - with the <xref linkend="sql-security-label"> command. For an easier - way to view security labels, see <xref linkend="view-pg-seclabels">. + with the <xref linkend="sql-security-label"/> command. For an easier + way to view security labels, see <xref linkend="view-pg-seclabels"/>. </para> <para> @@ -6093,7 +6093,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_shdescription</structname> stores optional descriptions (comments) for shared database objects. Descriptions can be - manipulated with the <xref linkend="sql-comment"> command and viewed with + manipulated with the <xref linkend="sql-comment"/> command and viewed with <application>psql</application>'s <literal>\d</literal> commands. </para> @@ -6160,8 +6160,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_shseclabel</structname> stores security labels on shared database objects. Security labels can be manipulated - with the <xref linkend="sql-security-label"> command. For an easier - way to view security labels, see <xref linkend="view-pg-seclabels">. + with the <xref linkend="sql-security-label"/> command. For an easier + way to view security labels, see <xref linkend="view-pg-seclabels"/>. </para> <para> @@ -6228,7 +6228,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_statistic</structname> stores statistical data about the contents of the database. Entries are - created by <xref linkend="sql-analyze"> + created by <xref linkend="sql-analyze"/> and subsequently used by the query planner. Note that all the statistical data is inherently approximate, even assuming that it is up-to-date. @@ -6408,7 +6408,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l The catalog <structname>pg_statistic_ext</structname> holds extended planner statistics. Each row in this catalog corresponds to a <firstterm>statistics object</firstterm> - created with <xref linkend="sql-createstatistics">. + created with <xref linkend="sql-createstatistics"/>. </para> <table> @@ -6521,7 +6521,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_subscription</structname> contains all existing logical replication subscriptions. For more information about logical - replication see <xref linkend="logical-replication">. + replication see <xref linkend="logical-replication"/>. </para> <para> @@ -6616,7 +6616,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry>Array of subscribed publication names. These reference the publications on the publisher server. For more on publications - see <xref linkend="logical-replication-publication">. + see <xref linkend="logical-replication-publication"/>. </entry> </row> </tbody> @@ -6758,8 +6758,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -6788,7 +6788,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_transform</structname> stores information about transforms, which are a mechanism to adapt data types to procedural - languages. See <xref linkend="sql-createtransform"> for more information. + languages. See <xref linkend="sql-createtransform"/> for more information. </para> <table> @@ -6856,7 +6856,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_trigger</structname> stores triggers on tables and views. - See <xref linkend="sql-createtrigger"> + See <xref linkend="sql-createtrigger"/> for more information. </para> @@ -6914,7 +6914,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>char</type></entry> <entry></entry> <entry> - Controls in which <xref linkend="guc-session-replication-role"> modes + Controls in which <xref linkend="guc-session-replication-role"/> modes the trigger fires. <literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>D</literal> = trigger is disabled, @@ -7066,7 +7066,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> <productname>PostgreSQL</productname>'s text search features are - described at length in <xref linkend="textsearch">. + described at length in <xref linkend="textsearch"/>. </para> <table> @@ -7141,7 +7141,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> <productname>PostgreSQL</productname>'s text search features are - described at length in <xref linkend="textsearch">. + described at length in <xref linkend="textsearch"/>. </para> <table> @@ -7212,7 +7212,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> <productname>PostgreSQL</productname>'s text search features are - described at length in <xref linkend="textsearch">. + described at length in <xref linkend="textsearch"/>. </para> <table> @@ -7295,7 +7295,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> <productname>PostgreSQL</productname>'s text search features are - described at length in <xref linkend="textsearch">. + described at length in <xref linkend="textsearch"/>. </para> <table> @@ -7392,7 +7392,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> <productname>PostgreSQL</productname>'s text search features are - described at length in <xref linkend="textsearch">. + described at length in <xref linkend="textsearch"/>. </para> <table> @@ -7461,9 +7461,9 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The catalog <structname>pg_type</structname> stores information about data types. Base types and enum types (scalar types) are created with - <xref linkend="sql-createtype">, and + <xref linkend="sql-createtype"/>, and domains with - <xref linkend="sql-createdomain">. + <xref linkend="sql-createdomain"/>. A composite type is automatically created for each table in the database, to represent the row structure of the table. It is also possible to create composite types with <command>CREATE TYPE AS</command>. @@ -7567,7 +7567,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <structfield>typcategory</structfield> is an arbitrary classification of data types that is used by the parser to determine which implicit casts should be <quote>preferred</quote>. - See <xref linkend="catalog-typcategory-table">. + See <xref linkend="catalog-typcategory-table"/>. </entry> </row> @@ -7871,8 +7871,8 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry></entry> <entry> Access privileges; see - <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> + <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> for details </entry> </row> @@ -7881,7 +7881,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </table> <para> - <xref linkend="catalog-typcategory-table"> lists the system-defined values + <xref linkend="catalog-typcategory-table"/> lists the system-defined values of <structfield>typcategory</structfield>. Any future additions to this list will also be upper-case ASCII letters. All other ASCII characters are reserved for user-defined categories. @@ -8043,7 +8043,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - The information schema (<xref linkend="information-schema">) provides + The information schema (<xref linkend="information-schema"/>) provides an alternative set of views which overlap the functionality of the system views. Since the information schema is SQL-standard whereas the views described here are <productname>PostgreSQL</productname>-specific, @@ -8052,11 +8052,11 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - <xref linkend="view-table"> lists the system views described here. + <xref linkend="view-table"/> lists the system views described here. More detailed documentation of each view follows below. There are some additional views that provide access to the results of the statistics collector; they are described in <xref - linkend="monitoring-stats-views-table">. + linkend="monitoring-stats-views-table"/>. </para> <para> @@ -8389,7 +8389,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l be used by software packages that want to interface to <productname>PostgreSQL</productname> to facilitate finding the required header files and libraries. It provides the same basic information as the - <xref linkend="app-pgconfig"> <productname>PostgreSQL</productname> client + <xref linkend="app-pgconfig"/> <productname>PostgreSQL</productname> client application. </para> @@ -8440,7 +8440,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <itemizedlist> <listitem> <para> - via the <xref linkend="sql-declare"> + via the <xref linkend="sql-declare"/> statement in SQL </para> </listitem> @@ -8448,14 +8448,14 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <listitem> <para> via the Bind message in the frontend/backend protocol, as - described in <xref linkend="protocol-flow-ext-query"> + described in <xref linkend="protocol-flow-ext-query"/> </para> </listitem> <listitem> <para> via the Server Programming Interface (SPI), as described in - <xref linkend="spi-interface"> + <xref linkend="spi-interface"/> </para> </listitem> </itemizedlist> @@ -8648,7 +8648,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - See <xref linkend="config-setting"> for more information about the various + See <xref linkend="config-setting"/> for more information about the various ways to change run-time parameters. </para> @@ -8813,7 +8813,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l </para> <para> - See <xref linkend="client-authentication"> for more information about + See <xref linkend="client-authentication"/> for more information about client authentication configuration. </para> </sect1> @@ -8890,7 +8890,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <para> The view <structname>pg_locks</structname> provides access to information about the locks held by active processes within the - database server. See <xref linkend="mvcc"> for more discussion + database server. See <xref linkend="mvcc"/> for more discussion of locking. </para> @@ -9053,7 +9053,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l <entry><type>text</type></entry> <entry></entry> <entry>Name of the lock mode held or desired by this process (see <xref - linkend="locking-tables"> and <xref linkend="xact-serializable">)</entry> + linkend="locking-tables"/> and <xref linkend="xact-serializable"/>)</entry> </row> <row> <entry><structfield>granted</structfield></entry> @@ -9164,7 +9164,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx queues, nor information about which processes are parallel workers running on behalf of which other client sessions. It is better to use the <function>pg_blocking_pids()</function> function - (see <xref linkend="functions-info-session-table">) to identify which + (see <xref linkend="functions-info-session-table"/>) to identify which process(es) a waiting process is blocked behind. </para> @@ -9369,7 +9369,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <para> The <structname>pg_prepared_statements</structname> view displays all the prepared statements that are available in the current - session. See <xref linkend="sql-prepare"> for more information about prepared + session. See <xref linkend="sql-prepare"/> for more information about prepared statements. </para> @@ -9377,7 +9377,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <structname>pg_prepared_statements</structname> contains one row for each prepared statement. Rows are added to the view when a new prepared statement is created and removed when a prepared statement - is released (for example, via the <xref linkend="sql-deallocate"> command). + is released (for example, via the <xref linkend="sql-deallocate"/> command). </para> <table> @@ -9457,7 +9457,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <para> The view <structname>pg_prepared_xacts</structname> displays information about transactions that are currently prepared for two-phase - commit (see <xref linkend="sql-prepare-transaction"> for details). + commit (see <xref linkend="sql-prepare-transaction"/> for details). </para> <para> @@ -9601,7 +9601,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The <structname>pg_replication_origin_status</structname> view contains information about how far replay for a certain origin has progressed. For more on replication origins - see <xref linkend="replication-origins">. + see <xref linkend="replication-origins"/>. </para> <table> @@ -9670,7 +9670,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <para> For more on replication slots, - see <xref linkend="streaming-replication-slots"> and <xref linkend="logicaldecoding">. + see <xref linkend="streaming-replication-slots"/> and <xref linkend="logicaldecoding"/>. </para> <table> @@ -9917,7 +9917,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry></entry> <entry> Role bypasses every row level security policy, see - <xref linkend="ddl-rowsecurity"> for more information. + <xref linkend="ddl-rowsecurity"/> for more information. </entry> </row> @@ -10203,8 +10203,8 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <para> The view <structname>pg_settings</structname> provides access to run-time parameters of the server. It is essentially an alternative - interface to the <xref linkend="sql-show"> - and <xref linkend="sql-set"> commands. + interface to the <xref linkend="sql-show"/> + and <xref linkend="sql-set"/> commands. It also provides access to some facts about each parameter that are not directly available from <command>SHOW</command>, such as minimum and maximum values. @@ -10441,7 +10441,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx </variablelist> <para> - See <xref linkend="config-setting"> for more information about the various + See <xref linkend="config-setting"/> for more information about the various ways to change these parameters. </para> @@ -10449,7 +10449,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The <structname>pg_settings</structname> view cannot be inserted into or deleted from, but it can be updated. An <command>UPDATE</command> applied to a row of <structname>pg_settings</structname> is equivalent to executing - the <xref linkend="sql-set"> command on that named + the <xref linkend="sql-set"/> command on that named parameter. The change only affects the value used by the current session. If an <command>UPDATE</command> is issued within a transaction that is later aborted, the effects of the <command>UPDATE</command> command @@ -10543,7 +10543,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry></entry> <entry> User bypasses every row level security policy, see - <xref linkend="ddl-rowsecurity"> for more information. + <xref linkend="ddl-rowsecurity"/> for more information. </entry> </row> @@ -10763,7 +10763,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The maximum number of entries in the array fields can be controlled on a column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command> command, or globally by setting the - <xref linkend="guc-default-statistics-target"> run-time parameter. + <xref linkend="guc-default-statistics-target"/> run-time parameter. </para> </sect1> @@ -10858,7 +10858,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The view <structname>pg_timezone_abbrevs</structname> provides a list of time zone abbreviations that are currently recognized by the datetime input routines. The contents of this view change when the - <xref linkend="guc-timezone-abbreviations"> run-time parameter is modified. + <xref linkend="guc-timezone-abbreviations"/> run-time parameter is modified. </para> <table> @@ -10895,7 +10895,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <para> While most timezone abbreviations represent fixed offsets from UTC, there are some that have historically varied in value - (see <xref linkend="datetime-config-files"> for more information). + (see <xref linkend="datetime-config-files"/> for more information). In such cases this view presents their current meaning. </para> @@ -11025,7 +11025,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry><type>bool</type></entry> <entry> User bypasses every row level security policy, see - <xref linkend="ddl-rowsecurity"> for more information. + <xref linkend="ddl-rowsecurity"/> for more information. </entry> </row> diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index ce395e115a..dc3fd34a62 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -15,8 +15,8 @@ Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. - This is covered in <xref linkend="locale"> and - <xref linkend="collation">. + This is covered in <xref linkend="locale"/> and + <xref linkend="collation"/>. </para> </listitem> @@ -25,7 +25,7 @@ Providing a number of different character sets to support storing text in all kinds of languages, and providing character set translation between client and server. - This is covered in <xref linkend="multibyte">. + This is covered in <xref linkend="multibyte"/>. </para> </listitem> </itemizedlist> @@ -146,7 +146,7 @@ initdb --locale=sv_SE the sort order of indexes, so they must be kept fixed, or indexes on text columns would become corrupt. (But you can alleviate this restriction using collations, as discussed - in <xref linkend="collation">.) + in <xref linkend="collation"/>.) The default values for these categories are determined when <command>initdb</command> is run, and those values are used when new databases are created, unless @@ -157,7 +157,7 @@ initdb --locale=sv_SE The other locale categories can be changed whenever desired by setting the server configuration parameters that have the same name as the locale categories (see <xref - linkend="runtime-config-client-format"> for details). The values + linkend="runtime-config-client-format"/> for details). The values that are chosen by <command>initdb</command> are actually only written into the configuration file <filename>postgresql.conf</filename> to serve as defaults when the server is started. If you remove these @@ -267,10 +267,10 @@ initdb --locale=sv_SE with <literal>LIKE</literal> clauses under a non-C locale, several custom operator classes exist. These allow the creation of an index that performs a strict character-by-character comparison, ignoring - locale comparison rules. Refer to <xref linkend="indexes-opclass"> + locale comparison rules. Refer to <xref linkend="indexes-opclass"/> for more information. Another approach is to create indexes using the <literal>C</literal> collation, as discussed in - <xref linkend="collation">. + <xref linkend="collation"/>. </para> </sect2> @@ -316,7 +316,7 @@ initdb --locale=sv_SE <productname>PostgreSQL</productname> speak their preferred language well. If messages in your language are currently not available or not fully translated, your assistance would be appreciated. If you want to - help, refer to <xref linkend="nls"> or write to the developers' + help, refer to <xref linkend="nls"/> or write to the developers' mailing list. </para> </sect2> @@ -524,7 +524,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; these under one concept than to create another infrastructure for setting <symbol>LC_CTYPE</symbol> per expression.) Also, a <literal>libc</literal> collation - is tied to a character set encoding (see <xref linkend="multibyte">). + is tied to a character set encoding (see <xref linkend="multibyte"/>). The same collation name may exist for different encodings. </para> @@ -605,7 +605,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; for <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, or if new locales are installed in the operating system after the database system was initialized, then a new collation may be created using - the <xref linkend="sql-createcollation"> command. + the <xref linkend="sql-createcollation"/> command. New operating system locales can also be imported en masse using the <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link> function. </para> @@ -702,7 +702,7 @@ SELECT a COLLATE "C" < b COLLATE "POSIX" FROM test1; <para> If the standard and predefined collations are not sufficient, users can create their own collation objects using the SQL - command <xref linkend="sql-createcollation">. + command <xref linkend="sql-createcollation"/>. </para> <para> @@ -730,7 +730,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE'); defined in the operating system when the database instance is initialized, it is not often necessary to manually create new ones. Reasons might be if a different naming system is desired (in which case - see also <xref linkend="collation-copy">) or if the operating system has + see also <xref linkend="collation-copy"/>) or if the operating system has been upgraded to provide new locale definitions (in which case see also <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link>). </para> @@ -871,7 +871,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE'); <title>Copying Collations</title> <para> - The command <xref linkend="sql-createcollation"> can also be used to + The command <xref linkend="sql-createcollation"/> can also be used to create a new collation from an existing collation, which can be useful to be able to use operating-system-independent collation names in applications, create compatibility names, or use an ICU-provided collation @@ -924,7 +924,7 @@ CREATE COLLATION french FROM "fr-x-icu"; <title>Supported Character Sets</title> <para> - <xref linkend="charset-table"> shows the character sets available + <xref linkend="charset-table"/> shows the character sets available for use in <productname>PostgreSQL</productname>. </para> @@ -1392,7 +1392,7 @@ CREATE DATABASE korean WITH ENCODING 'EUC_KR' LC_COLLATE='ko_KR.euckr' LC_CTYPE= database. When copying any other database, the encoding and locale settings cannot be changed from those of the source database, because that might result in corrupt data. For more information see - <xref linkend="manage-ag-templatedbs">. + <xref linkend="manage-ag-templatedbs"/>. </para> <para> @@ -1449,7 +1449,7 @@ $ <userinput>psql -l</userinput> character set combinations. The conversion information is stored in the <literal>pg_conversion</literal> system catalog. <productname>PostgreSQL</productname> comes with some predefined conversions, as shown in <xref - linkend="multibyte-translation-table">. You can create a new + linkend="multibyte-translation-table"/>. You can create a new conversion using the SQL command <command>CREATE CONVERSION</command>. </para> @@ -1763,7 +1763,7 @@ $ <userinput>psql -l</userinput> <listitem> <para> - <application>libpq</application> (<xref linkend="libpq-control">) has functions to control the client encoding. + <application>libpq</application> (<xref linkend="libpq-control"/>) has functions to control the client encoding. </para> </listitem> @@ -1812,7 +1812,7 @@ RESET client_encoding; <listitem> <para> Using the configuration variable <xref - linkend="guc-client-encoding">. If the + linkend="guc-client-encoding"/>. If the <varname>client_encoding</varname> variable is set, that client encoding is automatically selected when a connection to the server is made. (This can subsequently be overridden using any diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 99921ba079..c8a1bc79aa 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -13,13 +13,13 @@ wants to connect as, much the same way one logs into a Unix computer as a particular user. Within the SQL environment the active database user name determines access privileges to database objects — see - <xref linkend="user-manag"> for more information. Therefore, it is + <xref linkend="user-manag"/> for more information. Therefore, it is essential to restrict which database users can connect. </para> <note> <para> - As explained in <xref linkend="user-manag">, + As explained in <xref linkend="user-manag"/>, <productname>PostgreSQL</productname> actually does privilege management in terms of <quote>roles</quote>. In this chapter, we consistently use <firstterm>database user</firstterm> to mean <quote>role with the @@ -70,7 +70,7 @@ <filename>pg_hba.conf</filename> file is installed when the data directory is initialized by <command>initdb</command>. It is possible to place the authentication configuration file elsewhere, - however; see the <xref linkend="guc-hba-file"> configuration parameter. + however; see the <xref linkend="guc-hba-file"/> configuration parameter. </para> <para> @@ -136,7 +136,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Remote TCP/IP connections will not be possible unless the server is started with an appropriate value for the - <xref linkend="guc-listen-addresses"> configuration parameter, + <xref linkend="guc-listen-addresses"/> configuration parameter, since the default behavior is to listen for TCP/IP connections only on the local loopback address <literal>localhost</literal>. </para> @@ -157,8 +157,8 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> To make use of this option the server must be built with <acronym>SSL</acronym> support. Furthermore, <acronym>SSL</acronym> must be enabled - by setting the <xref linkend="guc-ssl"> configuration parameter (see - <xref linkend="ssl-tcp"> for more information). + by setting the <xref linkend="guc-ssl"/> configuration parameter (see + <xref linkend="ssl-tcp"/> for more information). Otherwise, the <literal>hostssl</literal> record is ignored except for logging a warning that it cannot match any connections. </para> @@ -381,7 +381,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Specifies the authentication method to use when a connection matches this record. The possible choices are summarized here; details - are in <xref linkend="auth-methods">. + are in <xref linkend="auth-methods"/>. <variablelist> <varlistentry> @@ -393,7 +393,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <productname>PostgreSQL</productname> database server to login as any <productname>PostgreSQL</productname> user they wish, without the need for a password or any other authentication. See <xref - linkend="auth-trust"> for details. + linkend="auth-trust"/> for details. </para> </listitem> </varlistentry> @@ -416,7 +416,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Perform SCRAM-SHA-256 authentication to verify the user's - password. See <xref linkend="auth-password"> for details. + password. See <xref linkend="auth-password"/> for details. </para> </listitem> </varlistentry> @@ -426,7 +426,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Perform SCRAM-SHA-256 or MD5 authentication to verify the - user's password. See <xref linkend="auth-password"> + user's password. See <xref linkend="auth-password"/> for details. </para> </listitem> @@ -440,7 +440,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> authentication. Since the password is sent in clear text over the network, this should not be used on untrusted networks. - See <xref linkend="auth-password"> for details. + See <xref linkend="auth-password"/> for details. </para> </listitem> </varlistentry> @@ -451,7 +451,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Use GSSAPI to authenticate the user. This is only available for TCP/IP connections. See <xref - linkend="gssapi-auth"> for details. + linkend="gssapi-auth"/> for details. </para> </listitem> </varlistentry> @@ -462,7 +462,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Use SSPI to authenticate the user. This is only available on Windows. See <xref - linkend="sspi-auth"> for details. + linkend="sspi-auth"/> for details. </para> </listitem> </varlistentry> @@ -477,7 +477,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> Ident authentication can only be used on TCP/IP connections. When specified for local connections, peer authentication will be used instead. - See <xref linkend="auth-ident"> for details. + See <xref linkend="auth-ident"/> for details. </para> </listitem> </varlistentry> @@ -489,7 +489,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> Obtain the client's operating system user name from the operating system and check if it matches the requested database user name. This is only available for local connections. - See <xref linkend="auth-peer"> for details. + See <xref linkend="auth-peer"/> for details. </para> </listitem> </varlistentry> @@ -499,7 +499,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Authenticate using an <acronym>LDAP</acronym> server. See <xref - linkend="auth-ldap"> for details. + linkend="auth-ldap"/> for details. </para> </listitem> </varlistentry> @@ -509,7 +509,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Authenticate using a RADIUS server. See <xref - linkend="auth-radius"> for details. + linkend="auth-radius"/> for details. </para> </listitem> </varlistentry> @@ -519,7 +519,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Authenticate using SSL client certificates. See - <xref linkend="auth-cert"> for details. + <xref linkend="auth-cert"/> for details. </para> </listitem> </varlistentry> @@ -530,7 +530,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Authenticate using the Pluggable Authentication Modules (PAM) service provided by the operating system. See <xref - linkend="auth-pam"> for details. + linkend="auth-pam"/> for details. </para> </listitem> </varlistentry> @@ -540,7 +540,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <listitem> <para> Authenticate using the BSD Authentication service provided by the - operating system. See <xref linkend="auth-bsd"> for details. + operating system. See <xref linkend="auth-bsd"/> for details. </para> </listitem> </varlistentry> @@ -638,7 +638,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> Some examples of <filename>pg_hba.conf</filename> entries are shown in - <xref linkend="example-pg-hba.conf">. See the next section for details on the + <xref linkend="example-pg-hba.conf"/>. See the next section for details on the different authentication methods. </para> @@ -763,7 +763,7 @@ local db1,db2,@demodbs all md5 <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm> and is stored in the cluster's data directory. (It is possible to place the map file - elsewhere, however; see the <xref linkend="guc-ident-file"> + elsewhere, however; see the <xref linkend="guc-ident-file"/> configuration parameter.) The ident map file contains lines of the general form: <synopsis> @@ -790,7 +790,7 @@ local db1,db2,@demodbs all md5 <para> If the <replaceable>system-username</replaceable> field starts with a slash (<literal>/</literal>), the remainder of the field is treated as a regular expression. - (See <xref linkend="posix-syntax-details"> for details of + (See <xref linkend="posix-syntax-details"/> for details of <productname>PostgreSQL</productname>'s regular expression syntax.) The regular expression can include a single capture, or parenthesized subexpression, which can then be referenced in the <replaceable>database-username</replaceable> @@ -828,8 +828,8 @@ mymap /^(.*)@otherdomain\.com$ guest <para> A <filename>pg_ident.conf</filename> file that could be used in conjunction with the <filename>pg_hba.conf</filename> file in <xref - linkend="example-pg-hba.conf"> is shown in <xref - linkend="example-pg-ident.conf">. In this example, anyone + linkend="example-pg-hba.conf"/> is shown in <xref + linkend="example-pg-ident.conf"/>. In this example, anyone logged in to a machine on the 192.168 network that does not have the operating system user name <literal>bryanh</literal>, <literal>ann</literal>, or <literal>robert</literal> would not be granted access. Unix user @@ -885,7 +885,7 @@ omicron bryanh guest1 Unix-domain socket file using file-system permissions. To do this, set the <varname>unix_socket_permissions</varname> (and possibly <varname>unix_socket_group</varname>) configuration parameters as - described in <xref linkend="runtime-config-connection">. Or you + described in <xref linkend="runtime-config-connection"/>. Or you could set the <varname>unix_socket_directories</varname> configuration parameter to place the socket file in a suitably restricted directory. @@ -965,7 +965,7 @@ omicron bryanh guest1 <para> The <literal>md5</literal> method cannot be used with - the <xref linkend="guc-db-user-namespace"> feature. + the <xref linkend="guc-db-user-namespace"/> feature. </para> <para> @@ -998,8 +998,8 @@ omicron bryanh guest1 separate from operating system user passwords. The password for each database user is stored in the <literal>pg_authid</literal> system catalog. Passwords can be managed with the SQL commands - <xref linkend="sql-createrole"> and - <xref linkend="sql-alterrole">, + <xref linkend="sql-createrole"/> and + <xref linkend="sql-alterrole"/>, e.g., <userinput>CREATE ROLE foo WITH LOGIN PASSWORD 'secret'</userinput>, or the <application>psql</application> command <literal>\password</literal>. @@ -1011,7 +1011,7 @@ omicron bryanh guest1 The availability of the different password-based authentication methods depends on how a user's password on the server is encrypted (or hashed, more accurately). This is controlled by the configuration - parameter <xref linkend="guc-password-encryption"> at the time the + parameter <xref linkend="guc-password-encryption"/> at the time the password is set. If a password was encrypted using the <literal>scram-sha-256</literal> setting, then it can be used for the authentication methods <literal>scram-sha-256</literal> @@ -1061,7 +1061,7 @@ omicron bryanh guest1 <para> GSSAPI support has to be enabled when <productname>PostgreSQL</productname> is built; - see <xref linkend="installation"> for more information. + see <xref linkend="installation"/> for more information. </para> <para> @@ -1072,7 +1072,7 @@ omicron bryanh guest1 The PostgreSQL server will accept any principal that is included in the keytab used by the server, but care needs to be taken to specify the correct principal details when making the connection from the client using the <literal>krbsrvname</literal> connection parameter. (See - also <xref linkend="libpq-paramkeywords">.) The installation default can be + also <xref linkend="libpq-paramkeywords"/>.) The installation default can be changed from the default <literal>postgres</literal> at build time using <literal>./configure --with-krb-srvnam=</literal><replaceable>whatever</replaceable>. In most environments, @@ -1112,9 +1112,9 @@ omicron bryanh guest1 <para> Make sure that your server keytab file is readable (and preferably only readable, not writable) by the <productname>PostgreSQL</productname> - server account. (See also <xref linkend="postgres-user">.) The location + server account. (See also <xref linkend="postgres-user"/>.) The location of the key file is specified by the <xref - linkend="guc-krb-server-keyfile"> configuration + linkend="guc-krb-server-keyfile"/> configuration parameter. The default is <filename>/usr/local/pgsql/etc/krb5.keytab</filename> (or whatever directory was specified as <varname>sysconfdir</varname> at build time). @@ -1138,7 +1138,7 @@ omicron bryanh guest1 database user name <literal>fred</literal>, principal <literal>[email protected]</literal> would be able to connect. To also allow principal <literal>fred/[email protected]</literal>, use a user name - map, as described in <xref linkend="auth-username-maps">. + map, as described in <xref linkend="auth-username-maps"/>. </para> <para> @@ -1150,7 +1150,7 @@ omicron bryanh guest1 <para> If set to 0, the realm name from the authenticated user principal is stripped off before being passed through the user name mapping - (<xref linkend="auth-username-maps">). This is discouraged and is + (<xref linkend="auth-username-maps"/>). This is discouraged and is primarily available for backwards compatibility, as it is not secure in multi-realm environments unless <literal>krb_realm</literal> is also used. It is recommended to @@ -1166,7 +1166,7 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos + <xref linkend="auth-username-maps"/> for details. For a GSSAPI/Kerberos principal, such as <literal>[email protected]</literal> (or, less commonly, <literal>username/[email protected]</literal>), the user name used for mapping is @@ -1217,7 +1217,7 @@ omicron bryanh guest1 <para> When using <productname>Kerberos</productname> authentication, <productname>SSPI</productname> works the same way - <productname>GSSAPI</productname> does; see <xref linkend="gssapi-auth"> + <productname>GSSAPI</productname> does; see <xref linkend="gssapi-auth"/> for details. </para> @@ -1231,7 +1231,7 @@ omicron bryanh guest1 <para> If set to 0, the realm name from the authenticated user principal is stripped off before being passed through the user name mapping - (<xref linkend="auth-username-maps">). This is discouraged and is + (<xref linkend="auth-username-maps"/>). This is discouraged and is primarily available for backwards compatibility, as it is not secure in multi-realm environments unless <literal>krb_realm</literal> is also used. It is recommended to @@ -1284,7 +1284,7 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos + <xref linkend="auth-username-maps"/> for details. For a SSPI/Kerberos principal, such as <literal>[email protected]</literal> (or, less commonly, <literal>username/[email protected]</literal>), the user name used for mapping is @@ -1329,7 +1329,7 @@ omicron bryanh guest1 <note> <para> When ident is specified for a local (non-TCP/IP) connection, - peer authentication (see <xref linkend="auth-peer">) will be + peer authentication (see <xref linkend="auth-peer"/>) will be used instead. </para> </note> @@ -1342,7 +1342,7 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. + <xref linkend="auth-username-maps"/> for details. </para> </listitem> </varlistentry> @@ -1415,7 +1415,7 @@ omicron bryanh guest1 <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. + <xref linkend="auth-username-maps"/> for details. </para> </listitem> </varlistentry> @@ -1828,7 +1828,7 @@ host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse <listitem> <para> Allows for mapping between system and database user names. See - <xref linkend="auth-username-maps"> for details. + <xref linkend="auth-username-maps"/> for details. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 7059dd4e5f..3060597011 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -170,7 +170,7 @@ shared_buffers = 128MB <filename>postgresql.auto.conf</filename><indexterm><primary>postgresql.auto.conf</primary></indexterm>, which has the same format as <filename>postgresql.conf</filename> but should never be edited manually. This file holds settings provided through - the <xref linkend="sql-altersystem"> command. This file is automatically + the <xref linkend="sql-altersystem"/> command. This file is automatically read whenever <filename>postgresql.conf</filename> is, and its settings take effect in the same way. Settings in <filename>postgresql.auto.conf</filename> override those in <filename>postgresql.conf</filename>. @@ -191,7 +191,7 @@ shared_buffers = 128MB <para> <productname>PostgreSQL</productname> provides three SQL commands to establish configuration defaults. - The already-mentioned <xref linkend="sql-altersystem"> command + The already-mentioned <xref linkend="sql-altersystem"/> command provides a SQL-accessible means of changing global defaults; it is functionally equivalent to editing <filename>postgresql.conf</filename>. In addition, there are two commands that allow setting of defaults @@ -201,14 +201,14 @@ shared_buffers = 128MB <itemizedlist> <listitem> <para> - The <xref linkend="sql-alterdatabase"> command allows global + The <xref linkend="sql-alterdatabase"/> command allows global settings to be overridden on a per-database basis. </para> </listitem> <listitem> <para> - The <xref linkend="sql-alterrole"> command allows both global and + The <xref linkend="sql-alterrole"/> command allows both global and per-database settings to be overridden with user-specific values. </para> </listitem> @@ -232,7 +232,7 @@ shared_buffers = 128MB <itemizedlist> <listitem> <para> - The <xref linkend="sql-show"> command allows inspection of the + The <xref linkend="sql-show"/> command allows inspection of the current value of all parameters. The corresponding function is <function>current_setting(setting_name text)</function>. </para> @@ -240,7 +240,7 @@ shared_buffers = 128MB <listitem> <para> - The <xref linkend="sql-set"> command allows modification of the + The <xref linkend="sql-set"/> command allows modification of the current value of those parameters that can be set locally to a session; it has no effect on other sessions. The corresponding function is @@ -266,7 +266,7 @@ shared_buffers = 128MB <listitem> <para> - Using <xref linkend="sql-update"> on this view, specifically + Using <xref linkend="sql-update"/> on this view, specifically updating the <structname>setting</structname> column, is the equivalent of issuing <command>SET</command> commands. For example, the equivalent of <programlisting> @@ -470,7 +470,7 @@ include_dir 'conf.d' already mentioned, <productname>PostgreSQL</productname> uses two other manually-edited configuration files, which control client authentication (their use is discussed in <xref - linkend="client-authentication">). By default, all three + linkend="client-authentication"/>). By default, all three configuration files are stored in the database cluster's data directory. The parameters described in this section allow the configuration files to be placed elsewhere. (Doing so can ease @@ -535,7 +535,7 @@ include_dir 'conf.d' Specifies the configuration file for user name mapping (customarily called <filename>pg_ident.conf</filename>). This parameter can only be set at server start. - See also <xref linkend="auth-username-maps">. + See also <xref linkend="auth-username-maps"/>. </para> </listitem> </varlistentry> @@ -625,7 +625,7 @@ include_dir 'conf.d' The default value is <systemitem class="systemname">localhost</systemitem>, which allows only local TCP/IP <quote>loopback</quote> connections to be made. While client authentication (<xref - linkend="client-authentication">) allows fine-grained control + linkend="client-authentication"/>) allows fine-grained control over who can access the server, <varname>listen_addresses</varname> controls which interfaces accept connection attempts, which can help prevent repeated malicious connection requests on @@ -685,7 +685,7 @@ include_dir 'conf.d' <para> Determines the number of connection <quote>slots</quote> that are reserved for connections by <productname>PostgreSQL</productname> - superusers. At most <xref linkend="guc-max-connections"> + superusers. At most <xref linkend="guc-max-connections"/> connections can ever be active simultaneously. Whenever the number of active concurrent connections is at least <varname>max_connections</varname> minus @@ -794,7 +794,7 @@ include_dir 'conf.d' <para> This access control mechanism is independent of the one - described in <xref linkend="client-authentication">. + described in <xref linkend="client-authentication"/>. </para> <para> @@ -959,7 +959,7 @@ include_dir 'conf.d' <listitem> <para> Enables <acronym>SSL</acronym> connections. Please read - <xref linkend="ssl-tcp"> before using this. + <xref linkend="ssl-tcp"/> before using this. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. The default is <literal>off</literal>. @@ -1180,8 +1180,8 @@ include_dir 'conf.d' </term> <listitem> <para> - When a password is specified in <xref linkend="sql-createrole"> or - <xref linkend="sql-alterrole">, this parameter determines the algorithm + When a password is specified in <xref linkend="sql-createrole"/> or + <xref linkend="sql-alterrole"/>, this parameter determines the algorithm to use to encrypt the password. The default value is <literal>md5</literal>, which stores the password as an MD5 hash (<literal>on</literal> is also accepted, as alias for <literal>md5</literal>). Setting this parameter to @@ -1190,7 +1190,7 @@ include_dir 'conf.d' <para> Note that older clients might lack support for the SCRAM authentication mechanism, and hence not work with passwords encrypted with - SCRAM-SHA-256. See <xref linkend="auth-password"> for more details. + SCRAM-SHA-256. See <xref linkend="auth-password"/> for more details. </para> </listitem> </varlistentry> @@ -1228,7 +1228,7 @@ include_dir 'conf.d' <listitem> <para> Sets the location of the Kerberos server key file. See - <xref linkend="gssapi-auth"> + <xref linkend="gssapi-auth"/> for details. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. </para> @@ -1376,7 +1376,7 @@ include_dir 'conf.d' <para> The use of huge pages results in smaller page tables and less CPU time spent on memory management, increasing performance. For more details, - see <xref linkend="linux-huge-pages">. + see <xref linkend="linux-huge-pages"/>. </para> <para> @@ -1428,7 +1428,7 @@ include_dir 'conf.d' <para> Sets the maximum number of transactions that can be in the <quote>prepared</quote> state simultaneously (see <xref - linkend="sql-prepare-transaction">). + linkend="sql-prepare-transaction"/>). Setting this parameter to zero (which is the default) disables the prepared-transaction feature. This parameter can only be set at server start. @@ -1439,7 +1439,7 @@ include_dir 'conf.d' should be set to zero to prevent accidental creation of prepared transactions. If you are using prepared transactions, you will probably want <varname>max_prepared_transactions</varname> to be at - least as large as <xref linkend="guc-max-connections">, so that every + least as large as <xref linkend="guc-max-connections"/>, so that every session can have a prepared transaction pending. </para> @@ -1497,10 +1497,10 @@ include_dir 'conf.d' </para> <para> Note that when autovacuum runs, up to - <xref linkend="guc-autovacuum-max-workers"> times this memory + <xref linkend="guc-autovacuum-max-workers"/> times this memory may be allocated, so be careful not to set the default value too high. It may be useful to control for this by separately - setting <xref linkend="guc-autovacuum-work-mem">. + setting <xref linkend="guc-autovacuum-work-mem"/>. </para> </listitem> </varlistentry> @@ -1515,7 +1515,7 @@ include_dir 'conf.d' <para> Specifies the maximum amount of memory to be used by each autovacuum worker process. It defaults to -1, indicating that - the value of <xref linkend="guc-maintenance-work-mem"> should + the value of <xref linkend="guc-maintenance-work-mem"/> should be used instead. The setting has no effect on the behavior of <command>VACUUM</command> when run in other contexts. </para> @@ -1649,8 +1649,8 @@ include_dir 'conf.d' <title>Cost-based Vacuum Delay</title> <para> - During the execution of <xref linkend="sql-vacuum"> - and <xref linkend="sql-analyze"> + During the execution of <xref linkend="sql-vacuum"/> + and <xref linkend="sql-analyze"/> commands, the system maintains an internal counter that keeps track of the estimated cost of the various I/O operations that are performed. When the accumulated @@ -1893,7 +1893,7 @@ include_dir 'conf.d' the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads that are bigger than - <xref linkend="guc-shared-buffers">, but smaller than the OS's page + <xref linkend="guc-shared-buffers"/>, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between <literal>0</literal>, which disables forced writeback, and @@ -1962,7 +1962,7 @@ include_dir 'conf.d' The default is 1 on supported systems, otherwise 0. This value can be overridden for tables in a particular tablespace by setting the tablespace parameter of the same name (see - <xref linkend="sql-altertablespace">). + <xref linkend="sql-altertablespace"/>). </para> </listitem> </varlistentry> @@ -1988,8 +1988,8 @@ include_dir 'conf.d' <para> When changing this value, consider also adjusting - <xref linkend="guc-max-parallel-workers"> and - <xref linkend="guc-max-parallel-workers-per-gather">. + <xref linkend="guc-max-parallel-workers"/> and + <xref linkend="guc-max-parallel-workers-per-gather"/>. </para> </listitem> </varlistentry> @@ -2005,8 +2005,8 @@ include_dir 'conf.d' Sets the maximum number of workers that can be started by a single <literal>Gather</literal> or <literal>Gather Merge</literal> node. Parallel workers are taken from the pool of processes established by - <xref linkend="guc-max-worker-processes">, limited by - <xref linkend="guc-max-parallel-workers">. Note that the requested + <xref linkend="guc-max-worker-processes"/>, limited by + <xref linkend="guc-max-parallel-workers"/>. Note that the requested number of workers may not actually be available at run time. If this occurs, the plan will run with fewer workers than expected, which may be inefficient. The default value is 2. Setting this value to 0 @@ -2020,7 +2020,7 @@ include_dir 'conf.d' system as an additional user session. This should be taken into account when choosing a value for this setting, as well as when configuring other settings that control resource utilization, such - as <xref linkend="guc-work-mem">. Resource limits such as + as <xref linkend="guc-work-mem"/>. Resource limits such as <varname>work_mem</varname> are applied individually to each worker, which means the total utilization may be much higher across all processes than it would normally be for any single process. @@ -2031,7 +2031,7 @@ include_dir 'conf.d' <para> For more information on parallel query, see - <xref linkend="parallel-query">. + <xref linkend="parallel-query"/>. </para> </listitem> </varlistentry> @@ -2047,9 +2047,9 @@ include_dir 'conf.d' Sets the maximum number of workers that the system can support for parallel queries. The default value is 8. When increasing or decreasing this value, consider also adjusting - <xref linkend="guc-max-parallel-workers-per-gather">. + <xref linkend="guc-max-parallel-workers-per-gather"/>. Also, note that a setting for this value which is higher than - <xref linkend="guc-max-worker-processes"> will have no effect, + <xref linkend="guc-max-worker-processes"/> will have no effect, since parallel workers are taken from the pool of worker processes established by that setting. </para> @@ -2072,7 +2072,7 @@ include_dir 'conf.d' checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads - that are bigger than <xref linkend="guc-shared-buffers">, but smaller + that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between <literal>0</literal>, which disables forced writeback, @@ -2148,7 +2148,7 @@ include_dir 'conf.d' <para> For additional information on tuning these settings, - see <xref linkend="wal-configuration">. + see <xref linkend="wal-configuration"/>. </para> <sect2 id="runtime-config-wal-settings"> @@ -2176,7 +2176,7 @@ include_dir 'conf.d' <para> In <literal>minimal</literal> level, WAL-logging of some bulk operations can be safely skipped, which can make those - operations much faster (see <xref linkend="populate-pitr">). + operations much faster (see <xref linkend="populate-pitr"/>). Operations in which this optimization can be applied include: <simplelist> <member><command>CREATE TABLE AS</command></member> @@ -2188,7 +2188,7 @@ include_dir 'conf.d' But minimal WAL does not contain enough information to reconstruct the data from a base backup and the WAL logs, so <literal>replica</literal> or higher must be used to enable WAL archiving - (<xref linkend="guc-archive-mode">) and streaming replication. + (<xref linkend="guc-archive-mode"/>) and streaming replication. </para> <para> In <literal>logical</literal> level, the same information is logged as @@ -2218,7 +2218,7 @@ include_dir 'conf.d' If this parameter is on, the <productname>PostgreSQL</productname> server will try to make sure that updates are physically written to disk, by issuing <function>fsync()</function> system calls or various - equivalent methods (see <xref linkend="guc-wal-sync-method">). + equivalent methods (see <xref linkend="guc-wal-sync-method"/>). This ensures that the database cluster can recover to a consistent state after an operating system or hardware crash. </para> @@ -2254,7 +2254,7 @@ include_dir 'conf.d' </para> <para> - In many situations, turning off <xref linkend="guc-synchronous-commit"> + In many situations, turning off <xref linkend="guc-synchronous-commit"/> for noncritical transactions can provide much of the potential performance benefit of turning off <varname>fsync</varname>, without the attendant risks of data corruption. @@ -2264,7 +2264,7 @@ include_dir 'conf.d' <varname>fsync</varname> can only be set in the <filename>postgresql.conf</filename> file or on the server command line. If you turn this parameter off, also consider turning off - <xref linkend="guc-full-page-writes">. + <xref linkend="guc-full-page-writes"/>. </para> </listitem> </varlistentry> @@ -2285,8 +2285,8 @@ include_dir 'conf.d' is <literal>on</literal>. When <literal>off</literal>, there can be a delay between when success is reported to the client and when the transaction is really guaranteed to be safe against a server crash. (The maximum - delay is three times <xref linkend="guc-wal-writer-delay">.) Unlike - <xref linkend="guc-fsync">, setting this parameter to <literal>off</literal> + delay is three times <xref linkend="guc-wal-writer-delay"/>.) Unlike + <xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal> does not create any risk of database inconsistency: an operating system or database crash might result in some recent allegedly-committed transactions being lost, but @@ -2294,10 +2294,10 @@ include_dir 'conf.d' been aborted cleanly. So, turning <varname>synchronous_commit</varname> off can be a useful alternative when performance is more important than exact certainty about the durability of a transaction. For more - discussion see <xref linkend="wal-async-commit">. + discussion see <xref linkend="wal-async-commit"/>. </para> <para> - If <xref linkend="guc-synchronous-standby-names"> is non-empty, this + If <xref linkend="guc-synchronous-standby-names"/> is non-empty, this parameter also controls whether or not transaction commits will wait for their WAL records to be replicated to the standby server(s). When set to <literal>on</literal>, commits will wait until replies @@ -2389,7 +2389,7 @@ include_dir 'conf.d' necessary to change this setting or other aspects of your system configuration in order to create a crash-safe configuration or achieve optimal performance. - These aspects are discussed in <xref linkend="wal-reliability">. + These aspects are discussed in <xref linkend="wal-reliability"/>. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. </para> @@ -2432,7 +2432,7 @@ include_dir 'conf.d' <para> Turning off this parameter does not affect use of WAL archiving for point-in-time recovery (PITR) - (see <xref linkend="continuous-archiving">). + (see <xref linkend="continuous-archiving"/>). </para> <para> @@ -2480,7 +2480,7 @@ include_dir 'conf.d' <para> When this parameter is <literal>on</literal>, the <productname>PostgreSQL</productname> server compresses a full page image written to WAL when - <xref linkend="guc-full-page-writes"> is on or during a base backup. + <xref linkend="guc-full-page-writes"/> is on or during a base backup. A compressed page image will be decompressed during WAL replay. The default value is <literal>off</literal>. Only superusers can change this setting. @@ -2505,7 +2505,7 @@ include_dir 'conf.d' <para> The amount of shared memory used for WAL data that has not yet been written to disk. The default setting of -1 selects a size equal to - 1/32nd (about 3%) of <xref linkend="guc-shared-buffers">, but not less + 1/32nd (about 3%) of <xref linkend="guc-shared-buffers"/>, but not less than <literal>64kB</literal> nor more than the size of one WAL segment, typically <literal>16MB</literal>. This value can be set manually if the automatic choice is too large or too small, @@ -2682,7 +2682,7 @@ include_dir 'conf.d' checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads - that are bigger than <xref linkend="guc-shared-buffers">, but smaller + that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between <literal>0</literal>, which disables forced writeback, @@ -2772,14 +2772,14 @@ include_dir 'conf.d' <para> When <varname>archive_mode</varname> is enabled, completed WAL segments are sent to archive storage by setting - <xref linkend="guc-archive-command">. In addition to <literal>off</literal>, + <xref linkend="guc-archive-command"/>. In addition to <literal>off</literal>, to disable, there are two modes: <literal>on</literal>, and <literal>always</literal>. During normal operation, there is no difference between the two modes, but when set to <literal>always</literal> the WAL archiver is enabled also during archive recovery or standby mode. In <literal>always</literal> mode, all files restored from the archive or streamed with streaming replication will be archived (again). See - <xref linkend="continuous-archiving-in-standby"> for details. + <xref linkend="continuous-archiving-in-standby"/> for details. </para> <para> <varname>archive_mode</varname> and <varname>archive_command</varname> are @@ -2809,7 +2809,7 @@ include_dir 'conf.d' Use <literal>%%</literal> to embed an actual <literal>%</literal> character in the command. It is important for the command to return a zero exit status only if it succeeds. For more information see - <xref linkend="backup-archiving-wal">. + <xref linkend="backup-archiving-wal"/>. </para> <para> This parameter can only be set in the <filename>postgresql.conf</filename> @@ -2836,7 +2836,7 @@ include_dir 'conf.d' </term> <listitem> <para> - The <xref linkend="guc-archive-command"> is only invoked for + The <xref linkend="guc-archive-command"/> is only invoked for completed WAL segments. Hence, if your server generates little WAL traffic (or has slack periods where it does so), there could be a long delay between the completion of a transaction and its safe @@ -2872,10 +2872,10 @@ include_dir 'conf.d' <para> These settings control the behavior of the built-in <firstterm>streaming replication</firstterm> feature (see - <xref linkend="streaming-replication">). Servers will be either a + <xref linkend="streaming-replication"/>). Servers will be either a Master or a Standby server. Masters can send data, while Standby(s) are always receivers of replicated data. When cascading replication - (see <xref linkend="cascading-replication">) is used, Standby server(s) + (see <xref linkend="cascading-replication"/>) is used, Standby server(s) can also be senders, as well as receivers. Parameters are mainly for Sending and Standby servers, though some parameters have meaning only on the Master server. Settings may vary @@ -2909,7 +2909,7 @@ include_dir 'conf.d' processes). The default is 10. The value 0 means replication is disabled. WAL sender processes count towards the total number of connections, so the parameter cannot be set higher than - <xref linkend="guc-max-connections">. Abrupt streaming client + <xref linkend="guc-max-connections"/>. Abrupt streaming client disconnection might cause an orphaned connection slot until a timeout is reached, so this parameter should be set slightly higher than the maximum number of expected clients so disconnected @@ -2930,7 +2930,7 @@ include_dir 'conf.d' <listitem> <para> Specifies the maximum number of replication slots - (see <xref linkend="streaming-replication-slots">) that the server + (see <xref linkend="streaming-replication-slots"/>) that the server can support. The default is 10. This parameter can only be set at server start. <varname>wal_level</varname> must be set @@ -3021,9 +3021,9 @@ include_dir 'conf.d' These parameters can be set on the master/primary server that is to send replication data to one or more standby servers. Note that in addition to these parameters, - <xref linkend="guc-wal-level"> must be set appropriately on the master + <xref linkend="guc-wal-level"/> must be set appropriately on the master server, and optionally WAL archiving can be enabled as - well (see <xref linkend="runtime-config-wal-archiving">). + well (see <xref linkend="runtime-config-wal-archiving"/>). The values of these parameters on standby servers are irrelevant, although you may wish to set them there in preparation for the possibility of a standby becoming the master. @@ -3041,7 +3041,7 @@ include_dir 'conf.d' <para> Specifies a list of standby servers that can support <firstterm>synchronous replication</firstterm>, as described in - <xref linkend="synchronous-replication">. + <xref linkend="synchronous-replication"/>. There will be one or more active synchronous standbys; transactions waiting for commit will be allowed to proceed after these standby servers confirm receipt of their data. @@ -3148,7 +3148,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" replication. This is the default configuration. Even when synchronous replication is enabled, individual transactions can be configured not to wait for replication by setting the - <xref linkend="guc-synchronous-commit"> parameter to + <xref linkend="guc-synchronous-commit"/> parameter to <literal>local</literal> or <literal>off</literal>. </para> <para> @@ -3172,7 +3172,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" removed as soon as possible, that is, as soon as they are no longer visible to any open transaction. You may wish to set this to a non-zero value on a primary server that is supporting hot standby - servers, as described in <xref linkend="hot-standby">. This allows + servers, as described in <xref linkend="hot-standby"/>. This allows more time for queries on the standby to complete without incurring conflicts due to early cleanup of rows. However, since the value is measured in terms of number of write transactions occurring on the @@ -3215,7 +3215,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <listitem> <para> Specifies whether or not you can connect and run queries during - recovery, as described in <xref linkend="hot-standby">. + recovery, as described in <xref linkend="hot-standby"/>. The default value is <literal>on</literal>. This parameter can only be set at server start. It only has effect during archive recovery or in standby mode. @@ -3234,7 +3234,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" When Hot Standby is active, this parameter determines how long the standby server should wait before canceling standby queries that conflict with about-to-be-applied WAL entries, as described in - <xref linkend="hot-standby-conflict">. + <xref linkend="hot-standby-conflict"/>. <varname>max_standby_archive_delay</varname> applies when WAL data is being read from WAL archive (and is therefore not current). The default is 30 seconds. Units are milliseconds if not specified. @@ -3265,7 +3265,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" When Hot Standby is active, this parameter determines how long the standby server should wait before canceling standby queries that conflict with about-to-be-applied WAL entries, as described in - <xref linkend="hot-standby-conflict">. + <xref linkend="hot-standby-conflict"/>. <varname>max_standby_streaming_delay</varname> applies when WAL data is being received via streaming replication. The default is 30 seconds. Units are milliseconds if not specified. @@ -3484,10 +3484,10 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" choose a different plan. Better ways to improve the quality of the plans chosen by the optimizer include adjusting the planner cost - constants (see <xref linkend="runtime-config-query-constants">), - running <xref linkend="sql-analyze"> manually, increasing + constants (see <xref linkend="runtime-config-query-constants"/>), + running <xref linkend="sql-analyze"/> manually, increasing the value of the <xref - linkend="guc-default-statistics-target"> configuration parameter, + linkend="guc-default-statistics-target"/> configuration parameter, and increasing the amount of statistics collected for specific columns using <command>ALTER TABLE SET STATISTICS</command>. @@ -3579,7 +3579,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <listitem> <para> Enables or disables the query planner's use of index-only-scan plan - types (see <xref linkend="indexes-index-only-scans">). + types (see <xref linkend="indexes-index-only-scans"/>). The default is <literal>on</literal>. </para> </listitem> @@ -3745,7 +3745,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" that is part of a series of sequential fetches. The default is 1.0. This value can be overridden for tables and indexes in a particular tablespace by setting the tablespace parameter of the same name - (see <xref linkend="sql-altertablespace">). + (see <xref linkend="sql-altertablespace"/>). </para> </listitem> </varlistentry> @@ -3762,7 +3762,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" non-sequentially-fetched disk page. The default is 4.0. This value can be overridden for tables and indexes in a particular tablespace by setting the tablespace parameter of the same name - (see <xref linkend="sql-altertablespace">). + (see <xref linkend="sql-altertablespace"/>). </para> <para> @@ -3960,7 +3960,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" complex queries (those joining many relations), at the cost of producing plans that are sometimes inferior to those found by the normal exhaustive-search algorithm. - For more information see <xref linkend="geqo">. + For more information see <xref linkend="geqo"/>. </para> <variablelist> @@ -4124,7 +4124,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" do <command>ANALYZE</command>, but might improve the quality of the planner's estimates. The default is 100. For more information on the use of statistics by the <productname>PostgreSQL</productname> - query planner, refer to <xref linkend="planner-stats">. + query planner, refer to <xref linkend="planner-stats"/>. </para> </listitem> </varlistentry> @@ -4180,7 +4180,7 @@ SELECT * FROM parent WHERE key = 2400; </para> <para> - Refer to <xref linkend="ddl-partitioning-constraint-exclusion"> for + Refer to <xref linkend="ddl-partitioning-constraint-exclusion"/> for more information on using constraint exclusion and partitioning. </para> </listitem> @@ -4219,13 +4219,13 @@ SELECT * FROM parent WHERE key = 2400; resulting <literal>FROM</literal> list would have no more than this many items. Smaller values reduce planning time but might yield inferior query plans. The default is eight. - For more information see <xref linkend="explicit-joins">. + For more information see <xref linkend="explicit-joins"/>. </para> <para> - Setting this value to <xref linkend="guc-geqo-threshold"> or more + Setting this value to <xref linkend="guc-geqo-threshold"/> or more may trigger use of the GEQO planner, resulting in non-optimal - plans. See <xref linkend="runtime-config-query-geqo">. + plans. See <xref linkend="runtime-config-query-geqo"/>. </para> </listitem> </varlistentry> @@ -4255,13 +4255,13 @@ SELECT * FROM parent WHERE key = 2400; the optimal join order, advanced users can elect to temporarily set this variable to 1, and then specify the join order they desire explicitly. - For more information see <xref linkend="explicit-joins">. + For more information see <xref linkend="explicit-joins"/>. </para> <para> - Setting this value to <xref linkend="guc-geqo-threshold"> or more + Setting this value to <xref linkend="guc-geqo-threshold"/> or more may trigger use of the GEQO planner, resulting in non-optimal - plans. See <xref linkend="runtime-config-query-geqo">. + plans. See <xref linkend="runtime-config-query-geqo"/>. </para> </listitem> </varlistentry> @@ -4386,8 +4386,8 @@ SELECT * FROM parent WHERE key = 2400; log entries are output in <quote>comma separated value</quote> (<acronym>CSV</acronym>) format, which is convenient for loading logs into programs. - See <xref linkend="runtime-config-logging-csvlog"> for details. - <xref linkend="guc-logging-collector"> must be enabled to generate + See <xref linkend="runtime-config-logging-csvlog"/> for details. + <xref linkend="guc-logging-collector"/> must be enabled to generate CSV-format log output. </para> <para> @@ -4420,7 +4420,7 @@ csvlog log/postgresql.csv <varname>log_destination</varname>. <productname>PostgreSQL</productname> can log to <application>syslog</application> facilities <literal>LOCAL0</literal> through <literal>LOCAL7</literal> (see <xref - linkend="guc-syslog-facility">), but the default + linkend="guc-syslog-facility"/>), but the default <application>syslog</application> configuration on most platforms will discard all such messages. You will need to add something like: <programlisting> @@ -4435,7 +4435,7 @@ local0.* /var/log/postgresql register an event source and its library with the operating system so that the Windows Event Viewer can display event log messages cleanly. - See <xref linkend="event-log-registration"> for details. + See <xref linkend="event-log-registration"/> for details. </para> </note> </listitem> @@ -4522,7 +4522,7 @@ local0.* /var/log/postgresql file names. (Note that if there are any time-zone-dependent <literal>%</literal>-escapes, the computation is done in the zone specified - by <xref linkend="guc-log-timezone">.) + by <xref linkend="guc-log-timezone"/>.) The supported <literal>%</literal>-escapes are similar to those listed in the Open Group's <ulink url="http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">strftime @@ -4576,7 +4576,7 @@ local0.* /var/log/postgresql server owner can read or write the log files. The other commonly useful setting is <literal>0640</literal>, allowing members of the owner's group to read the files. Note however that to make use of such a - setting, you'll need to alter <xref linkend="guc-log-directory"> to + setting, you'll need to alter <xref linkend="guc-log-directory"/> to store the files somewhere outside the cluster data directory. In any case, it's unwise to make the log files world-readable, since they might contain sensitive data. @@ -4897,13 +4897,13 @@ local0.* /var/log/postgresql <note> <para> When using this option together with - <xref linkend="guc-log-statement">, + <xref linkend="guc-log-statement"/>, the text of statements that are logged because of <varname>log_statement</varname> will not be repeated in the duration log message. If you are not using <application>syslog</application>, it is recommended that you log the PID or session ID using - <xref linkend="guc-log-line-prefix"> + <xref linkend="guc-log-line-prefix"/> so that you can link the statement message to the later duration message using the process ID or session ID. </para> @@ -4914,7 +4914,7 @@ local0.* /var/log/postgresql </variablelist> <para> - <xref linkend="runtime-config-severity-levels"> explains the message + <xref linkend="runtime-config-severity-levels"/> explains the message severity levels used by <productname>PostgreSQL</productname>. If logging output is sent to <systemitem>syslog</systemitem> or Windows' <systemitem>eventlog</systemitem>, the severity levels are translated @@ -5019,7 +5019,7 @@ local0.* /var/log/postgresql It is typically set by an application upon connection to the server. The name will be displayed in the <structname>pg_stat_activity</structname> view and included in CSV log entries. It can also be included in regular - log entries via the <xref linkend="guc-log-line-prefix"> parameter. + log entries via the <xref linkend="guc-log-line-prefix"/> parameter. Only printable ASCII characters may be used in the <varname>application_name</varname> value. Other characters will be replaced with question marks (<literal>?</literal>). @@ -5051,8 +5051,8 @@ local0.* /var/log/postgresql These messages are emitted at <literal>LOG</literal> message level, so by default they will appear in the server log but will not be sent to the client. You can change that by adjusting - <xref linkend="guc-client-min-messages"> and/or - <xref linkend="guc-log-min-messages">. + <xref linkend="guc-client-min-messages"/> and/or + <xref linkend="guc-log-min-messages"/>. These parameters are off by default. </para> </listitem> @@ -5159,7 +5159,7 @@ local0.* /var/log/postgresql <note> <para> The difference between setting this option and setting - <xref linkend="guc-log-min-duration-statement"> to zero is that + <xref linkend="guc-log-min-duration-statement"/> to zero is that exceeding <varname>log_min_duration_statement</varname> forces the text of the query to be logged, but this option doesn't. Thus, if <varname>log_duration</varname> is <literal>on</literal> and @@ -5187,7 +5187,7 @@ local0.* /var/log/postgresql the logging of <literal>DETAIL</literal>, <literal>HINT</literal>, <literal>QUERY</literal>, and <literal>CONTEXT</literal> error information. <literal>VERBOSE</literal> output includes the <symbol>SQLSTATE</symbol> error - code (see also <xref linkend="errcodes-appendix">) and the source code file name, function name, + code (see also <xref linkend="errcodes-appendix"/>) and the source code file name, function name, and line number that generated the error. Only superusers can change this setting. </para> @@ -5397,7 +5397,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' <listitem> <para> Controls whether a log message is produced when a session waits - longer than <xref linkend="guc-deadlock-timeout"> to acquire a + longer than <xref linkend="guc-deadlock-timeout"/> to acquire a lock. This is useful in determining if lock waits are causing poor performance. The default is <literal>off</literal>. Only superusers can change this setting. @@ -5459,7 +5459,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' <listitem> <para> Causes each replication command to be logged in the server log. - See <xref linkend="protocol-replication"> for more information about + See <xref linkend="protocol-replication"/> for more information about replication command. The default value is <literal>off</literal>. Only superusers can change this setting. </para> @@ -5496,12 +5496,12 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' <listitem> <para> Sets the time zone used for timestamps written in the server log. - Unlike <xref linkend="guc-timezone">, this value is cluster-wide, + Unlike <xref linkend="guc-timezone"/>, this value is cluster-wide, so that all sessions will report timestamps consistently. The built-in default is <literal>GMT</literal>, but that is typically overridden in <filename>postgresql.conf</filename>; <application>initdb</application> will install a setting there corresponding to its system environment. - See <xref linkend="datatype-timezones"> for more information. + See <xref linkend="datatype-timezones"/> for more information. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. </para> @@ -5641,7 +5641,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; These settings control how process titles of server processes are modified. Process titles are typically viewed using programs like <application>ps</application> or, on Windows, <application>Process Explorer</application>. - See <xref linkend="monitoring-ps"> for details. + See <xref linkend="monitoring-ps"/> for details. </para> <variablelist> @@ -5697,7 +5697,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; When statistics collection is enabled, the data that is produced can be accessed via the <structname>pg_stat</structname> and <structname>pg_statio</structname> family of system views. - Refer to <xref linkend="monitoring"> for more information. + Refer to <xref linkend="monitoring"/> for more information. </para> <variablelist> @@ -5766,12 +5766,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Enables timing of database I/O calls. This parameter is off by default, because it will repeatedly query the operating system for the current time, which may cause significant overhead on some - platforms. You can use the <xref linkend="pgtesttiming"> tool to + platforms. You can use the <xref linkend="pgtesttiming"/> tool to measure the overhead of timing on your system. I/O timing information is - displayed in <xref linkend="pg-stat-database-view">, in the output of - <xref linkend="sql-explain"> when the <literal>BUFFERS</literal> option is - used, and by <xref linkend="pgstatstatements">. Only superusers can + displayed in <xref linkend="pg-stat-database-view"/>, in the output of + <xref linkend="sql-explain"/> when the <literal>BUFFERS</literal> option is + used, and by <xref linkend="pgstatstatements"/>. Only superusers can change this setting. </para> </listitem> @@ -5878,10 +5878,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> These settings control the behavior of the <firstterm>autovacuum</firstterm> - feature. Refer to <xref linkend="autovacuum"> for more information. + feature. Refer to <xref linkend="autovacuum"/> for more information. Note that many of these settings can be overridden on a per-table basis; see <xref linkend="sql-createtable-storage-parameters" - endterm="sql-createtable-storage-parameters-title">. + endterm="sql-createtable-storage-parameters-title"/>. </para> <variablelist> @@ -5896,7 +5896,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> Controls whether the server should run the autovacuum launcher daemon. This is on by default; however, - <xref linkend="guc-track-counts"> must also be enabled for + <xref linkend="guc-track-counts"/> must also be enabled for autovacuum to work. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line; however, autovacuuming can be @@ -5906,7 +5906,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Note that even when this parameter is disabled, the system will launch autovacuum processes if necessary to prevent transaction ID wraparound. See <xref - linkend="vacuum-for-wraparound"> for more information. + linkend="vacuum-for-wraparound"/> for more information. </para> </listitem> </varlistentry> @@ -6071,7 +6071,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; This parameter can only be set at server start, but the setting can be reduced for individual tables by changing table storage parameters. - For more information see <xref linkend="vacuum-for-wraparound">. + For more information see <xref linkend="vacuum-for-wraparound"/>. </para> </listitem> </varlistentry> @@ -6099,7 +6099,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 400 million multixacts. This parameter can only be set at server start, but the setting can be reduced for individual tables by changing table storage parameters. - For more information see <xref linkend="vacuum-for-multixact-wraparound">. + For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. </para> </listitem> </varlistentry> @@ -6114,7 +6114,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> Specifies the cost delay value that will be used in automatic <command>VACUUM</command> operations. If -1 is specified, the regular - <xref linkend="guc-vacuum-cost-delay"> value will be used. + <xref linkend="guc-vacuum-cost-delay"/> value will be used. The default value is 20 milliseconds. This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line; @@ -6135,7 +6135,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Specifies the cost limit value that will be used in automatic <command>VACUUM</command> operations. If -1 is specified (which is the default), the regular - <xref linkend="guc-vacuum-cost-limit"> value will be used. Note that + <xref linkend="guc-vacuum-cost-limit"/> value will be used. Note that the value is distributed proportionally among the running autovacuum workers, if there is more than one, so that the sum of the limits for each worker does not exceed the value of this variable. @@ -6230,7 +6230,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; The current effective value of the search path can be examined via the <acronym>SQL</acronym> function <function>current_schemas</function> - (see <xref linkend="functions-info">). + (see <xref linkend="functions-info"/>). This is not quite the same as examining the value of <varname>search_path</varname>, since <function>current_schemas</function> shows how the items @@ -6238,7 +6238,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </para> <para> - For more information on schema handling, see <xref linkend="ddl-schemas">. + For more information on schema handling, see <xref linkend="ddl-schemas"/>. </para> </listitem> </varlistentry> @@ -6264,7 +6264,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> For more information on row security policies, - see <xref linkend="sql-createpolicy">. + see <xref linkend="sql-createpolicy"/>. </para> </listitem> </varlistentry> @@ -6295,7 +6295,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> This variable is not used for temporary tables; for them, - <xref linkend="guc-temp-tablespaces"> is consulted instead. + <xref linkend="guc-temp-tablespaces"/> is consulted instead. </para> <para> @@ -6306,7 +6306,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> For more information on tablespaces, - see <xref linkend="manage-ag-tablespaces">. + see <xref linkend="manage-ag-tablespaces"/>. </para> </listitem> </varlistentry> @@ -6355,7 +6355,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </para> <para> - See also <xref linkend="guc-default-tablespace">. + See also <xref linkend="guc-default-tablespace"/>. </para> </listitem> </varlistentry> @@ -6370,7 +6370,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> This parameter is normally on. When set to <literal>off</literal>, it disables validation of the function body string during <xref - linkend="sql-createfunction">. Disabling validation avoids side + linkend="sql-createfunction"/>. Disabling validation avoids side effects of the validation process and avoids false positives due to problems such as forward references. Set this parameter to <literal>off</literal> before loading functions on behalf of other @@ -6400,8 +6400,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </para> <para> - Consult <xref linkend="mvcc"> and <xref - linkend="sql-set-transaction"> for more information. + Consult <xref linkend="mvcc"/> and <xref + linkend="sql-set-transaction"/> for more information. </para> </listitem> </varlistentry> @@ -6424,7 +6424,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </para> <para> - Consult <xref linkend="sql-set-transaction"> for more information. + Consult <xref linkend="sql-set-transaction"/> for more information. </para> </listitem> </varlistentry> @@ -6458,7 +6458,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; </para> <para> - Consult <xref linkend="sql-set-transaction"> for more information. + Consult <xref linkend="sql-set-transaction"/> for more information. </para> </listitem> </varlistentry> @@ -6477,7 +6477,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; superuser privilege and results in discarding any previously cached query plans. Possible values are <literal>origin</literal> (the default), <literal>replica</literal> and <literal>local</literal>. - See <xref linkend="sql-altertable"> for + See <xref linkend="sql-altertable"/> for more information. </para> </listitem> @@ -6553,7 +6553,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; longer than the specified duration in milliseconds. This allows any locks held by that session to be released and the connection slot to be reused; it also allows tuples visible only to this transaction to be vacuumed. See - <xref linkend="routine-vacuuming"> for more details about this. + <xref linkend="routine-vacuuming"/> for more details about this. </para> <para> The default value of 0 disables this feature. @@ -6577,11 +6577,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; tuples. The default is 150 million transactions. Although users can set this value anywhere from zero to two billions, <command>VACUUM</command> will silently limit the effective value to 95% of - <xref linkend="guc-autovacuum-freeze-max-age">, so that a + <xref linkend="guc-autovacuum-freeze-max-age"/>, so that a periodical manual <command>VACUUM</command> has a chance to run before an anti-wraparound autovacuum is launched for the table. For more information see - <xref linkend="vacuum-for-wraparound">. + <xref linkend="vacuum-for-wraparound"/>. </para> </listitem> </varlistentry> @@ -6600,10 +6600,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; The default is 50 million transactions. Although users can set this value anywhere from zero to one billion, <command>VACUUM</command> will silently limit the effective value to half - the value of <xref linkend="guc-autovacuum-freeze-max-age">, so + the value of <xref linkend="guc-autovacuum-freeze-max-age"/>, so that there is not an unreasonably short time between forced autovacuums. For more information see <xref - linkend="vacuum-for-wraparound">. + linkend="vacuum-for-wraparound"/>. </para> </listitem> </varlistentry> @@ -6624,10 +6624,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; tuples. The default is 150 million multixacts. Although users can set this value anywhere from zero to two billions, <command>VACUUM</command> will silently limit the effective value to 95% of - <xref linkend="guc-autovacuum-multixact-freeze-max-age">, so that a + <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>, so that a periodical manual <command>VACUUM</command> has a chance to run before an anti-wraparound is launched for the table. - For more information see <xref linkend="vacuum-for-multixact-wraparound">. + For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. </para> </listitem> </varlistentry> @@ -6646,10 +6646,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; is 5 million multixacts. Although users can set this value anywhere from zero to one billion, <command>VACUUM</command> will silently limit the effective value to half - the value of <xref linkend="guc-autovacuum-multixact-freeze-max-age">, + the value of <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>, so that there is not an unreasonably short time between forced autovacuums. - For more information see <xref linkend="vacuum-for-multixact-wraparound">. + For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. </para> </listitem> </varlistentry> @@ -6665,7 +6665,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Sets the output format for values of type <type>bytea</type>. Valid values are <literal>hex</literal> (the default) and <literal>escape</literal> (the traditional PostgreSQL - format). See <xref linkend="datatype-binary"> for more + format). See <xref linkend="datatype-binary"/> for more information. The <type>bytea</type> type always accepts both formats on input, regardless of this setting. </para> @@ -6687,7 +6687,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <literal>base64</literal> and <literal>hex</literal>, which are both defined in the XML Schema standard. The default is <literal>base64</literal>. For further information about - XML-related functions, see <xref linkend="functions-xml">. + XML-related functions, see <xref linkend="functions-xml"/>. </para> <para> @@ -6717,7 +6717,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Sets whether <literal>DOCUMENT</literal> or <literal>CONTENT</literal> is implicit when converting between XML and character string values. See <xref - linkend="datatype-xml"> for a description of this. Valid + linkend="datatype-xml"/> for a description of this. Valid values are <literal>DOCUMENT</literal> and <literal>CONTENT</literal>. The default is <literal>CONTENT</literal>. @@ -6748,7 +6748,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; The default is four megabytes (<literal>4MB</literal>). This setting can be overridden for individual GIN indexes by changing index storage parameters. - See <xref linkend="gin-fast-update"> and <xref linkend="gin-tips"> + See <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/> for more information. </para> </listitem> @@ -6780,7 +6780,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; and <literal>European</literal> are synonyms for <literal>DMY</literal>; the keywords <literal>US</literal>, <literal>NonEuro</literal>, and <literal>NonEuropean</literal> are synonyms for <literal>MDY</literal>. See - <xref linkend="datatype-datetime"> for more information. The + <xref linkend="datatype-datetime"/> for more information. The built-in default is <literal>ISO, MDY</literal>, but <application>initdb</application> will initialize the configuration file with a setting that corresponds to the @@ -6802,7 +6802,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; output matching <acronym>SQL</acronym> standard interval literals. The value <literal>postgres</literal> (which is the default) will produce output matching <productname>PostgreSQL</productname> releases prior to 8.4 - when the <xref linkend="guc-datestyle"> + when the <xref linkend="guc-datestyle"/> parameter was set to <literal>ISO</literal>. The value <literal>postgres_verbose</literal> will produce output matching <productname>PostgreSQL</productname> releases prior to 8.4 @@ -6815,7 +6815,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; <para> The <varname>IntervalStyle</varname> parameter also affects the interpretation of ambiguous interval input. See - <xref linkend="datatype-interval-input"> for more information. + <xref linkend="datatype-interval-input"/> for more information. </para> </listitem> </varlistentry> @@ -6833,7 +6833,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; The built-in default is <literal>GMT</literal>, but that is typically overridden in <filename>postgresql.conf</filename>; <application>initdb</application> will install a setting there corresponding to its system environment. - See <xref linkend="datatype-timezones"> for more information. + See <xref linkend="datatype-timezones"/> for more information. </para> </listitem> </varlistentry> @@ -6852,7 +6852,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; which is a collection that works in most of the world; there are also <literal>'Australia'</literal> and <literal>'India'</literal>, and other collections can be defined for a particular installation. - See <xref linkend="datetime-config-files"> for more information. + See <xref linkend="datetime-config-files"/> for more information. </para> </listitem> </varlistentry> @@ -6880,7 +6880,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; partially-significant digits; this is especially useful for dumping float data that needs to be restored exactly. Or it can be set negative to suppress unwanted digits. - See also <xref linkend="datatype-float">. + See also <xref linkend="datatype-float"/>. </para> </listitem> </varlistentry> @@ -6897,7 +6897,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the client-side encoding (character set). The default is to use the database encoding. The character sets supported by the <productname>PostgreSQL</productname> - server are described in <xref linkend="multibyte-charset-supported">. + server are described in <xref linkend="multibyte-charset-supported"/>. </para> </listitem> </varlistentry> @@ -6911,7 +6911,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; <listitem> <para> Sets the language in which messages are displayed. Acceptable - values are system-dependent; see <xref linkend="locale"> for + values are system-dependent; see <xref linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6945,7 +6945,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting monetary amounts, for example with the <function>to_char</function> family of functions. Acceptable values are system-dependent; see <xref - linkend="locale"> for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6964,7 +6964,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting numbers, for example with the <function>to_char</function> family of functions. Acceptable values are system-dependent; see <xref - linkend="locale"> for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6983,7 +6983,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting dates and times, for example with the <function>to_char</function> family of functions. Acceptable values are system-dependent; see <xref - linkend="locale"> for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -7002,7 +7002,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Selects the text search configuration that is used by those variants of the text search functions that do not have an explicit argument specifying the configuration. - See <xref linkend="textsearch"> for further information. + See <xref linkend="textsearch"/> for further information. The built-in default is <literal>pg_catalog.simple</literal>, but <application>initdb</application> will initialize the configuration file with a setting that corresponds to the @@ -7067,7 +7067,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries that are to be preloaded at connection start. It contains a comma-separated list of library names, where each name - is interpreted as for the <xref linkend="sql-load"> command. + is interpreted as for the <xref linkend="sql-load"/> command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. The parameter value only takes effect at the start of the connection. @@ -7101,7 +7101,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; <para> However, unless a module is specifically designed to be used in this way by non-superusers, this is usually not the right setting to use. Look - at <xref linkend="guc-session-preload-libraries"> instead. + at <xref linkend="guc-session-preload-libraries"/> instead. </para> </listitem> </varlistentry> @@ -7118,7 +7118,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries that are to be preloaded at connection start. It contains a comma-separated list of library names, where each name - is interpreted as for the <xref linkend="sql-load"> command. + is interpreted as for the <xref linkend="sql-load"/> command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. The parameter value only takes effect at the start of the connection. @@ -7132,7 +7132,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; performance-measurement libraries to be loaded into specific sessions without an explicit <command>LOAD</command> command being given. For - example, <xref linkend="auto-explain"> could be enabled for all + example, <xref linkend="auto-explain"/> could be enabled for all sessions under a given user name by setting this parameter with <command>ALTER ROLE SET</command>. Also, this parameter can be changed without restarting the server (but changes only take effect when a new @@ -7141,7 +7141,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; </para> <para> - Unlike <xref linkend="guc-shared-preload-libraries">, there is no large + Unlike <xref linkend="guc-shared-preload-libraries"/>, there is no large performance advantage to loading a library at session start rather than when it is first used. There is some advantage, however, when connection pooling is used. @@ -7160,7 +7160,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries to be preloaded at server start. It contains a comma-separated list of library names, where each name - is interpreted as for the <xref linkend="sql-load"> command. + is interpreted as for the <xref linkend="sql-load"/> command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. This parameter can only be set at server start. If a specified @@ -7183,7 +7183,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; parameter is recommended only for libraries that will be used in most sessions. Also, changing this parameter requires a server restart, so this is not the right setting to use for short-term debugging tasks, - say. Use <xref linkend="guc-session-preload-libraries"> for that + say. Use <xref linkend="guc-session-preload-libraries"/> for that instead. </para> @@ -7269,7 +7269,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <listitem> <para> Soft upper limit of the size of the set returned by GIN index scans. For more - information see <xref linkend="gin-tips">. + information see <xref linkend="gin-tips"/>. </para> </listitem> </varlistentry> @@ -7317,7 +7317,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </para> <para> - When <xref linkend="guc-log-lock-waits"> is set, + When <xref linkend="guc-log-lock-waits"/> is set, this parameter also determines the length of time to wait before a log message is issued about the lock wait. If you are trying to investigate locking delays you might want to set a shorter than @@ -7336,8 +7336,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <para> The shared lock table tracks locks on <varname>max_locks_per_transaction</varname> * (<xref - linkend="guc-max-connections"> + <xref - linkend="guc-max-prepared-transactions">) objects (e.g., tables); + linkend="guc-max-connections"/> + <xref + linkend="guc-max-prepared-transactions"/>) objects (e.g., tables); hence, no more than this many distinct objects can be locked at any one time. This parameter controls the average number of object locks allocated for each transaction; individual transactions @@ -7368,8 +7368,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <para> The shared predicate lock table tracks locks on <varname>max_pred_locks_per_transaction</varname> * (<xref - linkend="guc-max-connections"> + <xref - linkend="guc-max-prepared-transactions">) objects (e.g., tables); + linkend="guc-max-connections"/> + <xref + linkend="guc-max-prepared-transactions"/>) objects (e.g., tables); hence, no more than this many distinct objects can be locked at any one time. This parameter controls the average number of object locks allocated for each transaction; individual transactions @@ -7396,7 +7396,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values - mean <xref linkend="guc-max-pred-locks-per-transaction"> divided by + mean <xref linkend="guc-max-pred-locks-per-transaction"/> divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of <productname>PostgreSQL</productname>. This parameter can only be set in the <filename>postgresql.conf</filename> @@ -7589,7 +7589,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </para> <para> - See <xref linkend="sql-precedence"> for more information. + See <xref linkend="sql-precedence"/> for more information. </para> </listitem> </varlistentry> @@ -7607,7 +7607,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' output of <command>EXPLAIN</command> as well as the results of functions like <function>pg_get_viewdef</function>. See also the <option>--quote-all-identifiers</option> option of - <xref linkend="app-pgdump"> and <xref linkend="app-pg-dumpall">. + <xref linkend="app-pgdump"/> and <xref linkend="app-pg-dumpall"/>. </para> </listitem> </varlistentry> @@ -7630,7 +7630,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' parameter to determine how string literals will be processed. The presence of this parameter can also be taken as an indication that the escape string syntax (<literal>E'...'</literal>) is supported. - Escape string syntax (<xref linkend="sql-syntax-strings-escape">) + Escape string syntax (<xref linkend="sql-syntax-strings-escape"/>) should be used if an application desires backslashes to be treated as escape characters. </para> @@ -7710,7 +7710,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </para> <para> - Refer to <xref linkend="functions-comparison"> for related information. + Refer to <xref linkend="functions-comparison"/> for related information. </para> </listitem> </varlistentry> @@ -7788,9 +7788,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the size of a disk block. It is determined by the value of <literal>BLCKSZ</literal> when building the server. The default value is 8192 bytes. The meaning of some configuration - variables (such as <xref linkend="guc-shared-buffers">) is + variables (such as <xref linkend="guc-shared-buffers"/>) is influenced by <varname>block_size</varname>. See <xref - linkend="runtime-config-resource"> for information. + linkend="runtime-config-resource"/> for information. </para> </listitem> </varlistentry> @@ -7804,7 +7804,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <listitem> <para> Reports whether data checksums are enabled for this cluster. - See <xref linkend="app-initdb-data-checksums"> for more information. + See <xref linkend="app-initdb-data-checksums"/> for more information. </para> </listitem> </varlistentry> @@ -7853,7 +7853,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <listitem> <para> Reports the locale in which sorting of textual data is done. - See <xref linkend="locale"> for more information. + See <xref linkend="locale"/> for more information. This value is determined when a database is created. </para> </listitem> @@ -7868,7 +7868,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <listitem> <para> Reports the locale that determines character classifications. - See <xref linkend="locale"> for more information. + See <xref linkend="locale"/> for more information. This value is determined when a database is created. Ordinarily this will be the same as <varname>lc_collate</varname>, but for special applications it might be set differently. @@ -7953,7 +7953,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the database encoding (character set). It is determined when the database is created. Ordinarily, clients need only be concerned with the value of <xref - linkend="guc-client-encoding">. + linkend="guc-client-encoding"/>. </para> </listitem> </varlistentry> @@ -8012,7 +8012,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the number of blocks (pages) in a WAL segment file. The total size of a WAL segment file in bytes is equal to <varname>wal_segment_size</varname> multiplied by <varname>wal_block_size</varname>; - by default this is 16MB. See <xref linkend="wal-configuration"> for + by default this is 16MB. See <xref linkend="wal-configuration"/> for more information. </para> </listitem> @@ -8140,8 +8140,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <para> Generates a great amount of debugging output for the <command>LISTEN</command> and <command>NOTIFY</command> - commands. <xref linkend="guc-client-min-messages"> or - <xref linkend="guc-log-min-messages"> must be + commands. <xref linkend="guc-client-min-messages"/> or + <xref linkend="guc-log-min-messages"/> must be <literal>DEBUG1</literal> or lower to send this output to the client or server logs, respectively. </para> @@ -8158,7 +8158,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' <para> Enables logging of recovery-related debugging output that otherwise would not be logged. This parameter allows the user to override the - normal setting of <xref linkend="guc-log-min-messages">, but only for + normal setting of <xref linkend="guc-log-min-messages"/>, but only for specific messages. This is intended for use in debugging Hot Standby. Valid values are <literal>DEBUG5</literal>, <literal>DEBUG4</literal>, <literal>DEBUG3</literal>, <literal>DEBUG2</literal>, <literal>DEBUG1</literal>, and @@ -8401,7 +8401,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) </term> <listitem> <para> - Only has effect if <xref linkend="app-initdb-data-checksums"> are enabled. + Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled. </para> <para> Detection of a checksum failure during a read normally causes @@ -8452,7 +8452,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) <para> For convenience there are also single letter command-line option switches available for some parameters. They are described in - <xref linkend="runtime-config-short-table">. Some of these + <xref linkend="runtime-config-short-table"/>. Some of these options exist for historical reasons, and their presence as a single-letter option does not necessarily indicate an endorsement to use the option heavily. diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 7dd203e9cd..0622227bee 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -16,14 +16,14 @@ <para> This appendix covers extensions and other server plug-in modules found in - <literal>contrib</literal>. <xref linkend="contrib-prog"> covers utility + <literal>contrib</literal>. <xref linkend="contrib-prog"/> covers utility programs. </para> <para> When building from the source distribution, these components are not built automatically, unless you build the "world" target - (see <xref linkend="build">). + (see <xref linkend="build"/>). You can build and install all of them by running: <screen> <userinput>make</userinput> @@ -55,7 +55,7 @@ To make use of one of these modules, after you have installed the code you need to register the new SQL objects in the database system. In <productname>PostgreSQL</productname> 9.1 and later, this is done by executing - a <xref linkend="sql-createextension"> command. In a fresh database, + a <xref linkend="sql-createextension"/> command. In a fresh database, you can simply do <programlisting> @@ -89,16 +89,16 @@ CREATE EXTENSION <replaceable>module_name</replaceable> FROM unpackaged; This will update the pre-9.1 objects of the module into a proper <firstterm>extension</firstterm> object. Future updates to the module will be - managed by <xref linkend="sql-alterextension">. + managed by <xref linkend="sql-alterextension"/>. For more information about extension updates, see - <xref linkend="extend-extensions">. + <xref linkend="extend-extensions"/>. </para> <para> Note, however, that some of these modules are not <quote>extensions</quote> in this sense, but are loaded into the server in some other way, for instance by way of - <xref linkend="guc-shared-preload-libraries">. See the documentation of each + <xref linkend="guc-shared-preload-libraries"/>. See the documentation of each module for details. </para> @@ -163,7 +163,7 @@ pages. <para> This appendix and the previous one contain information regarding the modules that can be found in the <literal>contrib</literal> directory of the - <productname>PostgreSQL</productname> distribution. See <xref linkend="contrib"> for + <productname>PostgreSQL</productname> distribution. See <xref linkend="contrib"/> for more information about the <literal>contrib</literal> section in general and server extensions and plug-ins found in <literal>contrib</literal> specifically. @@ -184,7 +184,7 @@ pages. This section covers <productname>PostgreSQL</productname> client applications in <literal>contrib</literal>. They can be run from anywhere, independent of where the database server resides. See - also <xref linkend="reference-client"> for information about client + also <xref linkend="reference-client"/> for information about client applications that part of the core <productname>PostgreSQL</productname> distribution. </para> @@ -200,7 +200,7 @@ pages. This section covers <productname>PostgreSQL</productname> server-related applications in <literal>contrib</literal>. They are typically run on the host where the database server resides. See also <xref - linkend="reference-server"> for information about server applications that + linkend="reference-server"/> for information about server applications that part of the core <productname>PostgreSQL</productname> distribution. </para> diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 46d8e4eb8f..b995dc7e2a 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -16,7 +16,7 @@ <title>Syntax</title> <para> - <xref linkend="cube-repr-table"> shows the valid external + <xref linkend="cube-repr-table"/> shows the valid external representations for the <type>cube</type> type. <replaceable>x</replaceable>, <replaceable>y</replaceable>, etc. denote floating-point numbers. @@ -106,7 +106,7 @@ <title>Usage</title> <para> - <xref linkend="cube-operators-table"> shows the operators provided for + <xref linkend="cube-operators-table"/> shows the operators provided for type <type>cube</type>. </para> @@ -268,7 +268,7 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; </para> <para> - <xref linkend="cube-functions-table"> shows the available functions. + <xref linkend="cube-functions-table"/> shows the available functions. </para> <table id="cube-functions-table"> diff --git a/doc/src/sgml/custom-scan.sgml b/doc/src/sgml/custom-scan.sgml index a46641674f..24631f5f40 100644 --- a/doc/src/sgml/custom-scan.sgml +++ b/doc/src/sgml/custom-scan.sgml @@ -123,7 +123,7 @@ Plan *(*PlanCustomPath) (PlannerInfo *root, </programlisting> Convert a custom path to a finished plan. The return value will generally be a <literal>CustomScan</literal> object, which the callback must allocate and - initialize. See <xref linkend="custom-scan-plan"> for more details. + initialize. See <xref linkend="custom-scan-plan"/> for more details. </para> </sect2> </sect1> diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 3d46098263..9aa9b28f3e 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -16,11 +16,11 @@ <productname>PostgreSQL</productname> has a rich set of native data types available to users. Users can add new types to <productname>PostgreSQL</productname> using the <xref - linkend="sql-createtype"> command. + linkend="sql-createtype"/> command. </para> <para> - <xref linkend="datatype-table"> shows all the built-in general-purpose data + <xref linkend="datatype-table"/> shows all the built-in general-purpose data types. Most of the alternative names listed in the <quote>Aliases</quote> column are the names used internally by <productname>PostgreSQL</productname> for historical reasons. In @@ -336,7 +336,7 @@ <para> Numeric types consist of two-, four-, and eight-byte integers, four- and eight-byte floating-point numbers, and selectable-precision - decimals. <xref linkend="datatype-numeric-table"> lists the + decimals. <xref linkend="datatype-numeric-table"/> lists the available types. </para> @@ -424,9 +424,9 @@ <para> The syntax of constants for the numeric types is described in - <xref linkend="sql-syntax-constants">. The numeric types have a + <xref linkend="sql-syntax-constants"/>. The numeric types have a full set of corresponding arithmetic operators and - functions. Refer to <xref linkend="functions"> for more + functions. Refer to <xref linkend="functions"/> for more information. The following sections describe the types in detail. </para> @@ -559,7 +559,7 @@ NUMERIC The maximum allowed precision when explicitly specified in the type declaration is 1000; <type>NUMERIC</type> without a specified precision is subject to the limits described in <xref - linkend="datatype-numeric-table">. + linkend="datatype-numeric-table"/>. </para> </note> @@ -728,7 +728,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; <note> <para> - The <xref linkend="guc-extra-float-digits"> setting controls the + The <xref linkend="guc-extra-float-digits"/> setting controls the number of extra significant digits included when a floating point value is converted to text for output. With the default value of <literal>0</literal>, the output is the same on every platform @@ -841,7 +841,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; <para> This section describes a PostgreSQL-specific way to create an autoincrementing column. Another way is to use the SQL-standard - identity column feature, described at <xref linkend="sql-createtable">. + identity column feature, described at <xref linkend="sql-createtable"/>. </para> </note> @@ -888,7 +888,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab from the sequence is still "used up" even if a row containing that value is never successfully inserted into the table column. This may happen, for example, if the inserting transaction rolls back. - See <literal>nextval()</literal> in <xref linkend="functions-sequence"> + See <literal>nextval()</literal> in <xref linkend="functions-sequence"/> for details. </para> </note> @@ -929,8 +929,8 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab <para> The <type>money</type> type stores a currency amount with a fixed fractional precision; see <xref - linkend="datatype-money-table">. The fractional precision is - determined by the database's <xref linkend="guc-lc-monetary"> setting. + linkend="datatype-money-table"/>. The fractional precision is + determined by the database's <xref linkend="guc-lc-monetary"/> setting. The range shown in the table assumes there are two fractional digits. Input is accepted in a variety of formats, including integer and floating-point literals, as well as typical @@ -1063,7 +1063,7 @@ SELECT '52093.89'::money::numeric::float8; </table> <para> - <xref linkend="datatype-character-table"> shows the + <xref linkend="datatype-character-table"/> shows the general-purpose character types available in <productname>PostgreSQL</productname>. </para> @@ -1166,12 +1166,12 @@ SELECT '52093.89'::money::numeric::float8; </tip> <para> - Refer to <xref linkend="sql-syntax-strings"> for information about - the syntax of string literals, and to <xref linkend="functions"> + Refer to <xref linkend="sql-syntax-strings"/> for information about + the syntax of string literals, and to <xref linkend="functions"/> for information about available operators and functions. The database character set determines the character set used to store textual values; for more information on character set support, - refer to <xref linkend="multibyte">. + refer to <xref linkend="multibyte"/>. </para> <example> @@ -1180,7 +1180,7 @@ SELECT '52093.89'::money::numeric::float8; <programlisting> CREATE TABLE test1 (a character(4)); INSERT INTO test1 VALUES ('ok'); -SELECT a, char_length(a) FROM test1; -- <co id="co.datatype-char"> +SELECT a, char_length(a) FROM test1; -- <co id="co.datatype-char"/> <computeroutput> a | char_length ------+------------- @@ -1206,7 +1206,7 @@ SELECT b, char_length(b) FROM test2; <callout arearefs="co.datatype-char"> <para> The <function>char_length</function> function is discussed in - <xref linkend="functions-string">. + <xref linkend="functions-string"/>. </para> </callout> </calloutlist> @@ -1215,7 +1215,7 @@ SELECT b, char_length(b) FROM test2; <para> There are two other fixed-length character types in <productname>PostgreSQL</productname>, shown in <xref - linkend="datatype-character-special-table">. The <type>name</type> + linkend="datatype-character-special-table"/>. The <type>name</type> type exists <emphasis>only</emphasis> for the storage of identifiers in the internal system catalogs and is not intended for use by the general user. Its length is currently defined as 64 bytes (63 usable characters plus @@ -1269,7 +1269,7 @@ SELECT b, char_length(b) FROM test2; <para> The <type>bytea</type> data type allows storage of binary strings; - see <xref linkend="datatype-binary-table">. + see <xref linkend="datatype-binary-table"/>. </para> <table id="datatype-binary-table"> @@ -1313,7 +1313,7 @@ SELECT b, char_length(b) FROM test2; input and output: <productname>PostgreSQL</productname>'s historical <quote>escape</quote> format, and <quote>hex</quote> format. Both of these are always accepted on input. The output format depends - on the configuration parameter <xref linkend="guc-bytea-output">; + on the configuration parameter <xref linkend="guc-bytea-output"/>; the default is hex. (Note that the hex format was introduced in <productname>PostgreSQL</productname> 9.0; earlier versions and some tools don't understand it.) @@ -1384,7 +1384,7 @@ SELECT E'\\xDEADBEEF'; literal using escape string syntax). Backslash itself (octet value 92) can alternatively be represented by double backslashes. - <xref linkend="datatype-binary-sqlesc"> + <xref linkend="datatype-binary-sqlesc"/> shows the characters that must be escaped, and gives the alternative escape sequences where applicable. </para> @@ -1443,14 +1443,14 @@ SELECT E'\\xDEADBEEF'; The requirement to escape <emphasis>non-printable</emphasis> octets varies depending on locale settings. In some instances you can get away with leaving them unescaped. Note that the result in each of the examples - in <xref linkend="datatype-binary-sqlesc"> was exactly one octet in + in <xref linkend="datatype-binary-sqlesc"/> was exactly one octet in length, even though the output representation is sometimes more than one character. </para> <para> The reason multiple backslashes are required, as shown - in <xref linkend="datatype-binary-sqlesc">, is that an input + in <xref linkend="datatype-binary-sqlesc"/>, is that an input string written as a string literal must pass through two parse phases in the <productname>PostgreSQL</productname> server. The first backslash of each pair is interpreted as an escape @@ -1467,7 +1467,7 @@ SELECT E'\\xDEADBEEF'; to a single octet with a decimal value of 1. Note that the single-quote character is not treated specially by <type>bytea</type>, so it follows the normal rules for string literals. (See also - <xref linkend="sql-syntax-strings">.) + <xref linkend="sql-syntax-strings"/>.) </para> <para> @@ -1477,7 +1477,7 @@ SELECT E'\\xDEADBEEF'; Most <quote>printable</quote> octets are represented by their standard representation in the client character set. The octet with decimal value 92 (backslash) is doubled in the output. - Details are in <xref linkend="datatype-binary-resesc">. + Details are in <xref linkend="datatype-binary-resesc"/>. </para> <table id="datatype-binary-resesc"> @@ -1571,12 +1571,12 @@ SELECT E'\\xDEADBEEF'; <para> <productname>PostgreSQL</productname> supports the full set of <acronym>SQL</acronym> date and time types, shown in <xref - linkend="datatype-datetime-table">. The operations available + linkend="datatype-datetime-table"/>. The operations available on these data types are described in - <xref linkend="functions-datetime">. + <xref linkend="functions-datetime"/>. Dates are counted according to the Gregorian calendar, even in years before that calendar was introduced (see <xref - linkend="datetime-units-history"> for more information). + linkend="datetime-units-history"/> for more information). </para> <table id="datatype-datetime-table"> @@ -1716,7 +1716,7 @@ MINUTE TO SECOND traditional <productname>POSTGRES</productname>, and others. For some formats, ordering of day, month, and year in date input is ambiguous and there is support for specifying the expected - ordering of these fields. Set the <xref linkend="guc-datestyle"> parameter + ordering of these fields. Set the <xref linkend="guc-datestyle"/> parameter to <literal>MDY</literal> to select month-day-year interpretation, <literal>DMY</literal> to select day-month-year interpretation, or <literal>YMD</literal> to select year-month-day interpretation. @@ -1726,7 +1726,7 @@ MINUTE TO SECOND <productname>PostgreSQL</productname> is more flexible in handling date/time input than the <acronym>SQL</acronym> standard requires. - See <xref linkend="datetime-appendix"> + See <xref linkend="datetime-appendix"/> for the exact parsing rules of date/time input and for the recognized text fields including months, days of the week, and time zones. @@ -1735,7 +1735,7 @@ MINUTE TO SECOND <para> Remember that any date or time literal input needs to be enclosed in single quotes, like text strings. Refer to - <xref linkend="sql-syntax-constants-generic"> for more + <xref linkend="sql-syntax-constants-generic"/> for more information. <acronym>SQL</acronym> requires the following syntax <synopsis> @@ -1759,7 +1759,7 @@ MINUTE TO SECOND </indexterm> <para> - <xref linkend="datatype-datetime-date-table"> shows some possible + <xref linkend="datatype-datetime-date-table"/> shows some possible inputs for the <type>date</type> type. </para> @@ -1872,8 +1872,8 @@ MINUTE TO SECOND <para> Valid input for these types consists of a time of day followed by an optional time zone. (See <xref - linkend="datatype-datetime-time-table"> - and <xref linkend="datatype-timezone-table">.) If a time zone is + linkend="datatype-datetime-time-table"/> + and <xref linkend="datatype-timezone-table"/>.) If a time zone is specified in the input for <type>time without time zone</type>, it is silently ignored. You can also specify a date but it will be ignored, except when you use a time zone name that involves a @@ -1993,7 +1993,7 @@ MINUTE TO SECOND </table> <para> - Refer to <xref linkend="datatype-timezones"> for more information on how + Refer to <xref linkend="datatype-timezones"/> for more information on how to specify time zones. </para> </sect3> @@ -2074,7 +2074,7 @@ January 8 04:05:06 1999 PST time zone specified is converted to UTC using the appropriate offset for that time zone. If no time zone is stated in the input string, then it is assumed to be in the time zone indicated by the system's - <xref linkend="guc-timezone"> parameter, and is converted to UTC using the + <xref linkend="guc-timezone"/> parameter, and is converted to UTC using the offset for the <varname>timezone</varname> zone. </para> @@ -2084,7 +2084,7 @@ January 8 04:05:06 1999 PST current <varname>timezone</varname> zone, and displayed as local time in that zone. To see the time in another time zone, either change <varname>timezone</varname> or use the <literal>AT TIME ZONE</literal> construct - (see <xref linkend="functions-datetime-zoneconvert">). + (see <xref linkend="functions-datetime-zoneconvert"/>). </para> <para> @@ -2112,7 +2112,7 @@ January 8 04:05:06 1999 PST <para> <productname>PostgreSQL</productname> supports several special date/time input values for convenience, as shown in <xref - linkend="datatype-datetime-special-table">. The values + linkend="datatype-datetime-special-table"/>. The values <literal>infinity</literal> and <literal>-infinity</literal> are specially represented inside the system and will be displayed unchanged; but the others are simply notational shorthands @@ -2186,7 +2186,7 @@ January 8 04:05:06 1999 PST <literal>CURRENT_TIMESTAMP</literal>, <literal>LOCALTIME</literal>, <literal>LOCALTIMESTAMP</literal>. The latter four accept an optional subsecond precision specification. (See <xref - linkend="functions-datetime-current">.) Note that these are + linkend="functions-datetime-current"/>.) Note that these are SQL functions and are <emphasis>not</emphasis> recognized in data input strings. </para> @@ -2218,7 +2218,7 @@ January 8 04:05:06 1999 PST <acronym>SQL</acronym> standard requires the use of the ISO 8601 format. The name of the <quote>SQL</quote> output format is a historical accident.) <xref - linkend="datatype-datetime-output-table"> shows examples of each + linkend="datatype-datetime-output-table"/> shows examples of each output style. The output of the <type>date</type> and <type>time</type> types is generally only the date or time part in accordance with the given examples. However, the @@ -2275,9 +2275,9 @@ January 8 04:05:06 1999 PST In the <acronym>SQL</acronym> and POSTGRES styles, day appears before month if DMY field ordering has been specified, otherwise month appears before day. - (See <xref linkend="datatype-datetime-input"> + (See <xref linkend="datatype-datetime-input"/> for how this setting also affects interpretation of input values.) - <xref linkend="datatype-datetime-output2-table"> shows examples. + <xref linkend="datatype-datetime-output2-table"/> shows examples. </para> <table id="datatype-datetime-output2-table"> @@ -2313,7 +2313,7 @@ January 8 04:05:06 1999 PST <para> The date/time style can be selected by the user using the <command>SET datestyle</command> command, the <xref - linkend="guc-datestyle"> parameter in the + linkend="guc-datestyle"/> parameter in the <filename>postgresql.conf</filename> configuration file, or the <envar>PGDATESTYLE</envar> environment variable on the server or client. @@ -2321,7 +2321,7 @@ January 8 04:05:06 1999 PST <para> The formatting function <function>to_char</function> - (see <xref linkend="functions-formatting">) is also available as + (see <xref linkend="functions-formatting"/>) is also available as a more flexible way to format date/time output. </para> </sect2> @@ -2391,7 +2391,7 @@ January 8 04:05:06 1999 PST <para> All timezone-aware dates and times are stored internally in <acronym>UTC</acronym>. They are converted to local time - in the zone specified by the <xref linkend="guc-timezone"> configuration + in the zone specified by the <xref linkend="guc-timezone"/> configuration parameter before being displayed to the client. </para> @@ -2404,7 +2404,7 @@ January 8 04:05:06 1999 PST A full time zone name, for example <literal>America/New_York</literal>. The recognized time zone names are listed in the <literal>pg_timezone_names</literal> view (see <xref - linkend="view-pg-timezone-names">). + linkend="view-pg-timezone-names"/>). <productname>PostgreSQL</productname> uses the widely-used IANA time zone data for this purpose, so the same time zone names are also recognized by much other software. @@ -2417,9 +2417,9 @@ January 8 04:05:06 1999 PST contrast to full time zone names which can imply a set of daylight savings transition-date rules as well. The recognized abbreviations are listed in the <literal>pg_timezone_abbrevs</literal> view (see <xref - linkend="view-pg-timezone-abbrevs">). You cannot set the - configuration parameters <xref linkend="guc-timezone"> or - <xref linkend="guc-log-timezone"> to a time + linkend="view-pg-timezone-abbrevs"/>). You cannot set the + configuration parameters <xref linkend="guc-timezone"/> or + <xref linkend="guc-log-timezone"/> to a time zone abbreviation, but you can use abbreviations in date/time input values and with the <literal>AT TIME ZONE</literal> operator. @@ -2499,13 +2499,13 @@ January 8 04:05:06 1999 PST they are obtained from configuration files stored under <filename>.../share/timezone/</filename> and <filename>.../share/timezonesets/</filename> of the installation directory - (see <xref linkend="datetime-config-files">). + (see <xref linkend="datetime-config-files"/>). </para> <para> - The <xref linkend="guc-timezone"> configuration parameter can + The <xref linkend="guc-timezone"/> configuration parameter can be set in the file <filename>postgresql.conf</filename>, or in any of the - other standard ways described in <xref linkend="runtime-config">. + other standard ways described in <xref linkend="runtime-config"/>. There are also some special ways to set it: <itemizedlist> @@ -2556,7 +2556,7 @@ January 8 04:05:06 1999 PST of the different units are implicitly added with appropriate sign accounting. <literal>ago</literal> negates all the fields. This syntax is also used for interval output, if - <xref linkend="guc-intervalstyle"> is set to + <xref linkend="guc-intervalstyle"/> is set to <literal>postgres_verbose</literal>. </para> @@ -2582,7 +2582,7 @@ P <replaceable>quantity</replaceable> <replaceable>unit</replaceable> <optional> The string must start with a <literal>P</literal>, and may include a <literal>T</literal> that introduces the time-of-day units. The available unit abbreviations are given in <xref - linkend="datatype-interval-iso8601-units">. Units may be + linkend="datatype-interval-iso8601-units"/>. Units may be omitted, and may be specified in any order, but units smaller than a day must appear after <literal>T</literal>. In particular, the meaning of <literal>M</literal> depends on whether it is before or after @@ -2696,7 +2696,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>- </para> <para> - <xref linkend="datatype-interval-input-examples"> shows some examples + <xref linkend="datatype-interval-input-examples"/> shows some examples of valid <type>interval</type> input. </para> @@ -2751,7 +2751,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>- <literal>postgres_verbose</literal>, or <literal>iso_8601</literal>, using the command <literal>SET intervalstyle</literal>. The default is the <literal>postgres</literal> format. - <xref linkend="interval-style-output-table"> shows examples of each + <xref linkend="interval-style-output-table"/> shows examples of each output style. </para> @@ -2768,7 +2768,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>- <para> The output of the <literal>postgres</literal> style matches the output of <productname>PostgreSQL</productname> releases prior to 8.4 when the - <xref linkend="guc-datestyle"> parameter was set to <literal>ISO</literal>. + <xref linkend="guc-datestyle"/> parameter was set to <literal>ISO</literal>. </para> <para> @@ -2846,7 +2846,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>- <para> <productname>PostgreSQL</productname> provides the standard <acronym>SQL</acronym> type <type>boolean</type>; - see <xref linkend="datatype-boolean-table">. + see <xref linkend="datatype-boolean-table"/>. The <type>boolean</type> type can have several states: <quote>true</quote>, <quote>false</quote>, and a third state, <quote>unknown</quote>, which is represented by the @@ -2902,7 +2902,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>- </para> <para> - <xref linkend="datatype-boolean-example"> shows that + <xref linkend="datatype-boolean-example"/> shows that <type>boolean</type> values are output using the letters <literal>t</literal> and <literal>f</literal>. </para> @@ -2954,7 +2954,7 @@ SELECT * FROM test1 WHERE a; <para> Enum types are created using the <xref - linkend="sql-createtype"> command, + linkend="sql-createtype"/> command, for example: <programlisting> @@ -3087,7 +3087,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <para> Geometric data types represent two-dimensional spatial - objects. <xref linkend="datatype-geo-table"> shows the geometric + objects. <xref linkend="datatype-geo-table"/> shows the geometric types available in <productname>PostgreSQL</productname>. </para> @@ -3158,7 +3158,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <para> A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining - intersections. They are explained in <xref linkend="functions-geometry">. + intersections. They are explained in <xref linkend="functions-geometry"/>. </para> <sect2> @@ -3410,11 +3410,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <para> <productname>PostgreSQL</productname> offers data types to store IPv4, IPv6, and MAC - addresses, as shown in <xref linkend="datatype-net-types-table">. It + addresses, as shown in <xref linkend="datatype-net-types-table"/>. It is better to use these types instead of plain text types to store network addresses, because these types offer input error checking and specialized - operators and functions (see <xref linkend="functions-net">). + operators and functions (see <xref linkend="functions-net"/>). </para> <table tocentry="1" id="datatype-net-types-table"> @@ -3526,7 +3526,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays </para> <para> - <xref linkend="datatype-net-cidr-table"> shows some examples. + <xref linkend="datatype-net-cidr-table"/> shows some examples. </para> <table id="datatype-net-cidr-table"> @@ -3809,10 +3809,10 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); <para> Refer to <xref - linkend="sql-syntax-bit-strings"> for information about the syntax + linkend="sql-syntax-bit-strings"/> for information about the syntax of bit string constants. Bit-logical operators and string manipulation functions are available; see <xref - linkend="functions-bitstring">. + linkend="functions-bitstring"/>. </para> <example> @@ -3840,7 +3840,7 @@ SELECT * FROM test; A bit string value requires 1 byte for each group of 8 bits, plus 5 or 8 bytes overhead depending on the length of the string (but long values may be compressed or moved out-of-line, as explained - in <xref linkend="datatype-character"> for character strings). + in <xref linkend="datatype-character"/> for character strings). </para> </sect1> @@ -3865,8 +3865,8 @@ SELECT * FROM test; The <type>tsvector</type> type represents a document in a form optimized for text search; the <type>tsquery</type> type similarly represents a text query. - <xref linkend="textsearch"> provides a detailed explanation of this - facility, and <xref linkend="functions-textsearch"> summarizes the + <xref linkend="textsearch"/> provides a detailed explanation of this + facility, and <xref linkend="functions-textsearch"/> summarizes the related functions and operators. </para> @@ -3881,7 +3881,7 @@ SELECT * FROM test; A <type>tsvector</type> value is a sorted list of distinct <firstterm>lexemes</firstterm>, which are words that have been <firstterm>normalized</firstterm> to merge different variants of the same word - (see <xref linkend="textsearch"> for details). Sorting and + (see <xref linkend="textsearch"/> for details). Sorting and duplicate-elimination are done automatically during input, as shown in this example: @@ -3975,7 +3975,7 @@ SELECT to_tsvector('english', 'The Fat Rats'); 'fat':2 'rat':3 </programlisting> - Again, see <xref linkend="textsearch"> for more detail. + Again, see <xref linkend="textsearch"/> for more detail. </para> </sect2> @@ -4140,9 +4140,9 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 functions for UUIDs, but the core database does not include any function for generating UUIDs, because no single algorithm is well suited for every application. The <xref - linkend="uuid-ossp"> module + linkend="uuid-ossp"/> module provides functions that implement several standard algorithms. - The <xref linkend="pgcrypto"> module also provides a generation + The <xref linkend="pgcrypto"/> module also provides a generation function for random UUIDs. Alternatively, UUIDs could be generated by client applications or other libraries invoked through a server-side function. @@ -4161,7 +4161,7 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 advantage over storing XML data in a <type>text</type> field is that it checks the input values for well-formedness, and there are support functions to perform type-safe operations on it; see <xref - linkend="functions-xml">. Use of this data type requires the + linkend="functions-xml"/>. Use of this data type requires the installation to have been built with <command>configure --with-libxml</command>. </para> @@ -4267,7 +4267,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; results to the client (which is the normal mode), PostgreSQL converts all character data passed between the client and the server and vice versa to the character encoding of the respective - end; see <xref linkend="multibyte">. This includes string + end; see <xref linkend="multibyte"/>. This includes string representations of XML values, such as in the above examples. This would ordinarily mean that encoding declarations contained in XML data can become invalid as the character data is converted @@ -4408,7 +4408,7 @@ INSERT INTO mytable VALUES(-1); -- fails </para> <para> - For additional information see <xref linkend="sql-createdomain">. + For additional information see <xref linkend="sql-createdomain"/>. </para> </sect1> @@ -4473,14 +4473,14 @@ INSERT INTO mytable VALUES(-1); -- fails <productname>PostgreSQL</productname> as primary keys for various system tables. OIDs are not added to user-created tables, unless <literal>WITH OIDS</literal> is specified when the table is - created, or the <xref linkend="guc-default-with-oids"> + created, or the <xref linkend="guc-default-with-oids"/> configuration variable is enabled. Type <type>oid</type> represents an object identifier. There are also several alias types for <type>oid</type>: <type>regproc</type>, <type>regprocedure</type>, <type>regoper</type>, <type>regoperator</type>, <type>regclass</type>, <type>regtype</type>, <type>regrole</type>, <type>regnamespace</type>, <type>regconfig</type>, and <type>regdictionary</type>. - <xref linkend="datatype-oid-table"> shows an overview. + <xref linkend="datatype-oid-table"/> shows an overview. </para> <para> @@ -4677,7 +4677,7 @@ SELECT * FROM pg_attribute <para> (The system columns are further explained in <xref - linkend="ddl-system-columns">.) + linkend="ddl-system-columns"/>.) </para> </sect1> @@ -4795,7 +4795,7 @@ SELECT * FROM pg_attribute useful in situations where a function's behavior does not correspond to simply taking or returning a value of a specific <acronym>SQL</acronym> data type. <xref - linkend="datatype-pseudotypes-table"> lists the existing + linkend="datatype-pseudotypes-table"/> lists the existing pseudo-types. </para> @@ -4818,33 +4818,33 @@ SELECT * FROM pg_attribute <row> <entry><type>anyelement</type></entry> <entry>Indicates that a function accepts any data type - (see <xref linkend="extend-types-polymorphic">).</entry> + (see <xref linkend="extend-types-polymorphic"/>).</entry> </row> <row> <entry><type>anyarray</type></entry> <entry>Indicates that a function accepts any array data type - (see <xref linkend="extend-types-polymorphic">).</entry> + (see <xref linkend="extend-types-polymorphic"/>).</entry> </row> <row> <entry><type>anynonarray</type></entry> <entry>Indicates that a function accepts any non-array data type - (see <xref linkend="extend-types-polymorphic">).</entry> + (see <xref linkend="extend-types-polymorphic"/>).</entry> </row> <row> <entry><type>anyenum</type></entry> <entry>Indicates that a function accepts any enum data type - (see <xref linkend="extend-types-polymorphic"> and - <xref linkend="datatype-enum">).</entry> + (see <xref linkend="extend-types-polymorphic"/> and + <xref linkend="datatype-enum"/>).</entry> </row> <row> <entry><type>anyrange</type></entry> <entry>Indicates that a function accepts any range data type - (see <xref linkend="extend-types-polymorphic"> and - <xref linkend="rangetypes">).</entry> + (see <xref linkend="extend-types-polymorphic"/> and + <xref linkend="rangetypes"/>).</entry> </row> <row> diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index a533bbf8d2..d269aa4cc5 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -180,7 +180,7 @@ <title>Date/Time Key Words</title> <para> - <xref linkend="datetime-month-table"> shows the tokens that are + <xref linkend="datetime-month-table"/> shows the tokens that are recognized as names of months. </para> @@ -247,7 +247,7 @@ </table> <para> - <xref linkend="datetime-dow-table"> shows the tokens that are + <xref linkend="datetime-dow-table"/> shows the tokens that are recognized as names of days of the week. </para> @@ -294,7 +294,7 @@ </table> <para> - <xref linkend="datetime-mod-table"> shows the tokens that serve + <xref linkend="datetime-mod-table"/> shows the tokens that serve various modifier purposes. </para> @@ -349,7 +349,7 @@ Since timezone abbreviations are not well standardized, <productname>PostgreSQL</productname> provides a means to customize the set of abbreviations accepted by the server. The - <xref linkend="guc-timezone-abbreviations"> run-time parameter + <xref linkend="guc-timezone-abbreviations"/> run-time parameter determines the active set of abbreviations. While this parameter can be altered by any database user, the possible values for it are under the control of the database administrator — they diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index 12928e8bd3..4c07f886aa 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -14,7 +14,7 @@ </para> <para> - See also <xref linkend="postgres-fdw">, which provides roughly the same + See also <xref linkend="postgres-fdw"/>, which provides roughly the same functionality using a more modern and standards-compliant infrastructure. </para> @@ -58,8 +58,8 @@ dblink_connect(text connname, text connstr) returns text server. It is recommended to use the foreign-data wrapper <literal>dblink_fdw</literal> when defining the foreign server. See the example below, as well as - <xref linkend="sql-createserver"> and - <xref linkend="sql-createusermapping">. + <xref linkend="sql-createserver"/> and + <xref linkend="sql-createusermapping"/>. </para> </refsect1> @@ -84,7 +84,7 @@ dblink_connect(text connname, text connstr) returns text <para><application>libpq</application>-style connection info string, for example <literal>hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd</literal>. - For details see <xref linkend="libpq-connstring">. + For details see <xref linkend="libpq-connstring"/>. Alternatively, the name of a foreign server. </para> </listitem> @@ -1340,7 +1340,7 @@ dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, ex the unnamed connection, or on a named connection if specified. To receive notifications via dblink, <function>LISTEN</function> must first be issued, using <function>dblink_exec</function>. - For details see <xref linkend="sql-listen"> and <xref linkend="sql-notify">. + For details see <xref linkend="sql-listen"/> and <xref linkend="sql-notify"/>. </para> </refsect1> diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index daba66c187..e6f50ec819 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -39,7 +39,7 @@ SQL does not make any guarantees about the order of the rows in a table. When a table is read, the rows will appear in an unspecified order, unless sorting is explicitly requested. This is covered in <xref - linkend="queries">. Furthermore, SQL does not assign unique + linkend="queries"/>. Furthermore, SQL does not assign unique identifiers to rows, so it is possible to have several completely identical rows in a table. This is a consequence of the mathematical model that underlies SQL but is usually not desirable. @@ -64,7 +64,7 @@ built-in data types that fit many applications. Users can also define their own data types. Most built-in data types have obvious names and semantics, so we defer a detailed explanation to <xref - linkend="datatype">. Some of the frequently used data types are + linkend="datatype"/>. Some of the frequently used data types are <type>integer</type> for whole numbers, <type>numeric</type> for possibly fractional numbers, <type>text</type> for character strings, <type>date</type> for dates, <type>time</type> for @@ -79,7 +79,7 @@ <para> To create a table, you use the aptly named <xref - linkend="sql-createtable"> command. + linkend="sql-createtable"/> command. In this command you specify at least a name for the new table, the names of the columns and the data type of each column. For example: @@ -95,7 +95,7 @@ CREATE TABLE my_first_table ( <type>text</type>; the second column has the name <literal>second_column</literal> and the type <type>integer</type>. The table and column names follow the identifier syntax explained - in <xref linkend="sql-syntax-identifiers">. The type names are + in <xref linkend="sql-syntax-identifiers"/>. The type names are usually also identifiers, but there are some exceptions. Note that the column list is comma-separated and surrounded by parentheses. </para> @@ -139,7 +139,7 @@ CREATE TABLE products ( <para> If you no longer need a table, you can remove it using the <xref - linkend="sql-droptable"> command. + linkend="sql-droptable"/> command. For example: <programlisting> DROP TABLE my_first_table; @@ -155,7 +155,7 @@ DROP TABLE products; <para> If you need to modify a table that already exists, see <xref - linkend="ddl-alter"> later in this chapter. + linkend="ddl-alter"/> later in this chapter. </para> <para> @@ -163,7 +163,7 @@ DROP TABLE products; tables. The remainder of this chapter is concerned with adding features to the table definition to ensure data integrity, security, or convenience. If you are eager to fill your tables with - data now you can skip ahead to <xref linkend="dml"> and read the + data now you can skip ahead to <xref linkend="dml"/> and read the rest of this chapter later. </para> </sect1> @@ -181,7 +181,7 @@ DROP TABLE products; columns will be filled with their respective default values. A data manipulation command can also request explicitly that a column be set to its default value, without having to know what that value is. - (Details about data manipulation commands are in <xref linkend="dml">.) + (Details about data manipulation commands are in <xref linkend="dml"/>.) </para> <para> @@ -220,7 +220,7 @@ CREATE TABLE products ( </programlisting> where the <literal>nextval()</literal> function supplies successive values from a <firstterm>sequence object</firstterm> (see <xref - linkend="functions-sequence">). This arrangement is sufficiently common + linkend="functions-sequence"/>). This arrangement is sufficiently common that there's a special shorthand for it: <programlisting> CREATE TABLE products ( @@ -229,7 +229,7 @@ CREATE TABLE products ( ); </programlisting> The <literal>SERIAL</literal> shorthand is discussed further in <xref - linkend="datatype-serial">. + linkend="datatype-serial"/>. </para> </sect1> @@ -876,9 +876,9 @@ CREATE TABLE order_items ( <para> More information about updating and deleting data is in <xref - linkend="dml">. Also see the description of foreign key constraint + linkend="dml"/>. Also see the description of foreign key constraint syntax in the reference documentation for - <xref linkend="sql-createtable">. + <xref linkend="sql-createtable"/>. </para> </sect2> @@ -948,10 +948,10 @@ CREATE TABLE circles ( </indexterm> The object identifier (object ID) of a row. This column is only present if the table was created using <literal>WITH - OIDS</literal>, or if the <xref linkend="guc-default-with-oids"> + OIDS</literal>, or if the <xref linkend="guc-default-with-oids"/> configuration variable was set at the time. This column is of type <type>oid</type> (same name as the column); see <xref - linkend="datatype-oid"> for more information about the type. + linkend="datatype-oid"/> for more information about the type. </para> </listitem> </varlistentry> @@ -966,7 +966,7 @@ CREATE TABLE circles ( <para> The OID of the table containing this row. This column is particularly handy for queries that select from inheritance - hierarchies (see <xref linkend="ddl-inherit">), since without it, + hierarchies (see <xref linkend="ddl-inherit"/>), since without it, it's difficult to tell which individual table a row came from. The <structfield>tableoid</structfield> can be joined against the <structfield>oid</structfield> column of @@ -1100,7 +1100,7 @@ CREATE TABLE circles ( Transaction identifiers are also 32-bit quantities. In a long-lived database it is possible for transaction IDs to wrap around. This is not a fatal problem given appropriate maintenance - procedures; see <xref linkend="maintenance"> for details. It is + procedures; see <xref linkend="maintenance"/> for details. It is unwise, however, to depend on the uniqueness of transaction IDs over the long term (more than one billion transactions). </para> @@ -1167,7 +1167,7 @@ CREATE TABLE circles ( </itemizedlist> All these actions are performed using the - <xref linkend="sql-altertable"> + <xref linkend="sql-altertable"/> command, whose reference page contains details beyond those given here. </para> @@ -1238,7 +1238,7 @@ ALTER TABLE products DROP COLUMN description; <programlisting> ALTER TABLE products DROP COLUMN description CASCADE; </programlisting> - See <xref linkend="ddl-depend"> for a description of the general + See <xref linkend="ddl-depend"/> for a description of the general mechanism behind this. </para> </sect2> @@ -1446,7 +1446,7 @@ ALTER TABLE products RENAME TO items; object vary depending on the object's type (table, function, etc). For complete information on the different types of privileges supported by <productname>PostgreSQL</productname>, refer to the - <xref linkend="sql-grant"> reference + <xref linkend="sql-grant"/> reference page. The following sections and chapters will also show you how those privileges are used. </para> @@ -1459,7 +1459,7 @@ ALTER TABLE products RENAME TO items; <para> An object can be assigned to a new owner with an <command>ALTER</command> command of the appropriate kind for the object, e.g. <xref - linkend="sql-altertable">. Superusers can always do + linkend="sql-altertable"/>. Superusers can always do this; ordinary roles can only do it if they are both the current owner of the object (or a member of the owning role) and a member of the new owning role. @@ -1482,7 +1482,7 @@ GRANT UPDATE ON accounts TO joe; be used to grant a privilege to every role on the system. Also, <quote>group</quote> roles can be set up to help manage privileges when there are many users of a database — for details see - <xref linkend="user-manag">. + <xref linkend="user-manag"/>. </para> <para> @@ -1506,8 +1506,8 @@ REVOKE ALL ON accounts FROM PUBLIC; the right to grant it in turn to others. If the grant option is subsequently revoked then all who received the privilege from that recipient (directly or through a chain of grants) will lose the - privilege. For details see the <xref linkend="sql-grant"> and - <xref linkend="sql-revoke"> reference pages. + privilege. For details see the <xref linkend="sql-grant"/> and + <xref linkend="sql-revoke"/> reference pages. </para> </sect1> @@ -1524,7 +1524,7 @@ REVOKE ALL ON accounts FROM PUBLIC; <para> In addition to the SQL-standard <link linkend="ddl-priv">privilege - system</link> available through <xref linkend="sql-grant">, + system</link> available through <xref linkend="sql-grant"/>, tables can have <firstterm>row security policies</firstterm> that restrict, on a per-user basis, which rows can be returned by normal queries or inserted, updated, or deleted by data modification commands. @@ -1584,11 +1584,11 @@ REVOKE ALL ON accounts FROM PUBLIC; </para> <para> - Policies are created using the <xref linkend="sql-createpolicy"> - command, altered using the <xref linkend="sql-alterpolicy"> command, - and dropped using the <xref linkend="sql-droppolicy"> command. To + Policies are created using the <xref linkend="sql-createpolicy"/> + command, altered using the <xref linkend="sql-alterpolicy"/> command, + and dropped using the <xref linkend="sql-droppolicy"/> command. To enable and disable row security for a given table, use the - <xref linkend="sql-altertable"> command. + <xref linkend="sql-altertable"/> command. </para> <para> @@ -1829,7 +1829,7 @@ UPDATE 0 not being applied. For example, when taking a backup, it could be disastrous if row security silently caused some rows to be omitted from the backup. In such a situation, you can set the - <xref linkend="guc-row-security"> configuration parameter + <xref linkend="guc-row-security"/> configuration parameter to <literal>off</literal>. This does not in itself bypass row security; what it does is throw an error if any query's results would get filtered by a policy. The reason for the error can then be investigated and @@ -1951,8 +1951,8 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE; </para> <para> - For additional details see <xref linkend="sql-createpolicy"> - and <xref linkend="sql-altertable">. + For additional details see <xref linkend="sql-createpolicy"/> + and <xref linkend="sql-altertable"/>. </para> </sect1> @@ -2034,7 +2034,7 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE; </indexterm> <para> - To create a schema, use the <xref linkend="sql-createschema"> + To create a schema, use the <xref linkend="sql-createschema"/> command. Give the schema a name of your choice. For example: <programlisting> @@ -2099,7 +2099,7 @@ DROP SCHEMA myschema; <programlisting> DROP SCHEMA myschema CASCADE; </programlisting> - See <xref linkend="ddl-depend"> for a description of the general + See <xref linkend="ddl-depend"/> for a description of the general mechanism behind this. </para> @@ -2112,7 +2112,7 @@ CREATE SCHEMA <replaceable>schema_name</replaceable> AUTHORIZATION <replaceable> </programlisting> You can even omit the schema name, in which case the schema name will be the same as the user name. See <xref - linkend="ddl-schemas-patterns"> for how this can be useful. + linkend="ddl-schemas-patterns"/> for how this can be useful. </para> <para> @@ -2242,7 +2242,7 @@ SET search_path TO myschema; </para> <para> - See also <xref linkend="functions-info"> for other ways to manipulate + See also <xref linkend="functions-info"/> for other ways to manipulate the schema search path. </para> @@ -2297,7 +2297,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC; <quote>public</quote> means <quote>every user</quote>. In the first sense it is an identifier, in the second sense it is a key word, hence the different capitalization; recall the - guidelines from <xref linkend="sql-syntax-identifiers">.) + guidelines from <xref linkend="sql-syntax-identifiers"/>.) </para> </sect2> @@ -2483,7 +2483,7 @@ SELECT name, altitude </programlisting> Given the sample data from the <productname>PostgreSQL</productname> - tutorial (see <xref linkend="tutorial-sql-intro">), this returns: + tutorial (see <xref linkend="tutorial-sql-intro"/>), this returns: <programlisting> name | altitude @@ -2602,7 +2602,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); <structname>capitals</structname> table, but this does not happen: <command>INSERT</command> always inserts into exactly the table specified. In some cases it is possible to redirect the insertion - using a rule (see <xref linkend="rules">). However that does not + using a rule (see <xref linkend="rules"/>). However that does not help for the above case because the <structname>cities</structname> table does not contain the column <structfield>state</structfield>, and so the command will be rejected before the rule can be applied. @@ -2633,11 +2633,11 @@ VALUES ('Albany', NULL, NULL, 'NY'); <para> Table inheritance is typically established when the child table is created, using the <literal>INHERITS</literal> clause of the - <xref linkend="sql-createtable"> + <xref linkend="sql-createtable"/> statement. Alternatively, a table which is already defined in a compatible way can have a new parent relationship added, using the <literal>INHERIT</literal> - variant of <xref linkend="sql-altertable">. + variant of <xref linkend="sql-altertable"/>. To do this the new child table must already include columns with the same names and types as the columns of the parent. It must also include check constraints with the same names and check expressions as those of the @@ -2645,7 +2645,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); <literal>NO INHERIT</literal> variant of <command>ALTER TABLE</command>. Dynamically adding and removing inheritance links like this can be useful when the inheritance relationship is being used for table - partitioning (see <xref linkend="ddl-partitioning">). + partitioning (see <xref linkend="ddl-partitioning"/>). </para> <para> @@ -2665,11 +2665,11 @@ VALUES ('Albany', NULL, NULL, 'NY'); if they are inherited from any parent tables. If you wish to remove a table and all of its descendants, one easy way is to drop the parent table with the - <literal>CASCADE</literal> option (see <xref linkend="ddl-depend">). + <literal>CASCADE</literal> option (see <xref linkend="ddl-depend"/>). </para> <para> - <xref linkend="sql-altertable"> will + <xref linkend="sql-altertable"/> will propagate any changes in column data definitions and check constraints down the inheritance hierarchy. Again, dropping columns that are depended on by other tables is only possible when using @@ -2687,7 +2687,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); that the data is (also) in the parent table. But the <structname>capitals</structname> table could not be updated directly without an additional grant. In a similar way, the parent table's row - security policies (see <xref linkend="ddl-rowsecurity">) are applied to + security policies (see <xref linkend="ddl-rowsecurity"/>) are applied to rows coming from child tables during an inherited query. A child table's policies, if any, are applied only when it is the table explicitly named in the query; and in that case, any policies attached to its parent(s) are @@ -2695,7 +2695,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); </para> <para> - Foreign tables (see <xref linkend="ddl-foreign-data">) can also + Foreign tables (see <xref linkend="ddl-foreign-data"/>) can also be part of inheritance hierarchies, either as parent or child tables, just as regular tables can be. If a foreign table is part of an inheritance hierarchy then any operations not supported by @@ -2719,7 +2719,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); typically only work on individual, physical tables and do not support recursing over inheritance hierarchies. The respective behavior of each individual command is documented in its reference - page (<xref linkend="sql-commands">). + page (<xref linkend="sql-commands"/>). </para> <para> @@ -2923,7 +2923,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); called <firstterm>sub-partitioning</firstterm>. Partitions may have their own indexes, constraints and default values, distinct from those of other partitions. Indexes must be created separately for each partition. See - <xref linkend="sql-createtable"> for more details on creating partitioned + <xref linkend="sql-createtable"/> for more details on creating partitioned tables and partitions. </para> @@ -2932,7 +2932,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); vice versa. However, it is possible to add a regular or partitioned table containing data as a partition of a partitioned table, or remove a partition from a partitioned table turning it into a standalone table; - see <xref linkend="sql-altertable"> to learn more about the + see <xref linkend="sql-altertable"/> to learn more about the <command>ATTACH PARTITION</command> and <command>DETACH PARTITION</command> sub-commands. </para> @@ -2948,7 +2948,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); inheritance with regular tables. Since a partition hierarchy consisting of the partitioned table and its partitions is still an inheritance hierarchy, all the normal rules of inheritance apply as described in - <xref linkend="ddl-inherit"> with some exceptions, most notably: + <xref linkend="ddl-inherit"/> with some exceptions, most notably: <itemizedlist> <listitem> @@ -2999,7 +2999,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); <para> Partitions can also be foreign tables - (see <xref linkend="sql-createforeigntable">), + (see <xref linkend="sql-createforeigntable"/>), although these have some limitations that normal tables do not. For example, data inserted into the partitioned table is not routed to foreign table partitions. @@ -3158,7 +3158,7 @@ CREATE INDEX ON measurement_y2008m01 (logdate); <listitem> <para> - Ensure that the <xref linkend="guc-constraint-exclusion"> + Ensure that the <xref linkend="guc-constraint-exclusion"/> configuration parameter is not disabled in <filename>postgresql.conf</filename>. If it is, queries will not be optimized as desired. </para> @@ -3595,7 +3595,7 @@ DO INSTEAD <listitem> <para> - Ensure that the <xref linkend="guc-constraint-exclusion"> + Ensure that the <xref linkend="guc-constraint-exclusion"/> configuration parameter is not disabled in <filename>postgresql.conf</filename>. If it is, queries will not be optimized as desired. @@ -3806,7 +3806,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; <para> The default (and recommended) setting of - <xref linkend="guc-constraint-exclusion"> is actually neither + <xref linkend="guc-constraint-exclusion"/> is actually neither <literal>on</literal> nor <literal>off</literal>, but an intermediate setting called <literal>partition</literal>, which causes the technique to be applied only to queries that are likely to be working on partitioned @@ -3889,10 +3889,10 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; library that can communicate with an external data source, hiding the details of connecting to the data source and obtaining data from it. There are some foreign data wrappers available as <filename>contrib</filename> - modules; see <xref linkend="contrib">. Other kinds of foreign data + modules; see <xref linkend="contrib"/>. Other kinds of foreign data wrappers might be found as third party products. If none of the existing foreign data wrappers suit your needs, you can write your own; see <xref - linkend="fdwhandler">. + linkend="fdwhandler"/>. </para> <para> @@ -3918,11 +3918,11 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; <para> For additional information, see - <xref linkend="sql-createforeigndatawrapper">, - <xref linkend="sql-createserver">, - <xref linkend="sql-createusermapping">, - <xref linkend="sql-createforeigntable">, and - <xref linkend="sql-importforeignschema">. + <xref linkend="sql-createforeigndatawrapper"/>, + <xref linkend="sql-createserver"/>, + <xref linkend="sql-createusermapping"/>, + <xref linkend="sql-createforeigntable"/>, and + <xref linkend="sql-importforeignschema"/>. </para> </sect1> @@ -3966,7 +3966,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; <para> Detailed information on - these topics appears in <xref linkend="server-programming">. + these topics appears in <xref linkend="server-programming"/>. </para> </sect1> @@ -3996,7 +3996,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; <productname>PostgreSQL</productname> makes sure that you cannot drop objects that other objects still depend on. For example, attempting to drop the products table we considered in <xref - linkend="ddl-constraints-fk">, with the orders table depending on + linkend="ddl-constraints-fk"/>, with the orders table depending on it, would result in an error message like this: <screen> DROP TABLE products; @@ -4066,7 +4066,7 @@ CREATE FUNCTION get_color_note (rainbow) RETURNS text AS LANGUAGE SQL; </programlisting> - (See <xref linkend="xfunc-sql"> for an explanation of SQL-language + (See <xref linkend="xfunc-sql"/> for an explanation of SQL-language functions.) <productname>PostgreSQL</productname> will be aware that the <function>get_color_note</function> function depends on the <type>rainbow</type> type: dropping the type would force dropping the function, because its diff --git a/doc/src/sgml/dfunc.sgml b/doc/src/sgml/dfunc.sgml index 7ef996b51f..dfefa9e686 100644 --- a/doc/src/sgml/dfunc.sgml +++ b/doc/src/sgml/dfunc.sgml @@ -226,7 +226,7 @@ gcc -G -o foo.so foo.o </para> <para> - Refer back to <xref linkend="xfunc-c-dynload"> about where the + Refer back to <xref linkend="xfunc-c-dynload"/> about where the server expects to find the shared library files. </para> diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml index 04cf14a73d..c15cbd0e4d 100644 --- a/doc/src/sgml/dict-int.sgml +++ b/doc/src/sgml/dict-int.sgml @@ -71,7 +71,7 @@ mydb# select ts_lexize('intdict', '12345678'); </programlisting> but real-world usage will involve including it in a text search - configuration as described in <xref linkend="textsearch">. + configuration as described in <xref linkend="textsearch"/>. That might look like this: <programlisting> diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml index bf4965c36f..256aff7c58 100644 --- a/doc/src/sgml/dict-xsyn.sgml +++ b/doc/src/sgml/dict-xsyn.sgml @@ -135,7 +135,7 @@ mydb=# SELECT ts_lexize('xsyn', 'syn1'); </programlisting> Real-world usage will involve including it in a text search - configuration as described in <xref linkend="textsearch">. + configuration as described in <xref linkend="textsearch"/>. That might look like this: <programlisting> diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml index ba23084354..3708e5f3d8 100644 --- a/doc/src/sgml/diskusage.sgml +++ b/doc/src/sgml/diskusage.sgml @@ -20,18 +20,18 @@ stored. If the table has any columns with potentially-wide values, there also might be a <acronym>TOAST</acronym> file associated with the table, which is used to store values too wide to fit comfortably in the main - table (see <xref linkend="storage-toast">). There will be one valid index + table (see <xref linkend="storage-toast"/>). There will be one valid index on the <acronym>TOAST</acronym> table, if present. There also might be indexes associated with the base table. Each table and index is stored in a separate disk file — possibly more than one file, if the file would exceed one gigabyte. Naming conventions for these files are described - in <xref linkend="storage-file-layout">. + in <xref linkend="storage-file-layout"/>. </para> <para> You can monitor disk space in three ways: - using the SQL functions listed in <xref linkend="functions-admin-dbsize">, - using the <xref linkend="oid2name"> module, or + using the SQL functions listed in <xref linkend="functions-admin-dbsize"/>, + using the <xref linkend="oid2name"/> module, or using manual inspection of the system catalogs. The SQL functions are the easiest to use and are generally recommended. The remainder of this section shows how to do it by inspection of the @@ -124,7 +124,7 @@ ORDER BY relpages DESC; If you cannot free up additional space on the disk by deleting other things, you can move some of the database files to other file systems by making use of tablespaces. See <xref - linkend="manage-ag-tablespaces"> for more information about that. + linkend="manage-ag-tablespaces"/> for more information about that. </para> <tip> diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml index bc016d3cae..1e05c84fd1 100644 --- a/doc/src/sgml/dml.sgml +++ b/doc/src/sgml/dml.sgml @@ -33,10 +33,10 @@ </para> <para> - To create a new row, use the <xref linkend="sql-insert"> + To create a new row, use the <xref linkend="sql-insert"/> command. The command requires the table name and column values. For - example, consider the products table from <xref linkend="ddl">: + example, consider the products table from <xref linkend="ddl"/>: <programlisting> CREATE TABLE products ( product_no integer, @@ -107,16 +107,16 @@ INSERT INTO products (product_no, name, price) WHERE release_date = 'today'; </programlisting> This provides the full power of the SQL query mechanism (<xref - linkend="queries">) for computing the rows to be inserted. + linkend="queries"/>) for computing the rows to be inserted. </para> <tip> <para> When inserting a lot of data at the same time, considering using - the <xref linkend="sql-copy"> command. - It is not as flexible as the <xref linkend="sql-insert"> + the <xref linkend="sql-copy"/> command. + It is not as flexible as the <xref linkend="sql-insert"/> command, but is more efficient. Refer - to <xref linkend="populate"> for more information on improving + to <xref linkend="populate"/> for more information on improving bulk loading performance. </para> </tip> @@ -141,7 +141,7 @@ INSERT INTO products (product_no, name, price) </para> <para> - To update existing rows, use the <xref linkend="sql-update"> + To update existing rows, use the <xref linkend="sql-update"/> command. This requires three pieces of information: <orderedlist spacing="compact"> @@ -160,7 +160,7 @@ INSERT INTO products (product_no, name, price) </para> <para> - Recall from <xref linkend="ddl"> that SQL does not, in general, + Recall from <xref linkend="ddl"/> that SQL does not, in general, provide a unique identifier for rows. Therefore it is not always possible to directly specify which row to update. Instead, you specify which conditions a row must meet in order to @@ -203,7 +203,7 @@ UPDATE products SET price = price * 1.10; this does not create any ambiguity. Of course, the <literal>WHERE</literal> condition does not have to be an equality test. Many other operators are - available (see <xref linkend="functions">). But the expression + available (see <xref linkend="functions"/>). But the expression needs to evaluate to a Boolean result. </para> @@ -243,7 +243,7 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0; </para> <para> - You use the <xref linkend="sql-delete"> + You use the <xref linkend="sql-delete"/> command to remove rows; the syntax is very similar to the <command>UPDATE</command> command. For instance, to remove all rows from the products table that have a price of 10, use: @@ -296,7 +296,7 @@ DELETE FROM products; <para> The allowed contents of a <literal>RETURNING</literal> clause are the same as a <command>SELECT</command> command's output list - (see <xref linkend="queries-select-lists">). It can contain column + (see <xref linkend="queries-select-lists"/>). It can contain column names of the command's target table, or value expressions using those columns. A common shorthand is <literal>RETURNING *</literal>, which selects all columns of the target table in order. @@ -340,7 +340,7 @@ DELETE FROM products </para> <para> - If there are triggers (<xref linkend="triggers">) on the target table, + If there are triggers (<xref linkend="triggers"/>) on the target table, the data available to <literal>RETURNING</literal> is the row as modified by the triggers. Thus, inspecting columns computed by triggers is another common use-case for <literal>RETURNING</literal>. diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 3a5b88ca1c..090ca95835 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -47,23 +47,11 @@ <para> The documentation sources are written in <firstterm>DocBook</firstterm>, which is a markup language - superficially similar to <acronym>HTML</acronym>. Both of these - languages are applications of the <firstterm>Standard Generalized - Markup Language</firstterm>, <acronym>SGML</acronym>, which is - essentially a language for describing other languages. In what - follows, the terms DocBook and <acronym>SGML</acronym> are both + defined in <acronym>XML</acronym>. In what + follows, the terms DocBook and <acronym>XML</acronym> are both used, but technically they are not interchangeable. </para> - <note> - <para> - The PostgreSQL documentation is currently being transitioned from DocBook - SGML and DSSSL style sheets to DocBook XML and XSLT style sheets. Be - careful to look at the instructions relating to the PostgreSQL version you - are dealing with, as the procedures and required tools will change. - </para> - </note> - <para> <productname>DocBook</productname> allows an author to specify the structure and content of a technical document without worrying @@ -97,19 +85,8 @@ <para> This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need - the <acronym>SGML</acronym> and the <acronym>XML</acronym> variant of - the DocBook DTD of the same version. These will usually be in separate - packages. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term> - <listitem> - <para> - These are required by DocBook SGML but are distributed separately - because they are maintained by ISO. + the <acronym>XML</acronym> variant of the DocBook DTD, not + the <acronym>SGML</acronym> variant. </para> </listitem> </varlistentry> @@ -131,17 +108,6 @@ </varlistentry> <varlistentry> - <term><ulink url="http://openjade.sourceforge.net">OpenSP</ulink></term> - <listitem> - <para> - This is the base package of <acronym>SGML</acronym> processing. Note - that we no longer need OpenJade, the <acronym>DSSSL</acronym> - processor, only the OpenSP package for converting SGML to XML. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term> <listitem> <para> @@ -201,7 +167,7 @@ <para> To install the required packages, use: <programlisting> -yum install docbook-dtds docbook-style-xsl fop libxslt opensp +yum install docbook-dtds docbook-style-xsl fop libxslt </programlisting> </para> </sect2> @@ -210,40 +176,9 @@ yum install docbook-dtds docbook-style-xsl fop libxslt opensp <title>Installation on FreeBSD</title> <para> - The FreeBSD Documentation Project is itself a heavy user of - DocBook, so it comes as no surprise that there is a full set of - <quote>ports</quote> of the documentation tools available on - FreeBSD. The following ports need to be installed to build the - documentation on FreeBSD. - <itemizedlist> - <listitem> - <para><filename>textproc/docbook-sgml</filename></para> - </listitem> - <listitem> - <para><filename>textproc/docbook-xml</filename></para> - </listitem> - <listitem> - <para><filename>textproc/docbook-xsl</filename></para> - </listitem> - <listitem> - <para><filename>textproc/dsssl-docbook-modular</filename></para> - </listitem> - <listitem> - <para><filename>textproc/libxslt</filename></para> - </listitem> - <listitem> - <para><filename>textproc/fop</filename></para> - </listitem> - <listitem> - <para><filename>textproc/opensp</filename></para> - </listitem> - </itemizedlist> - </para> - - <para> To install the required packages with <command>pkg</command>, use: <programlisting> -pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp +pkg install docbook-xml docbook-xsl fop libxslt </programlisting> </para> @@ -268,7 +203,7 @@ pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp available for <productname>Debian GNU/Linux</productname>. To install, simply use: <programlisting> -apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc +apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc </programlisting> </para> </sect2> @@ -277,117 +212,21 @@ apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltpro <title>macOS</title> <para> - If you use MacPorts, the following will get you set up: -<programlisting> -sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp -</programlisting> + On macOS, you can build the HTML and man documentation without installing + anything extra. If you want to build PDFs or want to install a local copy + of DocBook, you can get those from your preferred package manager. </para> - </sect2> - - <sect2> - <title>Manual Installation from Source</title> <para> - The manual installation process of the DocBook tools is somewhat - complex, so if you have pre-built packages available, use them. - We describe here only a standard setup, with reasonably standard - installation paths, and no <quote>fancy</quote> features. For - details, you should study the documentation of the respective - package, and read <acronym>SGML</acronym> introductory material. - </para> - - <sect3> - <title>Installing OpenSP</title> - - <para> - The installation of OpenSP offers a GNU-style - <literal>./configure; make; make install</literal> build process. - Details can be found in the OpenSP source distribution. In a nutshell: -<synopsis> -./configure --enable-default-catalog=/usr/local/etc/sgml/catalog -make -make install -</synopsis> - Be sure to remember where you put the <quote>default catalog</quote>; you - will need it below. You can also leave it off, but then you will have to - set the environment variable <envar>SGML_CATALOG_FILES</envar> to point - to the file whenever you use any programs from OpenSP later on. (This - method is also an option if OpenSP is already installed and you want to - install the rest of the toolchain locally.) - </para> - </sect3> - - <sect3> - <title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title> - - <procedure> - <step> - <para> - Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip"> - DocBook V4.2 distribution</ulink>. - </para> - </step> - - <step> - <para> - Create the directory - <filename>/usr/local/share/sgml/docbook-4.2</filename> and change - to it. (The exact location is irrelevant, but this one is - reasonable within the layout we are following here.) -<screen> -<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput> -<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput> -</screen> - </para> - </step> - - <step> - <para> - Unpack the archive: -<screen> -<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput> -</screen> - (The archive will unpack its files into the current directory.) - </para> - </step> - - <step> - <para> - Edit the file - <filename>/usr/local/share/sgml/catalog</filename> (or whatever - you told jade during installation) and put a line like this - into it: + If you use MacPorts, the following will get you set up: <programlisting> -CATALOG "docbook-4.2/docbook.cat" +sudo port install docbook-xml-4.2 docbook-xsl fop </programlisting> - </para> - </step> - - <step> - <para> - Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip"> - ISO 8879 character entities archive</ulink>, unpack it, and put the - files in the same directory you put the DocBook files in: -<screen> -<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput> -<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput> -</screen> - </para> - </step> - - <step> - <para> - Run the following command in the directory with the DocBook and ISO files: + If you use Homebrew, use this: <programlisting> -perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat +brew install docbook docbook-xsl fop </programlisting> - (This fixes a mixup between the names used in the DocBook - catalog file and the actual names of the ISO character entity - files.) - </para> - </step> - </procedure> - </sect3> + </para> </sect2> <sect2 id="docguide-toolsets-configure"> @@ -400,26 +239,14 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat Check the output near the end of the run, it should look something like this: <screen> -<computeroutput> -checking for onsgmls... onsgmls -checking for DocBook V4.2... yes -checking for dbtoepub... dbtoepub checking for xmllint... xmllint +checking for DocBook XML V4.2... yes +checking for dbtoepub... dbtoepub checking for xsltproc... xsltproc -checking for osx... osx checking for fop... fop -</computeroutput> </screen> - If neither <filename>onsgmls</filename> nor - <filename>nsgmls</filename> were found then some of the following tests - will be skipped. <filename>nsgmls</filename> is part of the OpenSP - package. You can pass the environment variable - <envar>NSGMLS</envar> to configure to point - to the programs if they are not found automatically. If - <quote>DocBook V4.2</quote> was not found then you did not install - the DocBook DTD kit in a place where OpenSP can find it, or you have - not set up the catalog files correctly. See the installation hints - above. + If <filename>xmllint</filename> was not found then some of the following + tests will be skipped. </para> </sect2> @@ -464,9 +291,7 @@ checking for fop... fop We use the DocBook XSL stylesheets to convert <productname>DocBook</productname> <sgmltag>refentry</sgmltag> pages to *roff output suitable for man - pages. The man pages are also distributed as a tar archive, - similar to the <acronym>HTML</acronym> version. To create the man - pages, use the commands: + pages. To create the man pages, use the command: <screen> <prompt>doc/src/sgml$ </prompt><userinput>make man</userinput> </screen> @@ -536,7 +361,7 @@ ADDITIONAL_FLAGS='-Xmx1000m' The installation instructions are also distributed as plain text, in case they are needed in a situation where better reading tools are not available. The <filename>INSTALL</filename> file - corresponds to <xref linkend="installation">, with some minor + corresponds to <xref linkend="installation"/>, with some minor changes to account for the different context. To recreate the file, change to the directory <filename>doc/src/sgml</filename> and enter <userinput>make INSTALL</userinput>. diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index 1bdcf64629..1f3ea6aa6e 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -56,7 +56,7 @@ <para> The provided functions are shown - in <xref linkend="earthdistance-cube-functions">. + in <xref linkend="earthdistance-cube-functions"/>. </para> <table id="earthdistance-cube-functions"> @@ -150,7 +150,7 @@ <para> A single operator is provided, shown - in <xref linkend="earthdistance-point-operators">. + in <xref linkend="earthdistance-point-operators"/>. </para> <table id="earthdistance-point-operators"> diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index bc3d080774..d1872c1a5c 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -31,7 +31,7 @@ specially marked sections. To build the program, the source code (<filename>*.pgc</filename>) is first passed through the embedded SQL preprocessor, which converts it to an ordinary C program (<filename>*.c</filename>), and afterwards it can be processed by a C - compiler. (For details about the compiling and linking see <xref linkend="ecpg-process">). + compiler. (For details about the compiling and linking see <xref linkend="ecpg-process"/>). Converted ECPG applications call functions in the libpq library through the embedded SQL library (ecpglib), and communicate with the PostgreSQL server using the normal frontend-backend protocol. @@ -397,9 +397,9 @@ EXEC SQL COMMIT; row can also be executed using <literal>EXEC SQL</literal> directly. To handle result sets with multiple rows, an application has to use a cursor; - see <xref linkend="ecpg-cursors"> below. (As a special case, an + see <xref linkend="ecpg-cursors"/> below. (As a special case, an application can fetch multiple rows at once into an array host - variable; see <xref linkend="ecpg-variables-arrays">.) + variable; see <xref linkend="ecpg-variables-arrays"/>.) </para> <para> @@ -422,7 +422,7 @@ EXEC SQL SHOW search_path INTO :var; <literal>:<replaceable>something</replaceable></literal> are <firstterm>host variables</firstterm>, that is, they refer to variables in the C program. They are explained in <xref - linkend="ecpg-variables">. + linkend="ecpg-variables"/>. </para> </sect2> @@ -452,8 +452,8 @@ EXEC SQL COMMIT; <para> For more details about declaration of the cursor, - see <xref linkend="ecpg-sql-declare">, and - see <xref linkend="sql-fetch"> for <literal>FETCH</literal> command + see <xref linkend="ecpg-sql-declare"/>, and + see <xref linkend="sql-fetch"/> for <literal>FETCH</literal> command details. </para> @@ -477,7 +477,7 @@ EXEC SQL COMMIT; interface also supports autocommit of transactions (similar to <application>psql</application>'s default behavior) via the <option>-t</option> command-line option to <command>ecpg</command> (see <xref - linkend="app-ecpg">) or via the <literal>EXEC SQL SET AUTOCOMMIT TO + linkend="app-ecpg"/>) or via the <literal>EXEC SQL SET AUTOCOMMIT TO ON</literal> statement. In autocommit mode, each command is automatically committed unless it is inside an explicit transaction block. This mode can be explicitly turned off using <literal>EXEC @@ -617,8 +617,8 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>; <para> For more details about <literal>PREPARE</literal>, - see <xref linkend="ecpg-sql-prepare">. Also - see <xref linkend="ecpg-dynamic"> for more details about using + see <xref linkend="ecpg-sql-prepare"/>. Also + see <xref linkend="ecpg-dynamic"/> for more details about using placeholders and input parameters. </para> </sect2> @@ -628,7 +628,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>; <title>Using Host Variables</title> <para> - In <xref linkend="ecpg-commands"> you saw how you can execute SQL + In <xref linkend="ecpg-commands"/> you saw how you can execute SQL statements from an embedded SQL program. Some of those statements only used fixed values and did not provide a way to insert user-supplied values into statements or have the program process @@ -646,7 +646,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>; <para> Another way to exchange values between PostgreSQL backends and ECPG applications is the use of SQL descriptors, described - in <xref linkend="ecpg-descriptors">. + in <xref linkend="ecpg-descriptors"/>. </para> <sect2 id="ecpg-variables-overview"> @@ -812,11 +812,11 @@ do directly. Other PostgreSQL data types, such as <type>timestamp</type> and <type>numeric</type> can only be accessed through special library functions; see - <xref linkend="ecpg-special-types">. + <xref linkend="ecpg-special-types"/>. </para> <para> - <xref linkend="ecpg-datatype-hostvars-table"> shows which PostgreSQL + <xref linkend="ecpg-datatype-hostvars-table"/> shows which PostgreSQL data types correspond to which C data types. When you wish to send or receive a value of a given PostgreSQL data type, you should declare a C variable of the corresponding C data type in @@ -851,12 +851,12 @@ do <row> <entry><type>decimal</type></entry> - <entry><type>decimal</type><footnote id="ecpg-datatype-table-fn"><para>This type can only be accessed through special library functions; see <xref linkend="ecpg-special-types">.</para></footnote></entry> + <entry><type>decimal</type><footnote id="ecpg-datatype-table-fn"><para>This type can only be accessed through special library functions; see <xref linkend="ecpg-special-types"/>.</para></footnote></entry> </row> <row> <entry><type>numeric</type></entry> - <entry><type>numeric</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> + <entry><type>numeric</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry> </row> <row> @@ -901,17 +901,17 @@ do <row> <entry><type>timestamp</type></entry> - <entry><type>timestamp</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> + <entry><type>timestamp</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry> </row> <row> <entry><type>interval</type></entry> - <entry><type>interval</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> + <entry><type>interval</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry> </row> <row> <entry><type>date</type></entry> - <entry><type>date</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> + <entry><type>date</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry> </row> <row> @@ -1002,7 +1002,7 @@ struct varchar_var { int len; char arr[180]; } var; structure. Applications deal with these types by declaring host variables in special types and accessing them using functions in the pgtypes library. The pgtypes library, described in detail - in <xref linkend="ecpg-pgtypes"> contains basic functions to deal + in <xref linkend="ecpg-pgtypes"/> contains basic functions to deal with those types, such that you do not need to send a query to the SQL server just for adding an interval to a time stamp for example. @@ -1011,7 +1011,7 @@ struct varchar_var { int len; char arr[180]; } var; <para> The follow subsections describe these special data types. For more details about pgtypes library functions, - see <xref linkend="ecpg-pgtypes">. + see <xref linkend="ecpg-pgtypes"/>. </para> <sect4> @@ -1062,7 +1062,7 @@ ts = 2010-06-27 18:03:56.949343 program has to include <filename>pgtypes_date.h</filename>, declare a host variable as the date type and convert a DATE value into a text form using <function>PGTYPESdate_to_asc()</function> function. For more details about the - pgtypes library functions, see <xref linkend="ecpg-pgtypes">. + pgtypes library functions, see <xref linkend="ecpg-pgtypes"/>. </para> </sect4> @@ -1117,7 +1117,7 @@ EXEC SQL END DECLARE SECTION; allocating some memory space on the heap, and accessing the variable using the pgtypes library functions. For more details about the pgtypes library functions, - see <xref linkend="ecpg-pgtypes">. + see <xref linkend="ecpg-pgtypes"/>. </para> <para> @@ -1193,7 +1193,7 @@ EXEC SQL END DECLARE SECTION; There are two use cases for arrays as host variables. The first is a way to store some text string in <type>char[]</type> or <type>VARCHAR[]</type>, as - explained in <xref linkend="ecpg-char">. The second use case is to + explained in <xref linkend="ecpg-char"/>. The second use case is to retrieve multiple rows from a query result without using a cursor. Without an array, to process a query result consisting of multiple rows, it is required to use a cursor and @@ -1378,7 +1378,7 @@ EXEC SQL TYPE serial_t IS long; <para> You can declare pointers to the most common types. Note however that you cannot use pointers as target variables of queries - without auto-allocation. See <xref linkend="ecpg-descriptors"> + without auto-allocation. See <xref linkend="ecpg-descriptors"/> for more information on auto-allocation. </para> @@ -1520,7 +1520,7 @@ while (1) Another workaround is to store arrays in their external string representation in host variables of type <type>char[]</type> or <type>VARCHAR[]</type>. For more details about this - representation, see <xref linkend="arrays-input">. Note that + representation, see <xref linkend="arrays-input"/>. Note that this means that the array cannot be accessed naturally as an array in the host program (without further processing that parses the text representation). @@ -1578,7 +1578,7 @@ EXEC SQL CLOSE cur1; To enhance this example, the host variables to store values in the <command>FETCH</command> command can be gathered into one structure. For more details about the host variable in the - structure form, see <xref linkend="ecpg-variables-struct">. + structure form, see <xref linkend="ecpg-variables-struct"/>. To switch to the structure, the example can be modified as below. The two host variables, <varname>intval</varname> and <varname>textval</varname>, become members of @@ -1659,12 +1659,12 @@ while (1) <para> Here is an example using the data type <type>complex</type> from - the example in <xref linkend="xtypes">. The external string + the example in <xref linkend="xtypes"/>. The external string representation of that type is <literal>(%lf,%lf)</literal>, which is defined in the functions <function>complex_in()</function> and <function>complex_out()</function> functions - in <xref linkend="xtypes">. The following example inserts the + in <xref linkend="xtypes"/>. The following example inserts the complex type values <literal>(1,1)</literal> and <literal>(3,3)</literal> into the columns <literal>a</literal> and <literal>b</literal>, and select @@ -1875,7 +1875,7 @@ EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37; <para> If a query is expected to return more than one result row, a cursor should be used, as in the following example. - (See <xref linkend="ecpg-cursors"> for more details about the + (See <xref linkend="ecpg-cursors"/> for more details about the cursor.) <programlisting> EXEC SQL BEGIN DECLARE SECTION; @@ -1941,7 +1941,7 @@ free(out); <title>The numeric Type</title> <para> The numeric type offers to do calculations with arbitrary precision. See - <xref linkend="datatype-numeric"> for the equivalent type in the + <xref linkend="datatype-numeric"/> for the equivalent type in the <productname>PostgreSQL</productname> server. Because of the arbitrary precision this variable needs to be able to expand and shrink dynamically. That's why you can only create numeric variables on the heap, by means of the @@ -2264,7 +2264,7 @@ int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst); <title>The date Type</title> <para> The date type in C enables your programs to deal with data of the SQL type - date. See <xref linkend="datatype-datetime"> for the equivalent type in the + date. See <xref linkend="datatype-datetime"/> for the equivalent type in the <productname>PostgreSQL</productname> server. </para> <para> @@ -2303,7 +2303,7 @@ date PGTYPESdate_from_asc(char *str, char **endptr); currently no variable to change that within ECPG. </para> <para> - <xref linkend="ecpg-pgtypesdate-from-asc-table"> shows the allowed input formats. + <xref linkend="ecpg-pgtypesdate-from-asc-table"/> shows the allowed input formats. </para> <table id="ecpg-pgtypesdate-from-asc-table"> <title>Valid Input Formats for <function>PGTYPESdate_from_asc</function></title> @@ -2558,7 +2558,7 @@ int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf); All other characters are copied 1:1 to the output string. </para> <para> - <xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"> indicates a few possible formats. This will give + <xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"/> indicates a few possible formats. This will give you an idea of how to use this function. All output lines are based on the same date: November 23, 1959. </para> @@ -2649,7 +2649,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str); day. </para> <para> - <xref linkend="ecpg-rdefmtdate-example-table"> indicates a few possible formats. This will give + <xref linkend="ecpg-rdefmtdate-example-table"/> indicates a few possible formats. This will give you an idea of how to use this function. </para> <table id="ecpg-rdefmtdate-example-table"> @@ -2741,7 +2741,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str); <title>The timestamp Type</title> <para> The timestamp type in C enables your programs to deal with data of the SQL - type timestamp. See <xref linkend="datatype-datetime"> for the equivalent + type timestamp. See <xref linkend="datatype-datetime"/> for the equivalent type in the <productname>PostgreSQL</productname> server. </para> <para> @@ -2766,7 +2766,7 @@ timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr); <para> The function returns the parsed timestamp on success. On error, <literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</varname> is - set to <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. See <xref linkend="pgtypesinvalidtimestamp"> for important notes on this value. + set to <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. See <xref linkend="pgtypesinvalidtimestamp"/> for important notes on this value. </para> <para> In general, the input string can contain any combination of an allowed @@ -2777,7 +2777,7 @@ timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr); specifiers are silently discarded. </para> <para> - <xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"> contains a few examples for input strings. + <xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"/> contains a few examples for input strings. </para> <table id="ecpg-pgtypestimestamp-from-asc-example-table"> <title>Valid Input Formats for <function>PGTYPEStimestamp_from_asc</function></title> @@ -3217,7 +3217,7 @@ int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d); </para> <para> This is the reverse function to <xref - linkend="pgtypestimestampfmtasc">. See the documentation there in + linkend="pgtypestimestampfmtasc"/>. See the documentation there in order to find out about the possible formatting mask entries. </para> </listitem> @@ -3270,7 +3270,7 @@ int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tou <title>The interval Type</title> <para> The interval type in C enables your programs to deal with data of the SQL - type interval. See <xref linkend="datatype-datetime"> for the equivalent + type interval. See <xref linkend="datatype-datetime"/> for the equivalent type in the <productname>PostgreSQL</productname> server. </para> <para> @@ -3364,7 +3364,7 @@ int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest); <function>PGTYPESdecimal_free</function>). There are a lot of other functions that deal with the decimal type in the <productname>Informix</productname> compatibility mode described in <xref - linkend="ecpg-informix-compat">. + linkend="ecpg-informix-compat"/>. </para> <para> The following functions can be used to work with the decimal type and are @@ -3632,7 +3632,7 @@ EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc; so using <literal>DESCRIPTOR</literal> and <literal>SQL DESCRIPTOR</literal> produced named SQL Descriptor Areas. Now it is mandatory, omitting the <literal>SQL</literal> keyword produces SQLDA Descriptor Areas, - see <xref linkend="ecpg-sqlda-descriptors">. + see <xref linkend="ecpg-sqlda-descriptors"/>. </para> <para> @@ -3853,7 +3853,7 @@ EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda; </programlisting> Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about the use cases of the <literal>INTO</literal> and <literal>USING</literal> - keywords in <xref linkend="ecpg-named-descriptors"> also apply here with an addition. + keywords in <xref linkend="ecpg-named-descriptors"/> also apply here with an addition. In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal> keyword can be completely omitted if the <literal>INTO</literal> keyword is used: <programlisting> @@ -4038,7 +4038,7 @@ typedef struct sqlvar_struct sqlvar_t; <listitem> <para> Points to the data. The format of the data is described - in <xref linkend="ecpg-variables-type-mapping">. + in <xref linkend="ecpg-variables-type-mapping"/>. </para> </listitem> </varlistentry> @@ -4447,7 +4447,7 @@ main(void) <para> The whole program is shown - in <xref linkend="ecpg-sqlda-example-example">. + in <xref linkend="ecpg-sqlda-example-example"/>. </para> <example id="ecpg-sqlda-example-example"> @@ -5016,7 +5016,7 @@ sqlstate: 42P01 <literal>SQLSTATE</literal> error codes; therefore a high degree of consistency can be achieved by using this error code scheme throughout all applications. For further information see - <xref linkend="errcodes-appendix">. + <xref linkend="errcodes-appendix"/>. </para> <para> @@ -5037,7 +5037,7 @@ sqlstate: 42P01 <literal>SQLSTATE</literal> is also listed. There is, however, no one-to-one or one-to-many mapping between the two schemes (indeed it is many-to-many), so you should consult the global - <literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix"> + <literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix"/> in each case. </para> @@ -5767,7 +5767,7 @@ ECPG = ecpg <para> The complete syntax of the <command>ecpg</command> command is - detailed in <xref linkend="app-ecpg">. + detailed in <xref linkend="app-ecpg"/>. </para> <para> @@ -5835,7 +5835,7 @@ ECPG = ecpg <para> <function>ECPGtransactionStatus(const char *<replaceable>connection_name</replaceable>)</function> returns the current transaction status of the given connection identified by <replaceable>connection_name</replaceable>. - See <xref linkend="libpq-status"> and libpq's <function>PQtransactionStatus()</function> for details about the returned status codes. + See <xref linkend="libpq-status"/> and libpq's <function>PQtransactionStatus()</function> for details about the returned status codes. </para> </listitem> @@ -5867,8 +5867,8 @@ ECPG = ecpg <para> For more details about the <function>ECPGget_PGconn()</function>, see - <xref linkend="ecpg-library">. For information about the large - object function interface, see <xref linkend="largeobjects">. + <xref linkend="ecpg-library"/>. For information about the large + object function interface, see <xref linkend="largeobjects"/>. </para> <para> @@ -5878,7 +5878,7 @@ ECPG = ecpg </para> <para> - <xref linkend="ecpg-lo-example"> shows an example program that + <xref linkend="ecpg-lo-example"/> shows an example program that illustrates how to create, write, and read a large object in an ECPG application. </para> @@ -5997,7 +5997,7 @@ main(void) A safe way to use the embedded SQL code in a C++ application is hiding the ECPG calls in a C module, which the C++ application code calls into to access the database, and linking that together with - the rest of the C++ code. See <xref linkend="ecpg-cpp-and-c"> + the rest of the C++ code. See <xref linkend="ecpg-cpp-and-c"/> about that. </para> @@ -6252,7 +6252,7 @@ c++ test_cpp.o test_mod.o -lecpg -o test_cpp <para> This section describes all SQL commands that are specific to embedded SQL. Also refer to the SQL commands listed - in <xref linkend="sql-commands">, which can also be used in + in <xref linkend="sql-commands"/>, which can also be used in embedded SQL, unless stated otherwise. </para> @@ -6320,9 +6320,9 @@ EXEC SQL ALLOCATE DESCRIPTOR mydesc; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-deallocate-descriptor"></member> - <member><xref linkend="ecpg-sql-get-descriptor"></member> - <member><xref linkend="ecpg-sql-set-descriptor"></member> + <member><xref linkend="ecpg-sql-deallocate-descriptor"/></member> + <member><xref linkend="ecpg-sql-get-descriptor"/></member> + <member><xref linkend="ecpg-sql-set-descriptor"/></member> </simplelist> </refsect1> </refentry> @@ -6539,8 +6539,8 @@ EXEC SQL END DECLARE SECTION; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-disconnect"></member> - <member><xref linkend="ecpg-sql-set-connection"></member> + <member><xref linkend="ecpg-sql-disconnect"/></member> + <member><xref linkend="ecpg-sql-set-connection"/></member> </simplelist> </refsect1> </refentry> @@ -6604,9 +6604,9 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-allocate-descriptor"></member> - <member><xref linkend="ecpg-sql-get-descriptor"></member> - <member><xref linkend="ecpg-sql-set-descriptor"></member> + <member><xref linkend="ecpg-sql-allocate-descriptor"/></member> + <member><xref linkend="ecpg-sql-get-descriptor"/></member> + <member><xref linkend="ecpg-sql-set-descriptor"/></member> </simplelist> </refsect1> </refentry> @@ -6668,8 +6668,8 @@ DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ IN <term><replaceable class="parameter">query</replaceable></term> <listitem> <para> - A <xref linkend="sql-select"> or - <xref linkend="sql-values"> command which will provide the + A <xref linkend="sql-select"/> or + <xref linkend="sql-values"/> command which will provide the rows to be returned by the cursor. </para> </listitem> @@ -6678,7 +6678,7 @@ DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ IN <para> For the meaning of the cursor options, - see <xref linkend="sql-declare">. + see <xref linkend="sql-declare"/>. </para> </refsect1> @@ -6715,9 +6715,9 @@ EXEC SQL DECLARE cur1 CURSOR FOR stmt1; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-open"></member> - <member><xref linkend="sql-close"></member> - <member><xref linkend="sql-declare"></member> + <member><xref linkend="ecpg-sql-open"/></member> + <member><xref linkend="sql-close"/></member> + <member><xref linkend="sql-declare"/></member> </simplelist> </refsect1> </refentry> @@ -6805,8 +6805,8 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-allocate-descriptor"></member> - <member><xref linkend="ecpg-sql-get-descriptor"></member> + <member><xref linkend="ecpg-sql-allocate-descriptor"/></member> + <member><xref linkend="ecpg-sql-get-descriptor"/></member> </simplelist> </refsect1> </refentry> @@ -6915,8 +6915,8 @@ main(void) <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-connect"></member> - <member><xref linkend="ecpg-sql-set-connection"></member> + <member><xref linkend="ecpg-sql-connect"/></member> + <member><xref linkend="ecpg-sql-set-connection"/></member> </simplelist> </refsect1> </refentry> @@ -7056,7 +7056,7 @@ GET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALU <listitem> <para> A token identifying which item of information about a column - to retrieve. See <xref linkend="ecpg-named-descriptors"> for + to retrieve. See <xref linkend="ecpg-named-descriptors"/> for a list of supported items. </para> </listitem> @@ -7164,8 +7164,8 @@ d_data = testdb <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-allocate-descriptor"></member> - <member><xref linkend="ecpg-sql-set-descriptor"></member> + <member><xref linkend="ecpg-sql-allocate-descriptor"/></member> + <member><xref linkend="ecpg-sql-set-descriptor"/></member> </simplelist> </refsect1> </refentry> @@ -7258,8 +7258,8 @@ EXEC SQL OPEN :curname1; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-declare"></member> - <member><xref linkend="sql-close"></member> + <member><xref linkend="ecpg-sql-declare"/></member> + <member><xref linkend="sql-close"/></member> </simplelist> </refsect1> </refentry> @@ -7282,8 +7282,8 @@ PREPARE <replaceable class="parameter">name</replaceable> FROM <replaceable clas <para> <command>PREPARE</command> prepares a statement dynamically specified as a string for execution. This is different from the - direct SQL statement <xref linkend="sql-prepare">, which can also - be used in embedded programs. The <xref linkend="sql-execute"> + direct SQL statement <xref linkend="sql-prepare"/>, which can also + be used in embedded programs. The <xref linkend="sql-execute"/> command is used to execute either kind of prepared statement. </para> </refsect1> @@ -7338,7 +7338,7 @@ EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="sql-execute"></member> + <member><xref linkend="sql-execute"/></member> </simplelist> </refsect1> </refentry> @@ -7445,8 +7445,8 @@ EXEC SQL SET CONNECTION = con1; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-connect"></member> - <member><xref linkend="ecpg-sql-disconnect"></member> + <member><xref linkend="ecpg-sql-connect"/></member> + <member><xref linkend="ecpg-sql-disconnect"/></member> </simplelist> </refsect1> </refentry> @@ -7520,7 +7520,7 @@ SET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALU <listitem> <para> A token identifying which item of information to set in the - descriptor. See <xref linkend="ecpg-named-descriptors"> for a + descriptor. See <xref linkend="ecpg-named-descriptors"/> for a list of supported items. </para> </listitem> @@ -7561,8 +7561,8 @@ EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2; <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="ecpg-sql-allocate-descriptor"></member> - <member><xref linkend="ecpg-sql-get-descriptor"></member> + <member><xref linkend="ecpg-sql-allocate-descriptor"/></member> + <member><xref linkend="ecpg-sql-get-descriptor"/></member> </simplelist> </refsect1> </refentry> @@ -7796,7 +7796,7 @@ WHENEVER { NOT FOUND | SQLERROR | SQLWARNING } <replaceable class="parameter">ac <title>Parameters</title> <para> - See <xref linkend="ecpg-whenever"> for a description of the + See <xref linkend="ecpg-whenever"/> for a description of the parameters. </para> </refsect1> @@ -7979,7 +7979,7 @@ EXEC SQL CLOSE DATABASE; <title>Informix-compatible SQLDA Descriptor Areas</title> <para> Informix-compatible mode supports a different structure than the one described in - <xref linkend="ecpg-sqlda-descriptors">. See below: + <xref linkend="ecpg-sqlda-descriptors"/>. See below: <programlisting> struct sqlvar_compat { @@ -8653,7 +8653,7 @@ void rtoday(date *d); that it sets to the current date. </para> <para> - Internally this function uses the <xref linkend="pgtypesdatetoday"> + Internally this function uses the <xref linkend="pgtypesdatetoday"/> function. </para> </listitem> @@ -8678,7 +8678,7 @@ int rjulmdy(date d, short mdy[3]); The function always returns 0 at the moment. </para> <para> - Internally the function uses the <xref linkend="pgtypesdatejulmdy"> + Internally the function uses the <xref linkend="pgtypesdatejulmdy"/> function. </para> </listitem> @@ -8748,7 +8748,7 @@ int rdefmtdate(date *d, char *fmt, char *str); </para> <para> Internally this function is implemented to use the <xref - linkend="pgtypesdatedefmtasc"> function. See the reference there for a + linkend="pgtypesdatedefmtasc"/> function. See the reference there for a table of example input. </para> </listitem> @@ -8771,7 +8771,7 @@ int rfmtdate(date d, char *fmt, char *str); On success, 0 is returned and a negative value if an error occurred. </para> <para> - Internally this function uses the <xref linkend="pgtypesdatefmtasc"> + Internally this function uses the <xref linkend="pgtypesdatefmtasc"/> function, see the reference there for examples. </para> </listitem> @@ -8795,7 +8795,7 @@ int rmdyjul(short mdy[3], date *d); </para> <para> Internally the function is implemented to use the function <xref - linkend="pgtypesdatemdyjul">. + linkend="pgtypesdatemdyjul"/>. </para> </listitem> </varlistentry> @@ -8851,7 +8851,7 @@ int rdayofweek(date d); </para> <para> Internally the function is implemented to use the function <xref - linkend="pgtypesdatedayofweek">. + linkend="pgtypesdatedayofweek"/>. </para> </listitem> </varlistentry> @@ -8889,7 +8889,7 @@ int dtcvasc(char *str, timestamp *ts); </para> <para> Internally this function uses the <xref - linkend="pgtypestimestampfromasc"> function. See the reference there + linkend="pgtypestimestampfromasc"/> function. See the reference there for a table with example inputs. </para> </listitem> @@ -8911,7 +8911,7 @@ dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue) </para> <para> This function is implemented by means of the <xref - linkend="pgtypestimestampdefmtasc"> function. See the documentation + linkend="pgtypestimestampdefmtasc"/> function. See the documentation there for a list of format specifiers that can be used. </para> <para> @@ -8983,7 +8983,7 @@ int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr); </para> <para> Internally, this function uses the <xref - linkend="pgtypestimestampfmtasc"> function. See the reference there for + linkend="pgtypestimestampfmtasc"/> function. See the reference there for information on what format mask specifiers can be used. </para> </listitem> @@ -9289,7 +9289,7 @@ int risnull(int t, char *ptr); The function receives the type of the variable to test (<literal>t</literal>) as well a pointer to this variable (<literal>ptr</literal>). Note that the latter needs to be cast to a char*. See the function <xref - linkend="rsetnull"> for a list of possible variable types. + linkend="rsetnull"/> for a list of possible variable types. </para> <para> Here is an example of how to use this function: diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml index 61ad3e00e9..6fd16f643e 100644 --- a/doc/src/sgml/errcodes.sgml +++ b/doc/src/sgml/errcodes.sgml @@ -32,7 +32,7 @@ </para> <para> - <xref linkend="errcodes-table"> lists all the error codes defined in + <xref linkend="errcodes-table"/> lists all the error codes defined in <productname>PostgreSQL</productname> &version;. (Some are not actually used at present, but are defined by the SQL standard.) The error classes are also shown. For each error class there is a @@ -66,9 +66,9 @@ <title><productname>PostgreSQL</productname> Error Codes</title> <tgroup cols="2"> - <colspec colnum="1" colname="errorcode"> - <colspec colnum="2" colname="condname"> - <spanspec namest="errorcode" nameend="condname" spanname="span12"> + <colspec colnum="1" colname="errorcode"/> + <colspec colnum="2" colname="condname"/> + <spanspec namest="errorcode" nameend="condname" spanname="span12"/> <thead> <row> diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index c16ff338a3..0a8860490a 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -8,7 +8,7 @@ </indexterm> <para> - To supplement the trigger mechanism discussed in <xref linkend="triggers">, + To supplement the trigger mechanism discussed in <xref linkend="triggers"/>, <productname>PostgreSQL</productname> also provides event triggers. Unlike regular triggers, which are attached to a single table and capture only DML events, event triggers are global to a particular database and are capable of @@ -57,7 +57,7 @@ operations that took place, use the set-returning function <literal>pg_event_trigger_ddl_commands()</literal> from the <literal>ddl_command_end</literal> event trigger code (see - <xref linkend="functions-event-triggers">). Note that the trigger fires + <xref linkend="functions-event-triggers"/>). Note that the trigger fires after the actions have taken place (but before the transaction commits), and thus the system catalogs can be read as already changed. </para> @@ -68,7 +68,7 @@ database objects. To list the objects that have been dropped, use the set-returning function <literal>pg_event_trigger_dropped_objects()</literal> from the <literal>sql_drop</literal> event trigger code (see - <xref linkend="functions-event-triggers">). Note that + <xref linkend="functions-event-triggers"/>). Note that the trigger is executed after the objects have been deleted from the system catalogs, so it's not possible to look them up anymore. </para> @@ -96,11 +96,11 @@ <para> For a complete list of commands supported by the event trigger mechanism, - see <xref linkend="event-trigger-matrix">. + see <xref linkend="event-trigger-matrix"/>. </para> <para> - Event triggers are created using the command <xref linkend="sql-createeventtrigger">. + Event triggers are created using the command <xref linkend="sql-createeventtrigger"/>. In order to create an event trigger, you must first create a function with the special return type <literal>event_trigger</literal>. This function need not (and may not) return a value; the return type serves merely as @@ -125,7 +125,7 @@ <title>Event Trigger Firing Matrix</title> <para> - <xref linkend="event-trigger-by-command-tag"> lists all commands + <xref linkend="event-trigger-by-command-tag"/> lists all commands for which event triggers are supported. </para> @@ -953,7 +953,7 @@ typedef struct EventTriggerData Describes the event for which the function is called, one of <literal>"ddl_command_start"</literal>, <literal>"ddl_command_end"</literal>, <literal>"sql_drop"</literal>, <literal>"table_rewrite"</literal>. - See <xref linkend="event-trigger-definition"> for the meaning of these + See <xref linkend="event-trigger-definition"/> for the meaning of these events. </para> </listitem> @@ -1003,7 +1003,7 @@ typedef struct EventTriggerData The event trigger definition associated the function with the <literal>ddl_command_start</literal> event. The effect is that all DDL commands (with the exceptions mentioned - in <xref linkend="event-trigger-definition">) are prevented from running. + in <xref linkend="event-trigger-definition"/>) are prevented from running. </para> <para> @@ -1037,7 +1037,7 @@ noddl(PG_FUNCTION_ARGS) </para> <para> - After you have compiled the source code (see <xref linkend="dfunc">), + After you have compiled the source code (see <xref linkend="dfunc"/>), declare the function and the triggers: <programlisting> CREATE FUNCTION noddl() RETURNS event_trigger diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index e819010875..5f1bb70e97 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -15,32 +15,32 @@ <itemizedlist spacing="compact" mark="bullet"> <listitem> <para> - functions (starting in <xref linkend="xfunc">) + functions (starting in <xref linkend="xfunc"/>) </para> </listitem> <listitem> <para> - aggregates (starting in <xref linkend="xaggr">) + aggregates (starting in <xref linkend="xaggr"/>) </para> </listitem> <listitem> <para> - data types (starting in <xref linkend="xtypes">) + data types (starting in <xref linkend="xtypes"/>) </para> </listitem> <listitem> <para> - operators (starting in <xref linkend="xoper">) + operators (starting in <xref linkend="xoper"/>) </para> </listitem> <listitem> <para> - operator classes for indexes (starting in <xref linkend="xindex">) + operator classes for indexes (starting in <xref linkend="xindex"/>) </para> </listitem> <listitem> <para> - packages of related objects (starting in <xref linkend="extend-extensions">) + packages of related objects (starting in <xref linkend="extend-extensions"/>) </para> </listitem> </itemizedlist> @@ -132,14 +132,14 @@ types through functions provided by the user and only understands the behavior of such types to the extent that the user describes them. - The built-in base types are described in <xref linkend="datatype">. + The built-in base types are described in <xref linkend="datatype"/>. </para> <para> Enumerated (enum) types can be considered as a subcategory of base types. The main difference is that they can be created using just <acronym>SQL</acronym> commands, without any low-level programming. - Refer to <xref linkend="datatype-enum"> for more information. + Refer to <xref linkend="datatype-enum"/> for more information. </para> </sect2> @@ -157,25 +157,25 @@ type is automatically created for each base type, composite type, range type, and domain type. But there are no arrays of arrays. So far as the type system is concerned, multi-dimensional arrays are the same as - one-dimensional arrays. Refer to <xref linkend="arrays"> for more + one-dimensional arrays. Refer to <xref linkend="arrays"/> for more information. </para> <para> Composite types, or row types, are created whenever the user creates a table. It is also possible to use <xref - linkend="sql-createtype"> to + linkend="sql-createtype"/> to define a <quote>stand-alone</quote> composite type with no associated table. A composite type is simply a list of types with associated field names. A value of a composite type is a row or - record of field values. Refer to <xref linkend="rowtypes"> + record of field values. Refer to <xref linkend="rowtypes"/> for more information. </para> <para> A range type can hold two values of the same type, which are the lower and upper bounds of the range. Range types are user-created, although - a few built-in ones exist. Refer to <xref linkend="rangetypes"> + a few built-in ones exist. Refer to <xref linkend="rangetypes"/> for more information. </para> </sect2> @@ -188,8 +188,8 @@ is interchangeable with its underlying type. However, a domain can have constraints that restrict its valid values to a subset of what the underlying type would allow. Domains are created using - the <acronym>SQL</acronym> command <xref linkend="sql-createdomain">. - Refer to <xref linkend="domains"> for more information. + the <acronym>SQL</acronym> command <xref linkend="sql-createdomain"/>. + Refer to <xref linkend="domains"/> for more information. </para> </sect2> @@ -202,7 +202,7 @@ container types, but they can be used to declare the argument and result types of functions. This provides a mechanism within the type system to identify special classes of functions. <xref - linkend="datatype-pseudotypes-table"> lists the existing + linkend="datatype-pseudotypes-table"/> lists the existing pseudo-types. </para> </sect2> @@ -300,7 +300,7 @@ <para> A variadic function (one taking a variable number of arguments, as in - <xref linkend="xfunc-sql-variadic-functions">) can be + <xref linkend="xfunc-sql-variadic-functions"/>) can be polymorphic: this is accomplished by declaring its last parameter as <literal>VARIADIC</literal> <type>anyarray</type>. For purposes of argument matching and determining the actual result type, such a function behaves @@ -337,7 +337,7 @@ of the extension itself. If the extension includes C code, there will typically also be a shared library file into which the C code has been built. Once you have these files, a simple - <xref linkend="sql-createextension"> command loads the objects into + <xref linkend="sql-createextension"/> command loads the objects into your database. </para> @@ -346,7 +346,7 @@ <acronym>SQL</acronym> script to load a bunch of <quote>loose</quote> objects into your database, is that <productname>PostgreSQL</productname> will then understand that the objects of the extension go together. You can - drop all the objects with a single <xref linkend="sql-dropextension"> + drop all the objects with a single <xref linkend="sql-dropextension"/> command (no need to maintain a separate <quote>uninstall</quote> script). Even more useful, <application>pg_dump</application> knows that it should not dump the individual member objects of the extension — it will @@ -366,7 +366,7 @@ by <application>pg_dump</application>. Such a change is usually only sensible if you concurrently make the same change in the extension's script file. (But there are special provisions for tables containing configuration - data; see <xref linkend="extend-extensions-config-tables">.) + data; see <xref linkend="extend-extensions-config-tables"/>.) In production situations, it's generally better to create an extension update script to perform changes to extension member objects. </para> @@ -405,7 +405,7 @@ <para> The kinds of SQL objects that can be members of an extension are shown in - the description of <xref linkend="sql-alterextension">. Notably, objects + the description of <xref linkend="sql-alterextension"/>. Notably, objects that are database-cluster-wide, such as databases, roles, and tablespaces, cannot be extension members since an extension is only known within one database. (Although an extension script is not prohibited from creating @@ -438,7 +438,7 @@ </indexterm> <para> - The <xref linkend="sql-createextension"> command relies on a control + The <xref linkend="sql-createextension"/> command relies on a control file for each extension, which must be named the same as the extension with a suffix of <literal>.control</literal>, and must be placed in the installation's <literal>SHAREDIR/extension</literal> directory. There @@ -499,7 +499,7 @@ when initially creating an extension, but not during extension updates (since that might override user-added comments). Alternatively, the extension's comment can be set by writing - a <xref linkend="sql-comment"> command in the script file. + a <xref linkend="sql-comment"/> command in the script file. </para> </listitem> </varlistentry> @@ -562,7 +562,7 @@ its contained objects into a different schema after initial creation of the extension. The default is <literal>false</literal>, i.e. the extension is not relocatable. - See <xref linkend="extend-extensions-relocation"> for more information. + See <xref linkend="extend-extensions-relocation"/> for more information. </para> </listitem> </varlistentry> @@ -576,7 +576,7 @@ and not any other. The <varname>schema</varname> parameter is consulted only when initially creating an extension, not during extension updates. - See <xref linkend="extend-extensions-relocation"> for more information. + See <xref linkend="extend-extensions-relocation"/> for more information. </para> </listitem> </varlistentry> @@ -609,7 +609,7 @@ comments) by the extension mechanism. This provision is commonly used to throw an error if the script file is fed to <application>psql</application> rather than being loaded via <command>CREATE EXTENSION</command> (see example - script in <xref linkend="extend-extensions-example">). + script in <xref linkend="extend-extensions-example"/>). Without that, users might accidentally load the extension's contents as <quote>loose</quote> objects rather than as an extension, a state of affairs that's a bit tedious to recover from. @@ -687,7 +687,7 @@ <para> In all cases, the script file will be executed with - <xref linkend="guc-search-path"> initially set to point to the target + <xref linkend="guc-search-path"/> initially set to point to the target schema; that is, <command>CREATE EXTENSION</command> does the equivalent of this: <programlisting> @@ -1031,14 +1031,14 @@ include $(PGXS) </programlisting> This makefile relies on <acronym>PGXS</acronym>, which is described - in <xref linkend="extend-pgxs">. The command <literal>make install</literal> + in <xref linkend="extend-pgxs"/>. The command <literal>make install</literal> will install the control and script files into the correct directory as reported by <application>pg_config</application>. </para> <para> Once the files are installed, use the - <xref linkend="sql-createextension"> command to load the objects into + <xref linkend="sql-createextension"/> command to load the objects into any particular database. </para> </sect2> diff --git a/doc/src/sgml/external-projects.sgml b/doc/src/sgml/external-projects.sgml index 03fd18aeb8..89147817ec 100644 --- a/doc/src/sgml/external-projects.sgml +++ b/doc/src/sgml/external-projects.sgml @@ -40,7 +40,7 @@ </itemizedlist> All other language interfaces are external projects and are distributed - separately. <xref linkend="language-interface-table"> includes a list of + separately. <xref linkend="language-interface-table"/> includes a list of some of these projects. Note that some of these packages might not be released under the same license as <productname>PostgreSQL</productname>. For more information on each language interface, including licensing terms, refer to @@ -170,7 +170,7 @@ <para> In addition, there are a number of procedural languages that are developed and maintained outside the core <productname>PostgreSQL</productname> - distribution. <xref linkend="pl-language-table"> lists some of these + distribution. <xref linkend="pl-language-table"/> lists some of these packages. Note that some of these projects might not be released under the same license as <productname>PostgreSQL</productname>. For more information on each procedural language, including licensing information, refer to its website @@ -238,7 +238,7 @@ just like features that are built in. The <filename>contrib/</filename> directory shipped with the source code contains several extensions, which are described in - <xref linkend="contrib">. Other extensions are developed + <xref linkend="contrib"/>. Other extensions are developed independently, like <application><ulink url="http://postgis.net/">PostGIS</ulink></application>. Even <productname>PostgreSQL</productname> replication solutions can be developed diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml index 4250a03f16..a2f8137713 100644 --- a/doc/src/sgml/fdwhandler.sgml +++ b/doc/src/sgml/fdwhandler.sgml @@ -22,7 +22,7 @@ The foreign data wrappers included in the standard distribution are good references when trying to write your own. Look into the <filename>contrib</filename> subdirectory of the source tree. - The <xref linkend="sql-createforeigndatawrapper"> reference page also has + The <xref linkend="sql-createforeigndatawrapper"/> reference page also has some useful details. </para> @@ -43,7 +43,7 @@ a validator function. Both functions must be written in a compiled language such as C, using the version-1 interface. For details on C language calling conventions and dynamic loading, - see <xref linkend="xfunc-c">. + see <xref linkend="xfunc-c"/>. </para> <para> @@ -57,7 +57,7 @@ returning the special pseudo-type <type>fdw_handler</type>. The callback functions are plain C functions and are not visible or callable at the SQL level. The callback functions are described in - <xref linkend="fdw-callbacks">. + <xref linkend="fdw-callbacks"/>. </para> <para> @@ -126,7 +126,7 @@ GetForeignRelSize(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> <para> @@ -157,7 +157,7 @@ GetForeignPaths(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> <para> @@ -193,7 +193,7 @@ GetForeignPlan(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> <para> @@ -341,7 +341,7 @@ GetForeignJoinPaths(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> </sect2> @@ -388,7 +388,7 @@ GetForeignUpperPaths(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> </sect2> @@ -477,7 +477,7 @@ PlanForeignModify(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> <para> @@ -759,7 +759,7 @@ PlanDirectModify(PlannerInfo *root, </para> <para> - See <xref linkend="fdw-planning"> for additional information. + See <xref linkend="fdw-planning"/> for additional information. </para> <para> @@ -872,7 +872,7 @@ EndDirectModify(ForeignScanState *node); <para> If an FDW wishes to support <firstterm>late row locking</firstterm> (as described - in <xref linkend="fdw-row-locking">), it must provide the following + in <xref linkend="fdw-row-locking"/>), it must provide the following callback functions: </para> @@ -905,7 +905,7 @@ GetForeignRowMarkType(RangeTblEntry *rte, </para> <para> - See <xref linkend="fdw-row-locking"> for more information. + See <xref linkend="fdw-row-locking"/> for more information. </para> <para> @@ -964,7 +964,7 @@ RefetchForeignRow(EState *estate, </para> <para> - See <xref linkend="fdw-row-locking"> for more information. + See <xref linkend="fdw-row-locking"/> for more information. </para> <para> @@ -1093,7 +1093,7 @@ AnalyzeForeignTable(Relation relation, BlockNumber *totalpages); </programlisting> - This function is called when <xref linkend="sql-analyze"> is executed on + This function is called when <xref linkend="sql-analyze"/> is executed on a foreign table. If the FDW can collect statistics for this foreign table, it should return <literal>true</literal>, and provide a pointer to a function that will collect sample rows from the table in @@ -1139,10 +1139,10 @@ ImportForeignSchema(ImportForeignSchemaStmt *stmt, Oid serverOid); </programlisting> Obtain a list of foreign table creation commands. This function is - called when executing <xref linkend="sql-importforeignschema">, and is + called when executing <xref linkend="sql-importforeignschema"/>, and is passed the parse tree for that statement, as well as the OID of the foreign server to use. It should return a list of C strings, each of - which must contain a <xref linkend="sql-createforeigntable"> command. + which must contain a <xref linkend="sql-createforeigntable"/> command. These strings will be parsed and executed by the core server. </para> @@ -1605,7 +1605,7 @@ GetForeignServerByName(const char *name, bool missing_ok); <para> <function>PlanForeignModify</function> and the other callbacks described in - <xref linkend="fdw-callbacks-update"> are designed around the assumption + <xref linkend="fdw-callbacks-update"/> are designed around the assumption that the foreign relation will be scanned in the usual way and then individual row updates will be driven by a local <literal>ModifyTable</literal> plan node. This approach is necessary for the general case where an @@ -1616,7 +1616,7 @@ GetForeignServerByName(const char *name, bool missing_ok); compete against the <literal>ModifyTable</literal> approach. This approach could also be used to implement remote <literal>SELECT FOR UPDATE</literal>, rather than using the row locking callbacks described in - <xref linkend="fdw-callbacks-row-locking">. Keep in mind that a path + <xref linkend="fdw-callbacks-row-locking"/>. Keep in mind that a path inserted into <literal>UPPERREL_FINAL</literal> is responsible for implementing <emphasis>all</emphasis> behavior of the query. </para> @@ -1676,7 +1676,7 @@ GetForeignServerByName(const char *name, bool missing_ok); By default, <productname>PostgreSQL</productname> ignores locking considerations when interfacing to FDWs, but an FDW can perform early locking without any explicit support from the core code. The API functions described - in <xref linkend="fdw-callbacks-row-locking">, which were added + in <xref linkend="fdw-callbacks-row-locking"/>, which were added in <productname>PostgreSQL</productname> 9.5, allow an FDW to use late locking if it wishes. </para> @@ -1720,7 +1720,7 @@ GetForeignServerByName(const char *name, bool missing_ok); again perform early locking by fetching tuples with the equivalent of <command>SELECT FOR UPDATE/SHARE</command>. To perform late locking instead, provide the callback functions defined - in <xref linkend="fdw-callbacks-row-locking">. + in <xref linkend="fdw-callbacks-row-locking"/>. In <function>GetForeignRowMarkType</function>, select rowmark option <literal>ROW_MARK_EXCLUSIVE</literal>, <literal>ROW_MARK_NOKEYEXCLUSIVE</literal>, <literal>ROW_MARK_SHARE</literal>, or <literal>ROW_MARK_KEYSHARE</literal> depending diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml index 88aefb8ef0..e2598a07da 100644 --- a/doc/src/sgml/file-fdw.sgml +++ b/doc/src/sgml/file-fdw.sgml @@ -13,7 +13,7 @@ files in the server's file system, or to execute programs on the server and read their output. The data file or program output must be in a format that can be read by <command>COPY FROM</command>; - see <xref linkend="sql-copy"> for details. + see <xref linkend="sql-copy"/> for details. Access to data files is currently read-only. </para> diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 698daf69ea..4dd9d029e6 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -15,7 +15,7 @@ <productname>PostgreSQL</productname> provides a large number of functions and operators for the built-in data types. Users can also define their own functions and operators, as described in - <xref linkend="server-programming">. The + <xref linkend="server-programming"/>. The <application>psql</application> commands <command>\df</command> and <command>\do</command> can be used to list all available functions and operators, respectively. @@ -176,7 +176,7 @@ The operators <literal>AND</literal> and <literal>OR</literal> are commutative, that is, you can switch the left and right operand without affecting the result. But see <xref - linkend="syntax-express-eval"> for more information about the + linkend="syntax-express-eval"/> for more information about the order of evaluation of subexpressions. </para> </sect1> @@ -191,7 +191,7 @@ <para> The usual comparison operators are available, as shown in <xref - linkend="functions-comparison-op-table">. + linkend="functions-comparison-op-table"/>. </para> <table id="functions-comparison-op-table"> @@ -258,7 +258,7 @@ <para> There are also some comparison predicates, as shown in <xref - linkend="functions-comparison-pred-table">. These behave much like + linkend="functions-comparison-pred-table"/>. These behave much like operators, but have special syntax mandated by the SQL standard. </para> @@ -455,7 +455,7 @@ returns true if <replaceable>expression</replaceable> evaluates to the null value. It is highly recommended that these applications be modified to comply with the SQL standard. However, if that - cannot be done the <xref linkend="guc-transform-null-equals"> + cannot be done the <xref linkend="guc-transform-null-equals"/> configuration variable is available. If it is enabled, <productname>PostgreSQL</productname> will convert <literal>x = NULL</literal> clauses to <literal>x IS NULL</literal>. @@ -536,7 +536,7 @@ <para> Some comparison-related functions are also available, as shown in <xref - linkend="functions-comparison-func-table">. + linkend="functions-comparison-func-table"/>. </para> <table id="functions-comparison-func-table"> @@ -591,7 +591,7 @@ </para> <para> - <xref linkend="functions-math-op-table"> shows the available mathematical operators. + <xref linkend="functions-math-op-table"/> shows the available mathematical operators. </para> <table id="functions-math-op-table"> @@ -736,11 +736,11 @@ the others are available for all numeric data types. The bitwise operators are also available for the bit string types <type>bit</type> and <type>bit varying</type>, as - shown in <xref linkend="functions-bit-string-op-table">. + shown in <xref linkend="functions-bit-string-op-table"/>. </para> <para> - <xref linkend="functions-math-func-table"> shows the available + <xref linkend="functions-math-func-table"/> shows the available mathematical functions. In the table, <literal>dp</literal> indicates <type>double precision</type>. Many of these functions are provided in multiple forms with different argument types. @@ -1093,7 +1093,7 @@ </table> <para> - <xref linkend="functions-math-random-table"> shows functions for + <xref linkend="functions-math-random-table"/> shows functions for generating random numbers. </para> @@ -1139,11 +1139,11 @@ The characteristics of the values returned by <literal><function>random()</function></literal> depend on the system implementation. It is not suitable for cryptographic - applications; see <xref linkend="pgcrypto"> module for an alternative. + applications; see <xref linkend="pgcrypto"/> module for an alternative. </para> <para> - Finally, <xref linkend="functions-math-trig-table"> shows the + Finally, <xref linkend="functions-math-trig-table"/> shows the available trigonometric functions. All trigonometric functions take arguments and return values of type <type>double precision</type>. Each of the trigonometric functions comes in @@ -1328,10 +1328,10 @@ <acronym>SQL</acronym> defines some string functions that use key words, rather than commas, to separate arguments. Details are in - <xref linkend="functions-string-sql">. + <xref linkend="functions-string-sql"/>. <productname>PostgreSQL</productname> also provides versions of these functions that use the regular function invocation syntax - (see <xref linkend="functions-string-other">). + (see <xref linkend="functions-string-other"/>). </para> <note> @@ -1343,7 +1343,7 @@ caused surprising behaviors. However, the string concatenation operator (<literal>||</literal>) still accepts non-string input, so long as at least one input is of a string type, as shown in <xref - linkend="functions-string-sql">. For other cases, insert an explicit + linkend="functions-string-sql"/>. For other cases, insert an explicit coercion to <type>text</type> if you need to duplicate the previous behavior. </para> </note> @@ -1504,7 +1504,7 @@ <entry><type>text</type></entry> <entry> Extract substring matching POSIX regular expression. See - <xref linkend="functions-matching"> for more information on pattern + <xref linkend="functions-matching"/> for more information on pattern matching. </entry> <entry><literal>substring('Thomas' from '...$')</literal></entry> @@ -1516,7 +1516,7 @@ <entry><type>text</type></entry> <entry> Extract substring matching <acronym>SQL</acronym> regular expression. - See <xref linkend="functions-matching"> for more information on + See <xref linkend="functions-matching"/> for more information on pattern matching. </entry> <entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry> @@ -1577,8 +1577,8 @@ <para> Additional string manipulation functions are available and are - listed in <xref linkend="functions-string-other">. Some of them are used internally to implement the - <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql">. + listed in <xref linkend="functions-string-other"/>. Some of them are used internally to implement the + <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql"/>. </para> <table id="functions-string-other"> @@ -1702,7 +1702,7 @@ <parameter>string</parameter> must be valid in this encoding. Conversions can be defined by <command>CREATE CONVERSION</command>. Also there are some predefined conversions. See <xref - linkend="conversion-names"> for available conversions. + linkend="conversion-names"/> for available conversions. </entry> <entry><literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal></entry> <entry><literal>text_in_utf8</literal> represented in Latin-1 @@ -1792,7 +1792,7 @@ <entry> Format arguments according to a format string. This function is similar to the C function <function>sprintf</function>. - See <xref linkend="functions-string-format">. + See <xref linkend="functions-string-format"/>. </entry> <entry><literal>format('Hello %s, %1$s', 'World')</literal></entry> <entry><literal>Hello World, World</literal></entry> @@ -1968,7 +1968,7 @@ Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled. - See also <xref linkend="plpgsql-quote-literal-example">. + See also <xref linkend="plpgsql-quote-literal-example"/>. </entry> <entry><literal>quote_ident('Foo bar')</literal></entry> <entry><literal>"Foo bar"</literal></entry> @@ -1989,7 +1989,7 @@ Note that <function>quote_literal</function> returns null on null input; if the argument might be null, <function>quote_nullable</function> is often more suitable. - See also <xref linkend="plpgsql-quote-literal-example">. + See also <xref linkend="plpgsql-quote-literal-example"/>. </entry> <entry><literal>quote_literal(E'O\'Reilly')</literal></entry> <entry><literal>'O''Reilly'</literal></entry> @@ -2019,7 +2019,7 @@ in an <acronym>SQL</acronym> statement string; or, if the argument is null, return <literal>NULL</literal>. Embedded single-quotes and backslashes are properly doubled. - See also <xref linkend="plpgsql-quote-literal-example">. + See also <xref linkend="plpgsql-quote-literal-example"/>. </entry> <entry><literal>quote_nullable(NULL)</literal></entry> <entry><literal>NULL</literal></entry> @@ -2048,7 +2048,7 @@ <entry> Return captured substring(s) resulting from the first match of a POSIX regular expression to the <parameter>string</parameter>. See - <xref linkend="functions-posix-regexp"> for more information. + <xref linkend="functions-posix-regexp"/> for more information. </entry> <entry><literal>regexp_match('foobarbequebaz', '(bar)(beque)')</literal></entry> <entry><literal>{bar,beque}</literal></entry> @@ -2065,7 +2065,7 @@ <entry> Return captured substring(s) resulting from matching a POSIX regular expression to the <parameter>string</parameter>. See - <xref linkend="functions-posix-regexp"> for more information. + <xref linkend="functions-posix-regexp"/> for more information. </entry> <entry><literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal></entry> <entry><literal>{bar}</literal><para><literal>{baz}</literal></para> (2 rows)</entry> @@ -2081,7 +2081,7 @@ <entry><type>text</type></entry> <entry> Replace substring(s) matching a POSIX regular expression. See - <xref linkend="functions-posix-regexp"> for more information. + <xref linkend="functions-posix-regexp"/> for more information. </entry> <entry><literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal></entry> <entry><literal>ThM</literal></entry> @@ -2097,7 +2097,7 @@ <entry><type>text[]</type></entry> <entry> Split <parameter>string</parameter> using a POSIX regular expression as - the delimiter. See <xref linkend="functions-posix-regexp"> for more + the delimiter. See <xref linkend="functions-posix-regexp"/> for more information. </entry> <entry><literal>regexp_split_to_array('hello world', E'\\s+')</literal></entry> @@ -2114,7 +2114,7 @@ <entry><type>setof text</type></entry> <entry> Split <parameter>string</parameter> using a POSIX regular expression as - the delimiter. See <xref linkend="functions-posix-regexp"> for more + the delimiter. See <xref linkend="functions-posix-regexp"/> for more information. </entry> <entry><literal>regexp_split_to_table('hello world', E'\\s+')</literal></entry> @@ -2339,7 +2339,7 @@ <function>format</function> functions are variadic, so it is possible to pass the values to be concatenated or formatted as an array marked with the <literal>VARIADIC</literal> keyword (see <xref - linkend="xfunc-sql-variadic-functions">). The array's elements are + linkend="xfunc-sql-variadic-functions"/>). The array's elements are treated as if they were separate ordinary arguments to the function. If the variadic array argument is NULL, <function>concat</function> and <function>concat_ws</function> return NULL, but @@ -2348,7 +2348,7 @@ <para> See also the aggregate function <function>string_agg</function> in - <xref linkend="functions-aggregate">. + <xref linkend="functions-aggregate"/>. </para> <table id="conversion-names"> @@ -3351,7 +3351,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); <para> The <literal>%I</literal> and <literal>%L</literal> format specifiers are particularly useful for safely constructing dynamic SQL statements. See - <xref linkend="plpgsql-quote-literal-example">. + <xref linkend="plpgsql-quote-literal-example"/>. </para> </sect2> @@ -3375,10 +3375,10 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); <acronym>SQL</acronym> defines some string functions that use key words, rather than commas, to separate arguments. Details are in - <xref linkend="functions-binarystring-sql">. + <xref linkend="functions-binarystring-sql"/>. <productname>PostgreSQL</productname> also provides versions of these functions that use the regular function invocation syntax - (see <xref linkend="functions-binarystring-other">). + (see <xref linkend="functions-binarystring-other"/>). </para> <note> @@ -3498,10 +3498,10 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); <para> Additional binary string manipulation functions are available and - are listed in <xref linkend="functions-binarystring-other">. Some + are listed in <xref linkend="functions-binarystring-other"/>. Some of them are used internally to implement the <acronym>SQL</acronym>-standard string functions listed in <xref - linkend="functions-binarystring-sql">. + linkend="functions-binarystring-sql"/>. </para> <table id="functions-binarystring-other"> @@ -3688,8 +3688,8 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); <para> See also the aggregate function <function>string_agg</function> in - <xref linkend="functions-aggregate"> and the large object functions - in <xref linkend="lo-funcs">. + <xref linkend="functions-aggregate"/> and the large object functions + in <xref linkend="lo-funcs"/>. </para> </sect1> @@ -3707,7 +3707,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); manipulating bit strings, that is values of the types <type>bit</type> and <type>bit varying</type>. Aside from the usual comparison operators, the operators - shown in <xref linkend="functions-bit-string-op-table"> can be used. + shown in <xref linkend="functions-bit-string-op-table"/> can be used. Bit string operands of <literal>&</literal>, <literal>|</literal>, and <literal>#</literal> must be of equal length. When bit shifting, the original length of the string is preserved, as shown @@ -3935,9 +3935,9 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> <note> <para> - If you have <xref linkend="guc-standard-conforming-strings"> turned off, + If you have <xref linkend="guc-standard-conforming-strings"/> turned off, any backslashes you write in literal string constants will need to be - doubled. See <xref linkend="sql-syntax-strings"> for more information. + doubled. See <xref linkend="sql-syntax-strings"/> for more information. </para> </note> @@ -4144,7 +4144,7 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat </indexterm> <para> - <xref linkend="functions-posix-table"> lists the available + <xref linkend="functions-posix-table"/> lists the available operators for pattern matching using POSIX regular expressions. </para> @@ -4277,7 +4277,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation> matching, while flag <literal>g</literal> specifies replacement of each matching substring rather than only the first one. Supported flags (though not <literal>g</literal>) are - described in <xref linkend="posix-embedded-options-table">. + described in <xref linkend="posix-embedded-options-table"/>. </para> <para> @@ -4311,7 +4311,7 @@ regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g') The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described - in <xref linkend="posix-embedded-options-table">. + in <xref linkend="posix-embedded-options-table"/>. </para> <para> @@ -4353,7 +4353,7 @@ SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1]; subexpressions of the <replaceable>pattern</replaceable>, just as described above for <function>regexp_match</function>. <function>regexp_matches</function> accepts all the flags shown - in <xref linkend="posix-embedded-options-table">, plus + in <xref linkend="posix-embedded-options-table"/>, plus the <literal>g</literal> flag which commands it to return all matches, not just the first one. </para> @@ -4407,7 +4407,7 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; The <replaceable>flags</replaceable> parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. <function>regexp_split_to_table</function> supports the flags described in - <xref linkend="posix-embedded-options-table">. + <xref linkend="posix-embedded-options-table"/>. </para> <para> @@ -4513,7 +4513,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; <productname>PostgreSQL</productname> always initially presumes that a regular expression follows the ARE rules. However, the more limited ERE or BRE rules can be chosen by prepending an <firstterm>embedded option</firstterm> - to the RE pattern, as described in <xref linkend="posix-metasyntax">. + to the RE pattern, as described in <xref linkend="posix-metasyntax"/>. This can be useful for compatibility with applications that expect exactly the <acronym>POSIX</acronym> 1003.2 rules. </para> @@ -4539,9 +4539,9 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; Without a quantifier, it matches a match for the atom. With a quantifier, it can match some number of matches of the atom. An <firstterm>atom</firstterm> can be any of the possibilities - shown in <xref linkend="posix-atoms-table">. + shown in <xref linkend="posix-atoms-table"/>. The possible quantifiers and their meanings are shown in - <xref linkend="posix-quantifiers-table">. + <xref linkend="posix-quantifiers-table"/>. </para> <para> @@ -4549,7 +4549,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; specific conditions are met. A constraint can be used where an atom could be used, except it cannot be followed by a quantifier. The simple constraints are shown in - <xref linkend="posix-constraints-table">; + <xref linkend="posix-constraints-table"/>; some more constraints are described later. </para> @@ -4589,7 +4589,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; <entry> <literal>[</literal><replaceable>chars</replaceable><literal>]</literal> </entry> <entry> a <firstterm>bracket expression</firstterm>, matching any one of the <replaceable>chars</replaceable> (see - <xref linkend="posix-bracket-expressions"> for more detail) </entry> + <xref linkend="posix-bracket-expressions"/> for more detail) </entry> </row> <row> @@ -4603,7 +4603,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; <entry> <literal>\</literal><replaceable>c</replaceable> </entry> <entry> where <replaceable>c</replaceable> is alphanumeric (possibly followed by other characters) - is an <firstterm>escape</firstterm>, see <xref linkend="posix-escape-sequences"> + is an <firstterm>escape</firstterm>, see <xref linkend="posix-escape-sequences"/> (AREs only; in EREs and BREs, this matches <replaceable>c</replaceable>) </entry> |