"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Fri, May 3, 2024 at 7:10 AM Peter Eisentraut <peter@eisentraut.org>
> wrote:
>> On 02.05.24 17:23, David G. Johnston wrote:
>>> I chose to add a new sect1 in the user guide (The SQL Language) chapter,
>>> "Data".
>> Please, let's not.
> If a committer wants to state the single place in the documentation to put
> this I'm content to put it there while leaving my reasoning of choices in
> place for future bike-shedding. My next options to decide between are the
> appendix or the lead chapter in Data Types. It really doesn't fit inside
> DDL IMO which is the only other suggestion I've seen (and an uncertain, or
> at least unsubstantiated, one) and a new chapter meets both criteria Tom
> laid out, so long as this is framed as more than just having to document
> null values.
I could see going that route if we actually had a chapter's worth of
material to put into "Data". But we don't, there's really only one
not-very-long section. Robert has justifiably complained about that
sort of thing elsewhere in the docs, and I don't want to argue with
him about why it'd be OK here.
Having said that, I reiterate my proposal that we make it a new
<sect1> under DDL, before 5.2 Default Values which is the first
place in ddl.sgml that assumes you have heard of nulls. Sure,
it's not totally ideal, but noplace is going to be entirely
perfect. I can see some attraction in dropping it under Data Types,
but (a) null is a data-type-independent concept, and (b) the
chapters before that are just full of places that assume you have
heard of nulls. Putting it in an appendix is similarly throwing
to the wind any idea that you can read the documentation in order.
Really, even the syntax chapter has some mentions of nulls.
If we did have a "Data" chapter there would be a case for
putting it as the *first* chapter of Part II.
I suppose we could address the nonlinearity gripe with a bunch
of cross-reference links, in which case maybe something under
Data Types is the least bad approach.
regards, tom lane