database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-10-27 00:12:01 +03:00
Code Activity

Don't use SGML empty tags

Browse Source 
For DocBook XML compatibility, don't use SGML empty tags (</>) anymore,
replace by the full tag name.  Add a warning option to catch future
occurrences.

Alexander Lakhin, Jürgen Purtz
This commit is contained in:
Peter Eisentraut
2017-10-08 21:44:17 -04:00
parent 6ecabead4b
commit c29c578908
337 changed files with 31636 additions and 31635 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
doc/src/sgml/sources.sgml
View File

@@ -14,8 +14,8 @@
<para>
Layout rules (brace positioning, etc) follow BSD conventions. In
particular, curly braces for the controlled blocks of <literal>if</>,
<literal>while</>, <literal>switch</>, etc go on their own lines.
particular, curly braces for the controlled blocks of <literal>if</literal>,
<literal>while</literal>, <literal>switch</literal>, etc go on their own lines.
</para>
<para>
@@ -26,7 +26,7 @@
</para>
<para>
Do not use C++ style comments (<literal>//</> comments). Strict ANSI C
Do not use C++ style comments (<literal>//</literal> comments). Strict ANSI C
compilers do not accept them. For the same reason, do not use C++
extensions such as declaring new variables mid-block.
</para>
@@ -40,7 +40,7 @@
*/
</programlisting>
Note that comment blocks that begin in column 1 will be preserved as-is
by <application>pgindent</>, but it will re-flow indented comment blocks
by <application>pgindent</application>, but it will re-flow indented comment blocks
as though they were plain text. If you want to preserve the line breaks
in an indented block, add dashes like this:
<programlisting>
@@ -55,10 +55,10 @@
<para>
While submitted patches do not absolutely have to follow these formatting
rules, it's a good idea to do so. Your code will get run through
<application>pgindent</> before the next release, so there's no point in
<application>pgindent</application> before the next release, so there's no point in
making it look nice under some other set of formatting conventions.
A good rule of thumb for patches is <quote>make the new code look like
the existing code around it</>.
the existing code around it</quote>.
</para>
<para>
@@ -92,37 +92,37 @@ less -x4
<para>
Error, warning, and log messages generated within the server code
should be created using <function>ereport</>, or its older cousin
<function>elog</>. The use of this function is complex enough to
should be created using <function>ereport</function>, or its older cousin
<function>elog</function>. The use of this function is complex enough to
require some explanation.
</para>
<para>
There are two required elements for every message: a severity level
(ranging from <literal>DEBUG</> to <literal>PANIC</>) and a primary
(ranging from <literal>DEBUG</literal> to <literal>PANIC</literal>) and a primary
message text. In addition there are optional elements, the most
common of which is an error identifier code that follows the SQL spec's
SQLSTATE conventions.
<function>ereport</> itself is just a shell function, that exists
<function>ereport</function> itself is just a shell function, that exists
mainly for the syntactic convenience of making message generation
look like a function call in the C source code. The only parameter
accepted directly by <function>ereport</> is the severity level.
accepted directly by <function>ereport</function> is the severity level.
The primary message text and any optional message elements are
generated by calling auxiliary functions, such as <function>errmsg</>,
within the <function>ereport</> call.
generated by calling auxiliary functions, such as <function>errmsg</function>,
within the <function>ereport</function> call.
</para>
<para>
A typical call to <function>ereport</> might look like this:
A typical call to <function>ereport</function> might look like this:
<programlisting>
ereport(ERROR,
(errcode(ERRCODE_DIVISION_BY_ZERO),
errmsg("division by zero")));
</programlisting>
This specifies error severity level <literal>ERROR</> (a run-of-the-mill
error). The <function>errcode</> call specifies the SQLSTATE error code
using a macro defined in <filename>src/include/utils/errcodes.h</>. The
<function>errmsg</> call provides the primary message text. Notice the
This specifies error severity level <literal>ERROR</literal> (a run-of-the-mill
error). The <function>errcode</function> call specifies the SQLSTATE error code
using a macro defined in <filename>src/include/utils/errcodes.h</filename>. The
<function>errmsg</function> call provides the primary message text. Notice the
extra set of parentheses surrounding the auxiliary function calls &mdash;
these are annoying but syntactically necessary.
</para>
@@ -139,72 +139,72 @@ ereport(ERROR,
"You might need to add explicit typecasts.")));
</programlisting>
This illustrates the use of format codes to embed run-time values into
a message text. Also, an optional <quote>hint</> message is provided.
a message text. Also, an optional <quote>hint</quote> message is provided.
</para>
<para>
If the severity level is <literal>ERROR</> or higher,
<function>ereport</> aborts the execution of the user-defined
If the severity level is <literal>ERROR</literal> or higher,
<function>ereport</function> aborts the execution of the user-defined
function and does not return to the caller. If the severity level is
lower than <literal>ERROR</>, <function>ereport</> returns normally.
lower than <literal>ERROR</literal>, <function>ereport</function> returns normally.
</para>
<para>
The available auxiliary routines for <function>ereport</> are:
The available auxiliary routines for <function>ereport</function> are:
<itemizedlist>
<listitem>
<para>
<function>errcode(sqlerrcode)</function> specifies the SQLSTATE error identifier
code for the condition. If this routine is not called, the error
identifier defaults to
<literal>ERRCODE_INTERNAL_ERROR</> when the error severity level is
<literal>ERROR</> or higher, <literal>ERRCODE_WARNING</> when the
error level is <literal>WARNING</>, otherwise (for <literal>NOTICE</>
and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</>.
<literal>ERRCODE_INTERNAL_ERROR</literal> when the error severity level is
<literal>ERROR</literal> or higher, <literal>ERRCODE_WARNING</literal> when the
error level is <literal>WARNING</literal>, otherwise (for <literal>NOTICE</literal>
and below) <literal>ERRCODE_SUCCESSFUL_COMPLETION</literal>.
While these defaults are often convenient, always think whether they
are appropriate before omitting the <function>errcode()</> call.
are appropriate before omitting the <function>errcode()</function> call.
</para>
</listitem>
<listitem>
<para>
<function>errmsg(const char *msg, ...)</function> specifies the primary error
message text, and possibly run-time values to insert into it. Insertions
are specified by <function>sprintf</>-style format codes. In addition to
the standard format codes accepted by <function>sprintf</>, the format
code <literal>%m</> can be used to insert the error message returned
by <function>strerror</> for the current value of <literal>errno</>.
are specified by <function>sprintf</function>-style format codes. In addition to
the standard format codes accepted by <function>sprintf</function>, the format
code <literal>%m</literal> can be used to insert the error message returned
by <function>strerror</function> for the current value of <literal>errno</literal>.
<footnote>
<para>
That is, the value that was current when the <function>ereport</> call
was reached; changes of <literal>errno</> within the auxiliary reporting
That is, the value that was current when the <function>ereport</function> call
was reached; changes of <literal>errno</literal> within the auxiliary reporting
routines will not affect it. That would not be true if you were to
write <literal>strerror(errno)</> explicitly in <function>errmsg</>'s
write <literal>strerror(errno)</literal> explicitly in <function>errmsg</function>'s
parameter list; accordingly, do not do so.
</para>
</footnote>
<literal>%m</> does not require any
corresponding entry in the parameter list for <function>errmsg</>.
Note that the message string will be run through <function>gettext</>
<literal>%m</literal> does not require any
corresponding entry in the parameter list for <function>errmsg</function>.
Note that the message string will be run through <function>gettext</function>
for possible localization before format codes are processed.
</para>
</listitem>
<listitem>
<para>
<function>errmsg_internal(const char *msg, ...)</function> is the same as
<function>errmsg</>, except that the message string will not be
<function>errmsg</function>, except that the message string will not be
translated nor included in the internationalization message dictionary.
This should be used for <quote>cannot happen</> cases that are probably
This should be used for <quote>cannot happen</quote> cases that are probably
not worth expending translation effort on.
</para>
</listitem>
<listitem>
<para>
<function>errmsg_plural(const char *fmt_singular, const char *fmt_plural,
unsigned long n, ...)</function> is like <function>errmsg</>, but with
unsigned long n, ...)</function> is like <function>errmsg</function>, but with
support for various plural forms of the message.
<replaceable>fmt_singular</> is the English singular format,
<replaceable>fmt_plural</> is the English plural format,
<replaceable>n</> is the integer value that determines which plural
<replaceable>fmt_singular</replaceable> is the English singular format,
<replaceable>fmt_plural</replaceable> is the English plural format,
<replaceable>n</replaceable> is the integer value that determines which plural
form is needed, and the remaining arguments are formatted according
to the selected format string. For more information see
<xref linkend="nls-guidelines">.
@@ -213,16 +213,16 @@ ereport(ERROR,
<listitem>
<para>
<function>errdetail(const char *msg, ...)</function> supplies an optional
<quote>detail</> message; this is to be used when there is additional
<quote>detail</quote> message; this is to be used when there is additional
information that seems inappropriate to put in the primary message.
The message string is processed in just the same way as for
<function>errmsg</>.
<function>errmsg</function>.
</para>
</listitem>
<listitem>
<para>
<function>errdetail_internal(const char *msg, ...)</function> is the same
as <function>errdetail</>, except that the message string will not be
as <function>errdetail</function>, except that the message string will not be
translated nor included in the internationalization message dictionary.
This should be used for detail messages that are not worth expending
translation effort on, for instance because they are too technical to be
@@ -232,7 +232,7 @@ ereport(ERROR,
<listitem>
<para>
<function>errdetail_plural(const char *fmt_singular, const char *fmt_plural,
unsigned long n, ...)</function> is like <function>errdetail</>, but with
unsigned long n, ...)</function> is like <function>errdetail</function>, but with
support for various plural forms of the message.
For more information see <xref linkend="nls-guidelines">.
</para>
@@ -240,10 +240,10 @@ ereport(ERROR,
<listitem>
<para>
<function>errdetail_log(const char *msg, ...)</function> is the same as
<function>errdetail</> except that this string goes only to the server
log, never to the client. If both <function>errdetail</> (or one of
<function>errdetail</function> except that this string goes only to the server
log, never to the client. If both <function>errdetail</function> (or one of
its equivalents above) and
<function>errdetail_log</> are used then one string goes to the client
<function>errdetail_log</function> are used then one string goes to the client
and the other to the log. This is useful for error details that are
too security-sensitive or too bulky to include in the report
sent to the client.
@@ -253,7 +253,7 @@ ereport(ERROR,
<para>
<function>errdetail_log_plural(const char *fmt_singular, const char
*fmt_plural, unsigned long n, ...)</function> is like
<function>errdetail_log</>, but with support for various plural forms of
<function>errdetail_log</function>, but with support for various plural forms of
the message.
For more information see <xref linkend="nls-guidelines">.
</para>
@@ -261,23 +261,23 @@ ereport(ERROR,
<listitem>
<para>
<function>errhint(const char *msg, ...)</function> supplies an optional
<quote>hint</> message; this is to be used when offering suggestions
<quote>hint</quote> message; this is to be used when offering suggestions
about how to fix the problem, as opposed to factual details about
what went wrong.
The message string is processed in just the same way as for
<function>errmsg</>.
<function>errmsg</function>.
</para>
</listitem>
<listitem>
<para>
<function>errcontext(const char *msg, ...)</function> is not normally called
directly from an <function>ereport</> message site; rather it is used
in <literal>error_context_stack</> callback functions to provide
directly from an <function>ereport</function> message site; rather it is used
in <literal>error_context_stack</literal> callback functions to provide
information about the context in which an error occurred, such as the
current location in a PL function.
The message string is processed in just the same way as for
<function>errmsg</>. Unlike the other auxiliary functions, this can
be called more than once per <function>ereport</> call; the successive
<function>errmsg</function>. Unlike the other auxiliary functions, this can
be called more than once per <function>ereport</function> call; the successive
strings thus supplied are concatenated with separating newlines.
</para>
</listitem>
@@ -309,9 +309,9 @@ ereport(ERROR,
specifies a table constraint whose name, table name, and schema name
should be included as auxiliary fields in the error report. Indexes
should be considered to be constraints for this purpose, whether or
not they have an associated <structname>pg_constraint</> entry. Be
not they have an associated <structname>pg_constraint</structname> entry. Be
careful to pass the underlying heap relation, not the index itself, as
<literal>rel</>.
<literal>rel</literal>.
</para>
</listitem>
<listitem>
@@ -330,17 +330,17 @@ ereport(ERROR,
</listitem>
<listitem>
<para>
<function>errcode_for_file_access()</> is a convenience function that
<function>errcode_for_file_access()</function> is a convenience function that
selects an appropriate SQLSTATE error identifier for a failure in a
file-access-related system call. It uses the saved
<literal>errno</> to determine which error code to generate.
Usually this should be used in combination with <literal>%m</> in the
<literal>errno</literal> to determine which error code to generate.
Usually this should be used in combination with <literal>%m</literal> in the
primary error message text.
</para>
</listitem>
<listitem>
<para>
<function>errcode_for_socket_access()</> is a convenience function that
<function>errcode_for_socket_access()</function> is a convenience function that
selects an appropriate SQLSTATE error identifier for a failure in a
socket-related system call.
</para>
@@ -348,7 +348,7 @@ ereport(ERROR,
<listitem>
<para>
<function>errhidestmt(bool hide_stmt)</function> can be called to specify
suppression of the <literal>STATEMENT:</> portion of a message in the
suppression of the <literal>STATEMENT:</literal> portion of a message in the
postmaster log. Generally this is appropriate if the message text
includes the current statement already.
</para>
@@ -356,7 +356,7 @@ ereport(ERROR,
<listitem>
<para>
<function>errhidecontext(bool hide_ctx)</function> can be called to
specify suppression of the <literal>CONTEXT:</> portion of a message in
specify suppression of the <literal>CONTEXT:</literal> portion of a message in
the postmaster log. This should only be used for verbose debugging
messages where the repeated inclusion of context would bloat the log
volume too much.
@@ -367,24 +367,24 @@ ereport(ERROR,
<note>
<para>
At most one of the functions <function>errtable</>,
<function>errtablecol</>, <function>errtableconstraint</>,
<function>errdatatype</>, or <function>errdomainconstraint</> should
be used in an <function>ereport</> call. These functions exist to
At most one of the functions <function>errtable</function>,
<function>errtablecol</function>, <function>errtableconstraint</function>,
<function>errdatatype</function>, or <function>errdomainconstraint</function> should
be used in an <function>ereport</function> call. These functions exist to
allow applications to extract the name of a database object associated
with the error condition without having to examine the
potentially-localized error message text.
These functions should be used in error reports for which it's likely
that applications would wish to have automatic error handling. As of
<productname>PostgreSQL</> 9.3, complete coverage exists only for
<productname>PostgreSQL</productname> 9.3, complete coverage exists only for
errors in SQLSTATE class 23 (integrity constraint violation), but this
is likely to be expanded in future.
</para>
</note>
<para>
There is an older function <function>elog</> that is still heavily used.
An <function>elog</> call:
There is an older function <function>elog</function> that is still heavily used.
An <function>elog</function> call:
<programlisting>
elog(level, "format string", ...);
</programlisting>
@@ -394,11 +394,11 @@ ereport(level, (errmsg_internal("format string", ...)));
</programlisting>
Notice that the SQLSTATE error code is always defaulted, and the message
string is not subject to translation.
Therefore, <function>elog</> should be used only for internal errors and
Therefore, <function>elog</function> should be used only for internal errors and
low-level debug logging. Any message that is likely to be of interest to
ordinary users should go through <function>ereport</>. Nonetheless,
there are enough internal <quote>cannot happen</> error checks in the
system that <function>elog</> is still widely used; it is preferred for
ordinary users should go through <function>ereport</function>. Nonetheless,
there are enough internal <quote>cannot happen</quote> error checks in the
system that <function>elog</function> is still widely used; it is preferred for
those messages for its notational simplicity.
</para>
@@ -414,7 +414,7 @@ ereport(level, (errmsg_internal("format string", ...)));
<para>
This style guide is offered in the hope of maintaining a consistent,
user-friendly style throughout all the messages generated by
<productname>PostgreSQL</>.
<productname>PostgreSQL</productname>.
</para>
<simplesect>
@@ -643,7 +643,7 @@ cannot open file "%s"
</para>
<para>
Rationale: Otherwise no one will know what <quote>foo.bar.baz</>
Rationale: Otherwise no one will know what <quote>foo.bar.baz</quote>
refers to.
</para>
@@ -866,7 +866,7 @@ BETTER: unrecognized node type: 42
<simplesect>
<title>C Standard</title>
<para>
Code in <productname>PostgreSQL</> should only rely on language
Code in <productname>PostgreSQL</productname> should only rely on language
features available in the C89 standard. That means a conforming
C89 compiler has to be able to compile postgres, at least aside
from a few platform dependent pieces. Features from later
@@ -874,7 +874,7 @@ BETTER: unrecognized node type: 42
used, if a fallback is provided.
</para>
<para>
For example <literal>static inline</> and
For example <literal>static inline</literal> and
<literal>_StaticAssert()</literal> are currently used, even
though they are from newer revisions of the C standard. If not
available we respectively fall back to defining the functions
@@ -886,7 +886,7 @@ BETTER: unrecognized node type: 42
<simplesect>
<title>Function-Like Macros and Inline Functions</title>
<para>
Both, macros with arguments and <literal>static inline</>
Both, macros with arguments and <literal>static inline</literal>
functions, may be used. The latter are preferable if there are
multiple-evaluation hazards when written as a macro, as e.g. the
case with
@@ -914,7 +914,7 @@ MemoryContextSwitchTo(MemoryContext context)
}
#endif /* FRONTEND */
</programlisting>
In this example <literal>CurrentMemoryContext</>, which is only
In this example <literal>CurrentMemoryContext</literal>, which is only
available in the backend, is referenced and the function thus
hidden with a <literal>#ifndef FRONTEND</literal>. This rule
exists because some compilers emit references to symbols
@@ -957,8 +957,8 @@ handle_sighup(SIGNAL_ARGS)
errno = save_errno;
}
</programlisting>
<varname>errno</> is saved and restored because
<function>SetLatch()</> might change it. If that were not done
<varname>errno</varname> is saved and restored because
<function>SetLatch()</function> might change it. If that were not done
interrupted code that's currently inspecting <varname>errno</varname> might see the wrong
value.
</para>