Re: Document NULL

On Wed, Dec 11, 2024 at 7:00 AM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> v5 Attached, v5-0001 is just v4-0001 rebased; v5-0002 is the rework over v4-0001. There is no formatting-only patch this round.
>
> Wiki tracker: https://wiki.postgresql.org/wiki/Documenting_NULL#ToDo_Note
>

please see attached png file.
As you can see, many of the <screen> </screen> are not fully
left-aligned, and also have an extra empty new line.

[1] says "This element is displayed "verbatim"; whitespace and
linebreaks within this element are significant.
Screens are usually displayed in a fixed width font."
also see [2] for programlisting

space is scarce, i think empty new lines are not good. to avoid extra
empty new line,
in doc/src/sgml/nullvalues.sgml
all the <programlisting> </programlisting>, <screen>, </screen>
should be completely left-aligned.
----------------------------------------------------------------------------

+ <para>
+ As a general expectation, operator invocation expressions where
one of inputs
+ is a null value will result in a null-valued output.

I think the following description is more simple and concise.
+Typically, when one of the inputs in an operator invocation
expression is a null value, the output is expected to also be null.

+ The <link linkend="sql-copy"><command>COPY ... TO</command></link> command,
+ including its psql counter-part meta-command
+ <link linkend="app-psql-meta-commands-copy"><command>\copy</command></link>,
+ has the <literal>NULL</literal> option (and some modifier
options) to specify
+ the string to print to the output for null values it encounters
in the query result.
+ As with input file processing, for the CSV format it will, by default,
+ produce an unquoted empty string for the null value.
+ </para>

I think the following make more sense:

+ The <link linkend="sql-copy"><command>COPY ... TO</command></link>
command and
+ <application>psql</application> meta-command
+ <link linkend="app-psql-meta-commands-copy"><command>\copy</command></link>,
+ has the <literal>NULL</literal> option to specify
+ the string that represents a null value. The default is
+ <literal>\N</literal> (backslash-N) in text format, and an unquoted empty
+ string in <literal>CSV</literal> format.
+ </para>

also psql should decorated as <application>psql</application>
----------------------------------------------------------------------------

+ It is possible to define
+ <link linkend="ddl-constraints-check-constraints">check constraint</link>
+ expressions on tables to ensure only values passing those
expressions are inserted.
+ While this seems like it would behave the same as a where clause,
the choice here,
+ when an expression evaulates to a null value, is to allow the row
to be inserted
+ - the same as a true result.

i think in ddl.sgml,
we already have """
It should be noted that a check constraint is satisfied if the
check expression evaluates to true or the null value.
"""
it is more concise, IMO, we can just try to copy it here.

[1] https://www.oreilly.com/openbook/docbook/book/screen.html
[2] https://www.oreilly.com/openbook/docbook/book/programlisting.html