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

On Mon, Apr 25, 2022 at 08:33:47AM -0700, David G. Johnston wrote:

Hi,

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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson

Bruce Momjian <bruce@momjian.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.

regards, tom lane

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

Bruce Momjian <bruce@momjian.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.

On Fri, Jul 15, 2022 at 12:36 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

I would ask that we at least rename it to:

Disk Usage Functions

Nevermind...I identified the scope of that header incorrectly and the
rename wouldn't be appropriate for the other tables in that section.

David J.