Thread: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
From
"David G. Johnston"
Date:
Hi,
Both the location and name of the linked to section make no sense to me:
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.
David J.
Re: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
From
Bruce Momjian
Date:
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
Re: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
From
Tom Lane
Date:
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
Re: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
From
"David G. Johnston"
Date:
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.
Re: Move Section 9.27.7 (Data Object Management Functions) to System Information Chapter
From
"David G. Johnston"
Date:
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.