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 f9307f329ec..34b829eade2 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]) diff --git a/configure b/configure index b31134832e9..3203473f874 100755 --- a/configure +++ b/configure @@ -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 3f26f038d6e..d9c4a50b4b6 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 df77a142e4d..f122b4187f4 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 b27a4a325d9..1197eefbf31 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 bf87df4dcb1..ae5f3fac75e 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 0dd68f0ba14..852e260c098 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 d49901c6900..53f8049df38 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 9187f6e02e7..f4d4a610ef3 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 9221d2dfb65..bd3ef7128d5 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 240098c82f7..08b67f2600b 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 39bb25c8e24..9d8e69056f7 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 0b092f6e492..4bc2b696b3f 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 b7483df4c08..23c0e05ed6c 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 ef60a58631a..da881a77371 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 ce395e115a3..dc3fd34a624 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 99921ba0793..c8a1bc79aa6 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 7059dd4e5f5..3060597011d 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"/>). |