Doc: explain dollar quoting in the intro part of the pl/pgsql chapter.

We're throwing people into the guts of the syntax with not much context;
let's back up one step and point out that this goes inside a literal in
a CREATE FUNCTION command.  Per suggestion from Kurt Kartaltepe.

Discussion: https://postgr.es/m/CACawnnyWAmH+au8nfZhLiFfWKjXy4d0kY+eZWfcxPRnjVfaa_Q@mail.gmail.com
This commit is contained in:
Tom Lane 2017-07-17 16:43:03 -04:00
parent cde11fa3c0
commit 533463307b
1 changed files with 19 additions and 1 deletions

View File

@ -179,9 +179,27 @@
<sect1 id="plpgsql-structure">
<title>Structure of <application>PL/pgSQL</application></title>
<para>
Functions written in <application>PL/pgSQL</application> are defined
to the server by executing <xref linkend="sql-createfunction"> commands.
Such a command would normally look like, say,
<programlisting>
CREATE FUNCTION somefunc(integer, text) RETURNS integer
AS '<replaceable>function body text</>'
LANGUAGE plpgsql;
</programlisting>
The function body is simply a string literal so far as <command>CREATE
FUNCTION</> is concerned. It is often helpful to use dollar quoting
(see <xref linkend="sql-syntax-dollar-quoting">) to write the function
body, rather than the normal single quote syntax. Without dollar quoting,
any single quotes or backslashes in the function body must be escaped by
doubling them. Almost all the examples in this chapter use dollar-quoted
literals for their function bodies.
</para>
<para>
<application>PL/pgSQL</application> is a block-structured language.
The complete text of a function definition must be a
The complete text of a function body must be a
<firstterm>block</>. A block is defined as:
<synopsis>