Re: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter

On Thu, Jul 14, 2022 at 3:57 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > On Mon, Apr 25, 2022 at 08:33:47AM -0700, David G. Johnston wrote:
> >> Both the location and name of the linked to section make no sense to me:
> >> https://www.postgresql.org/docs/current/functions-admin.html#
> >> FUNCTIONS-ADMIN-DBOBJECT
> >> Neither of the tables listed there manage (cause to change) anything.
> They are
> >> pure informational functions - size and path of objects respectively.
> It
> >> belongs in the previous chapter "System Information Functions and
> Operators"
> >> with a different name.
>
> > So, the section title is:
> > 9.27.7. Database Object Management Functions
> > I think the idea is that they _help_ to manage database objects by
> > reporting their size or location. I do think it is in the right
> > chapter, but maybe needs a better title? I can't think of one.
>
> I'm hesitant to move functions to a different documentation page
> without a really solid reason. Just a couple days ago I fielded a
> complaint from somebody who couldn't find string_to_array anymore
> because we'd moved it from "array functions" to "string functions".
>
> I'd be the first to say that the division between 9.26 and 9.27 is
> pretty arbitrary ... but without a clearer demarcation rule,
> moving functions between the two pages seems more likely to
> add confusion than subtract it.
>
>
I'm not going to fight the prevailing winds on this one, much...but I've
probably been sitting on this annoyance for years since I use the ToC to
find stuff fairly quickly in the docs. This seems much more clear to me
than a function than deciding whether a function that converts a string
into an array belongs in the string chapter or the array chapter.

On a related note, why itemize 9.27 in the table of contents but not 9.26?

I would ask that we at least rename it to:

Disk Usage Functions

Since this would show in the ToC finding the name of the functions that
allow one to compute disk usage, which is a question I probably see once a
year, and what motivates this request, would be more likely to be found
without skimming the entire 9.26 chapter (since I cannot see those table
heading in the ToC) and not finding it and then stumbling upon in on a
table the only deals with sizes but whose headers says nothing about sizes.

David J.