Re: Document NULL

On Sun, Dec 22, 2024 at 7:27 AM jian he <jian(dot)universality(at)gmail(dot)com> wrote:

> 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.
>

I'm aware, which is why I keep mentioning "formatting" in my emails.

Again, I'm choosing to indent those tags because while I edit I find it
much easier if I can "fold all" in my editor and have those tags be hidden
away under the fold.

Please use your imagination to visualize how thIngs would look without the
indentation, or un-indent the elements yourself if you find it so
bothersome to look at. I promise you I will unindent them in
the final patch that would be committed. Until then it is having no
material impact on the substance/content of the patch - which is what needs
reviewing. And since you didn't even apply my formatting 0002 patch the
first time around I figured producing it was simply unneeded busy-work.

I will try to remember to consider/fix the "extra newline" aspect of this
since simply unindenting isn't going to alter vertical space, just
horizontal.

> + <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.
>

Not sure on the "is expected" qualifier but overall that does seem better.

> + 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>
>

The extra detail for text format is out-of-place in this overview document
- csv format is most commonly used so I mention it for the example. I do
not feel a need to provide commentary for other formats or provide other
examples. I do think at least alluding to the other options, so the reader
can go look for them, is a positive. I'll markup psql.

----------------------------------------------------------------------------
>
> + 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.
>

I may have been overly verbose in a bad way but just putting that sentence
here is too concise IMO. Absent a complete suggestion to consider I'm
inclined to stick with what I have.

Thanks!

David J.