On Fri, May 3, 2024 at 8:44 AM Tom Lane <t...@sss.pgh.pa.us> wrote:
> "David G. Johnston" <david.g.johns...@gmail.com> writes: > > On Fri, May 3, 2024 at 7:10 AM Peter Eisentraut <pe...@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. > OK. I was hopeful that once the Chapter existed the annoyance of it being short would be solved by making it longer. If we ever do that, moving this section under there at that point would be an option. > 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. I will go with this and remove the "Data Basics" section I wrote, leaving it to be just a discussion about null values. The tutorial is the only section that really needs unique wording to fit in. No matter where we decide to place it otherwise the core content will be the same, with maybe a different section preface to tie it in. Putting it in an appendix is similarly throwing > to the wind any idea that you can read the documentation in order. > I think we can keep the entire camel out of the tent while letting it get a whiff of what is inside. It would be a summary reference linked to from the various places that mention null values. https://en.wikipedia.org/wiki/Camel%27s_nose > 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. > > Yeah, there is circularity here that is probably impossible to completely resolve. David J.
