mirror of
https://git.postgresql.org/git/postgresql.git
synced 2026-02-19 12:56:59 +08:00
a70bce43fb
The old documentation encourages entering single-user mode for no reason, which is a bad plan in most cases. Instead, discourage users from doing that, and explain the limited cases in which it may be desirable. The old documentation claims that running VACUUM as anyone but the superuser can't possibly work, which is not really true, because it might be that some other user has enough permissions to VACUUM all the tables that matter. Weaken the language just a bit. The old documentation claims that you can't run any commands when near XID exhaustion, which is false because you can still run commands that don't require an XID, like a SELECT without a locking clause. The old documentation doesn't clearly explain that it's a good idea to get rid of prepared transactons, long-running transactions, and replication slots that are preventing (M)XID horizon advancement. Spell out the steps to do that. Also, discourage the use of VACUUM FULL and VACUUM FREEZE in this type of scenario. Back-patch to v14. Much of this is good advice on all supported versions, but before 60f1f09ff44308667ef6c72fbafd68235e55ae27 the chances of VACUUM failing in multi-user mode were much higher. Alexander Alekseev, John Naylor, Robert Haas, reviewed at various times by Peter Geoghegan, Hannu Krosing, and Andres Freund. Discussion: http://postgr.es/m/CA+TgmoYtsUDrzaHcmjFhLzTk1VEv29mO_u-MT+XWHrBJ_4nD8A@mail.gmail.com
<!-- doc/src/sgml/README.links -->
Linking within DocBook documents can be confusing, so here is a summary:
Intra-document Linking
----------------------
<xref>
use to get chapter/section number from the title of the target
link, or xreflabel if defined at the target, or refentrytitle if target
is a refentry; has no close tag
http://www.oasis-open.org/docbook/documentation/reference/html/xref.html
linkend=
controls the target of the link/xref, required
endterm=
for <xref>, allows the text of the link/xref to be taken from a
different link target title
<link>
use to supply text for the link, only uses linkend, requires </link>
http://www.oasis-open.org/docbook/documentation/reference/html/link.html
can be embedded inside of <command>, unlike <xref>
External Linking
----------------
<ulink>
like <link>, but uses a URL (not a document target); requires
</ulink>; if no text is specified, the URL appears as the link
text
http://www.oasis-open.org/docbook/documentation/reference/html/ulink.html
url=
used by <ulink> to specify the URL, required
Guidelines
----------
- For an internal link, if you want to supply text, use <link>, else
<xref>.
- Specific nouns like GUC variables, SQL commands, and contrib modules
usually have xreflabels.
- For an external link, use <ulink>, with or without link text.
- xreflabels added to tags prevent the chapter/section for id's from being
referenced; only the xreflabel is accessible. Therefore, use xreflabels
only when linking is common, and chapter/section information is unneeded.