Re: Document NULL - Mailing list pgsql-hackers
| From | David G. Johnston |
|---|---|
| Subject | Re: Document NULL |
| Date | |
| Msg-id | CAKFQuwY7=us5wG2SxLTdLLT-9M+BNDOz5d=84VGQv+JVG-W7pQ@mail.gmail.com Whole thread Raw |
| In response to | Document NULL ("David G. Johnston" <david.g.johnston@gmail.com>) |
| Responses |
Re: Document NULL
|
| List | pgsql-hackers |
On Sun, Dec 22, 2024 at 7:27 AM jian he <jian.universality@gmail.com> wrote:
On Wed, Dec 11, 2024 at 7:00 AM David G. Johnston
<david.g.johnston@gmail.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.
pgsql-hackers by date: