On Thu, Jul 14, 2022 at 3:57 PM Tom Lane <t...@sss.pgh.pa.us> wrote: > Bruce Momjian <br...@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.
