>
> I've splitted it to7 patches.
> each patch split one into separate new files.
>
Seems like a good start. Looking at the diffs of these, I wonder if we
would be better off with a func/ directory, each function gets its own file
in that dir, and either these files above include the individual
On Wed, Apr 17, 2024 at 7:07 PM Dagfinn Ilmari Mannsåker
wrote:
>
>
> > It'd also be quite useful if clients could render more of the documentation
> > for functions. People are used to language servers providing full
> > documentation for functions etc...
>
> A more user-friendly version of \df+
>
> Yeah, we can't expect everyone wanting to call a built-in function to
> know how they would define an equivalent one themselves. In that case I
> propos marking it up like this:
>
> format (
> formatstr text
> , formatarg "any"
> , ... )
> text
>
Looks good, but I guess I
Corey Huinker writes:
>>
>> I havent dealt with variadic yet, since the two styles are visually
>> different, not just markup (... renders as [...]).
>>
>> The two styles for variadic are the what I call caller-style:
>>
>>concat ( val1 "any" [, val2 "any" [, ...] ] )
>>format(formatstr
>
> I havent dealt with variadic yet, since the two styles are visually
> different, not just markup (... renders as [...]).
>
> The two styles for variadic are the what I call caller-style:
>
>concat ( val1 "any" [, val2 "any" [, ...] ] )
>format(formatstr text [, formatarg "any" [, ...]
On Thu, Apr 18, 2024 at 2:37 AM Dagfinn Ilmari Mannsåker
wrote:
>
> Andres Freund writes:
>
> > Hi,
> >
> > On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Mannsåker wrote:
> >> Andres Freund writes:
> >> > I think the manual work for writing signatures in sgml is not
> >> > insignificant,
> >> >
Andres Freund writes:
> Hi,
>
> On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Mannsåker wrote:
>> Andres Freund writes:
>> > I think the manual work for writing signatures in sgml is not
>> > insignificant,
>> > nor is the volume of sgml for them. Manually maintaining the signatures
>> > makes
Hi,
On 2024-04-17 12:07:24 +0100, Dagfinn Ilmari Mannsåker wrote:
> Andres Freund writes:
> > I think the manual work for writing signatures in sgml is not insignificant,
> > nor is the volume of sgml for them. Manually maintaining the signatures
> > makes
> > it impractical to significantly
Hi,
On 2024-04-17 02:46:53 -0400, Corey Huinker wrote:
> > > This sounds to me like it would be a painful exercise with not a
> > > lot of benefit in the end.
> >
> > Maybe we could _verify_ the contents of func.sgml against pg_proc.
> >
>
> All of the functions redefined in
>
> And it's very inconsistent. For example, some functions use
> tags for optional parameters, others use square brackets, and some use
> VARIADIC to indicate variadic parameters, others use
> ellipses (sometimes in tags or brackets).
Having just written a couple of those functions, I wasn't
Andres Freund writes:
> Definitely shouldn't be the same in all cases, but I think there's a decent
> number of cases where they can be the same. The differences between the two is
> often minimal today.
>
> Entirely randomly chosen example:
>
> { oid => '2825',
> descr => 'slope of the
>
> > This sounds to me like it would be a painful exercise with not a
> > lot of benefit in the end.
>
> Maybe we could _verify_ the contents of func.sgml against pg_proc.
>
All of the functions redefined in catalog/system_functions.sql complicate
using pg_proc.dat as a doc generator or source
Hi,
On 2024-04-16 15:05:32 -0400, Tom Lane wrote:
> Andres Freund writes:
> > I think we should work on generating a lot of func.sgml. Particularly the
> > signature etc should just come from pg_proc.dat, it's pointlessly painful to
> > generate that by hand. And for a lot of the functions we
On Tue, Apr 16, 2024 at 03:05:32PM -0400, Tom Lane wrote:
> Andres Freund writes:
> > I think we should work on generating a lot of func.sgml. Particularly the
> > signature etc should just come from pg_proc.dat, it's pointlessly painful to
> > generate that by hand. And for a lot of the
Andres Freund writes:
> I think we should work on generating a lot of func.sgml. Particularly the
> signature etc should just come from pg_proc.dat, it's pointlessly painful to
> generate that by hand. And for a lot of the functions we should probably move
> the existing func.sgml comments to
Hi,
On 2024-03-19 17:39:39 -0400, Andrew Dunstan wrote:
> My own pet docs peeve is a purely editorial one: func.sgml is a 30k line
> beast, and I think there's a good case for splitting out at least the
> larger chunks of it.
I think we should work on generating a lot of func.sgml. Particularly
On Mon, Apr 8, 2024 at 10:15 AM Peter Eisentraut wrote:
> > Here is a new version of this patch. I think this is v18 material at
> > this point, absent an outcry to the contrary. Sometimes we're flexible
> > about doc patches.
>
> Looks good to me. I think this could go into PG17.
Hearing no
On Wed, Mar 20, 2024 at 5:40 AM Andrew Dunstan wrote:
>
>
> +many for improving the index.
>
> My own pet docs peeve is a purely editorial one: func.sgml is a 30k line
> beast, and I think there's a good case for splitting out at least the larger
> chunks of it.
>
I think I successfully
On 05.04.24 17:11, Robert Haas wrote:
4. Consolidate the "Generic WAL Records" and "Custom WAL Resource
Managers" chapters, which cover related topics, into a single one. I
didn't see anyone object to this, but David Johnston pointed out that
the patch I posted was a few bricks short of a load,
On Fri, Apr 5, 2024 at 9:18 AM Robert Haas wrote:
> On Fri, Apr 5, 2024 at 12:15 PM David G. Johnston
> wrote:
> > Here is a link to my attempt at this a couple of years ago. It
> basically "abuses" refentry.
> >
> >
>
On Fri, Apr 5, 2024 at 12:15 PM David G. Johnston
wrote:
> Here is a link to my attempt at this a couple of years ago. It basically
> "abuses" refentry.
>
> https://www.postgresql.org/message-id/CAKFQuwaVm%3D6d_sw9Wrp4cdSm5_k%3D8ZVx0--v2v4BH4KnJtqXqg%40mail.gmail.com
>
> I never did dive into
On Fri, Apr 5, 2024 at 9:01 AM Robert Haas wrote:
>
> > The rendering can be adjusted to some degree, but then we also need to
> > make sure any new chunking makes sense in other chapters. (And it might
> > also change a bunch of externally known HTML links.)
>
> I looked into this and I'm
index and add a new landing page
alongside it. Something that isn't derived automatically from the
documentation structure but is created by hand.
--
Robert Haas
EDB: http://www.enterprisedb.com
On Fri, Mar 29, 2024 at 9:40 AM Robert Haas wrote:
> 2. Demote "Monitoring Disk Usage" from a chapter on its own to a
> section of the "Monitoring Database Activity" chapter. I haven't seen
> any objections to this, and I'd like to move ahead with it.
>
> 3. Merge the separate chapters on various
OK, so I'm coming back to this thread after giving it a few days to
cool off. My last series of patches proposed to do five things:
1. Merge the four-sentence "Installation from Binaries" chapter back
into "Installation from Source". I thought this was a slam-dunk, but
Peter pointed out that
On Mon, Mar 25, 2024 at 11:40 AM Peter Eisentraut wrote:
> I think a possible problem we need to consider with these proposals to
> combine chapters is that they could make the chapters themselves too
> deep and harder to navigate. For example, if we combined the
> installation from source and
On 22.03.24 15:10, Robert Haas wrote:
Sorry. I didn't mean to dispute the point that the section was added a
few years ago, nor the point that most people just want to read about
the binaries. I am confident that both of those things are true. What
I do want to dispute is that having a
On 22.03.24 14:59, Robert Haas wrote:
And I don't believe that if someone were writing a physical book about
PostgreSQL from scratch, they'd ever end up with a top-level chapter
that looks anything like our GiST chapter. All of the index AM
chapters are quite obviously clones of each other, and
On Fri, Mar 22, 2024 at 3:17 PM Bruce Momjian wrote:
> I agree and they should be with the other views. I was just explaining
> why, at the time, I didn't touch them.
Ah, OK. That makes total sense.
--
Robert Haas
EDB: http://www.enterprisedb.com
On Fri, Mar 22, 2024 at 03:13:29PM -0400, Robert Haas wrote:
> On Fri, Mar 22, 2024 at 2:59 PM Bruce Momjian wrote:
> > I assume statistics collector views are in "Monitoring Database
> > Activity" because that is their purpose.
>
> Well, yes. :-)
>
> But the point is that all other statistics
On Fri, Mar 22, 2024 at 2:59 PM Bruce Momjian wrote:
> I assume statistics collector views are in "Monitoring Database
> Activity" because that is their purpose.
Well, yes. :-)
But the point is that all other statistics views are in a single
section regardless of their purpose. We don't
On Fri, Mar 22, 2024 at 11:19 AM Robert Haas wrote:
> On Fri, Mar 22, 2024 at 1:35 PM Bruce Momjian wrote:
>
> But that all seems like a separate question from why we have the
> statistic collector views in a completely different part of the
> documentation from the rest of the system views. My
On Fri, Mar 22, 2024 at 02:19:29PM -0400, Robert Haas wrote:
> If you were actually looking for the section called "System Views",
> you weren't likely to see it here unless you already knew it was
> there, because it was 64 items into a 97-item list. Having one of
> these two sections inside the
On Fri, Mar 22, 2024 at 1:35 PM Bruce Momjian wrote:
> > One question I have is why all of these views are documented here
> > rather than in chapter 53, "System Views," because surely they are
> > system views. I feel like if our documentation index weren't a mile
> > long and if you could
On Fri, Mar 22, 2024 at 08:32:14AM -0400, Robert Haas wrote:
> On Thu, Mar 21, 2024 at 6:32 PM David G. Johnston
> wrote:
> > Just going to note that the section on the cumulative statistics views
> > being a single page is still a strongly bothersome issue here. Though the
> > quick fix
On Fri, Mar 22, 2024, 09:32 Robert Haas wrote:
>
>
> I notice that you say that the "Installation" section should "cover
> the architectural overview and point people to where they can find the
> stuff they need to install PostgreSQL in the various ways available to
> them" so maybe you're not
On Fri, Mar 22, 2024 at 11:50 AM David G. Johnston
wrote:
> On Fri, Mar 22, 2024 at 7:10 AM Robert Haas wrote:
>> That's actually what we had in chapter
>> 18, "Installation from Source Code on Windows", since removed. But for
>> some reason we decided that on non-Windows platforms, it needed a
On Fri, Mar 22, 2024 at 7:10 AM Robert Haas wrote:
>
> That's actually what we had in chapter
> 18, "Installation from Source Code on Windows", since removed. But for
> some reason we decided that on non-Windows platforms, it needed a
> whole new chapter rather than an extra sentence in the
On Fri, Mar 22, 2024 at 9:35 AM Peter Eisentraut wrote:
> >> But this separation was explicitly added a few years ago, because most
> >> people just want to read about the binaries.
> >
> > I really doubt that this is true.
>
> Here is the thread:
>
On Thu, Mar 21, 2024 at 7:40 PM Peter Eisentraut wrote:
> I'm highly against this. If I want to read about PL/Python, why should
> I have to wade through PL/Perl and PL/Tcl?
>
> I think, abstractly, in a book, PL/Python should be a chapter of its
> own. Just like GiST should be a chapter of its
On 22.03.24 13:50, Robert Haas wrote:
On Thu, Mar 21, 2024 at 7:37 PM Peter Eisentraut wrote:
On 20.03.24 17:43, Robert Haas wrote:
0001 removes the "Installation from Binaries" chapter. The whole thing
is four sentences. I moved the most important information into the
"Installation from
On Thu, Mar 21, 2024 at 7:37 PM Peter Eisentraut wrote:
> On 20.03.24 17:43, Robert Haas wrote:
> > 0001 removes the "Installation from Binaries" chapter. The whole thing
> > is four sentences. I moved the most important information into the
> > "Installation from Source Code" chapter and
On Thu, Mar 21, 2024 at 6:32 PM David G. Johnston
wrote:
> Just going to note that the section on the cumulative statistics views being
> a single page is still a strongly bothersome issue here. Though the quick
> fix actually requires upgrading the section to chapter status...
Yeah, I've
On Fri, Mar 22, 2024 at 01:12:30AM +0100, Daniel Gustafsson wrote:
> > On 22 Mar 2024, at 00:33, Peter Eisentraut wrote:
> >
> > On 19.03.24 14:50, Tom Lane wrote:
> >> Daniel Gustafsson writes:
> >>> It's actually not very odd, the reference section is using
> >>> elements
> >>> and we had
> On 22 Mar 2024, at 00:33, Peter Eisentraut wrote:
>
> On 19.03.24 14:50, Tom Lane wrote:
>> Daniel Gustafsson writes:
>>> It's actually not very odd, the reference section is using
>>> elements
>>> and we had missed the arabic numerals setting on those. The attached fixes
>>> that for me.
On 21.03.24 15:31, Robert Haas wrote:
On Thu, Mar 21, 2024 at 9:38 AM Tom Lane wrote:
I'd follow the extend.sgml precedent: have a file corresponding to the
chapter and containing any top-level text we need, then that includes
a file per sect1.
OK, here's a new patch set. I've revised 0003
On 20.03.24 17:43, Robert Haas wrote:
0001 removes the "Installation from Binaries" chapter. The whole thing
is four sentences. I moved the most important information into the
"Installation from Source Code" chapter and retitled it
"Installation".
But this separation was explicitly added a few
On 19.03.24 14:50, Tom Lane wrote:
Daniel Gustafsson writes:
It's actually not very odd, the reference section is using elements
and we had missed the arabic numerals setting on those. The attached fixes
that for me. That being said, we've had roman numerals for the reference
section since
On Thu, Mar 21, 2024 at 11:30 AM Robert Haas wrote:
>
> My second thought is that the stuff from "VII. Internals" that I
> categorized as reference material should move into section "VI.
> Reference". I think we should also consider moving appendix F,
> "Additional Supplied Modules and
On Wed, Mar 20, 2024 at 9:43 AM Robert Haas wrote:
> On Tue, Mar 19, 2024 at 5:39 PM Andrew Dunstan
> wrote:
> > +many for improving the index.
>
> Here's a series of four patches.
I reviewed the most recent set of 5 patches.
> Taken together, they cut down the
> number of numbered chapters
On Thu, Mar 21, 2024 at 12:43 PM Alvaro Herrera wrote:
> which is a bit odd: why are the two WAL chapters in the middle of the
> chapters 62 and 63 talking about AMs? Maybe put 66 right after 63
> instead.Also, is it really better to have 62/63 first and 66
> later? It sounds to me like 66
On 2024-Mar-21, Robert Haas wrote:
> On Thu, Mar 21, 2024 at 9:38 AM Tom Lane wrote:
> > I'd follow the extend.sgml precedent: have a file corresponding to the
> > chapter and containing any top-level text we need, then that includes
> > a file per sect1.
>
> OK, here's a new patch set. I've
On Thu, Mar 21, 2024 at 10:31 AM Robert Haas wrote:
> 0001 and 0002 are changed. Should 0002 use the include-an-entity
> approach as well?
Woops. I meant to say that 0001 and 0002 are *unchanged*.
--
Robert Haas
EDB: http://www.enterprisedb.com
On Thu, Mar 21, 2024 at 9:38 AM Tom Lane wrote:
> I'd follow the extend.sgml precedent: have a file corresponding to the
> chapter and containing any top-level text we need, then that includes
> a file per sect1.
OK, here's a new patch set. I've revised 0003 and 0004 to use this
approach, and
Robert Haas writes:
> Well, I suppose I thought it was a good idea because (1) we don't seem
> to have any existing precedent for file-per-sect1 rather than
> file-per-chapter and (2) all of the per-AM files combined are less
> than 20% of the size of func.sgml.
We have done (1) in places, eg.
On Wed, Mar 20, 2024 at 5:25 PM Tom Lane wrote:
> I'd say that a separate file per AM is a good thing regardless.
> Elsewhere in this same thread are grumblings about how big func.sgml
> is; why would you think it good to start down that same path for the
> AM documentation?
Well, I suppose I
Robert Haas writes:
> On Wed, Mar 20, 2024 at 5:05 PM Alvaro Herrera
> wrote:
>> I think you can achieve this with a much smaller patch that just changes
>> the outer tag in each file so that each file is a , then create a
>> single file that includes all of these plus an additional outer tag
On Wed, Mar 20, 2024 at 5:05 PM Alvaro Herrera wrote:
> I think you can achieve this with a much smaller patch that just changes
> the outer tag in each file so that each file is a , then create a
> single file that includes all of these plus an additional outer tag for
> the (or maybe just add
On 2024-Mar-20, Robert Haas wrote:
> 0003 merges all of the "Internals" chapters whose names are the names
> of built-in index access methods (Btree, Gin, etc.) into a single
> chapter called "Built-In Index Access Methods". All of these chapters
> have a very similar structure and none of them
On Wed, Mar 20, 2024 at 1:35 PM Bruce Momjian wrote:
> On Wed, Mar 20, 2024 at 12:43:08PM -0400, Robert Haas wrote:
> > Overall, I think this achieves a minor but pleasant level of
> > de-cluttering of the index. It's going to take a lot more than one
> > morning's work to produce a major
On Wed, Mar 20, 2024 at 12:43:08PM -0400, Robert Haas wrote:
> Overall, I think this achieves a minor but pleasant level of
> de-cluttering of the index. It's going to take a lot more than one
> morning's work to produce a major improvement, but at least this is
> something.
I think this kind of
On Mon, Mar 18, 2024 at 5:40 PM Laurenz Albe wrote:
> I also disagree that chapters 4 to 6 are a continuation of the tutorial.
> Or at least, they shouldn't be.
> When I am looking for a documentation reference on something like
> security considerations of SECURITY DEFINER functions, my first
>
On Mon, Mar 18, 2024 at 10:12 AM Robert Haas wrote:
> I was looking at the documentation index this morning[1], and I can't
> help feeling like there are some parts of it that are over-emphasized
> and some parts that are under-emphasized. I'm not sure what we can do
> about this exactly, but I
Daniel Gustafsson writes:
> It's actually not very odd, the reference section is using
> elements
> and we had missed the arabic numerals setting on those. The attached fixes
> that for me. That being said, we've had roman numerals for the reference
> section since forever (all the way down
> On 18 Mar 2024, at 22:40, Laurenz Albe wrote:
> On Mon, 2024-03-18 at 10:11 -0400, Robert Haas wrote:
>> For reasons that I don't understand, all chapters except
>> for those in "VI. Reference" are numbered, but the chapters in that
>> section have Roman numerals instead.
>
> That last fact
On Mon, Mar 18, 2024 at 6:51 PM Tom Lane wrote:
> This might be a silly suggestion, but: could we just render the
> "most important" chapter titles in a larger font?
It's not the silliest suggestion ever -- you could have proposed
! -- but I also suspect it's not the right answer. Of course,
Laurenz Albe writes:
> On Mon, 2024-03-18 at 10:11 -0400, Robert Haas wrote:
>> I don't know what to do about "I. SQL commands". It's obviously
>> impractical to promote that to a top-level section, because it's got a
>> zillion sub-pages which I don't think we want in the top-level
>>
On Mon, 2024-03-18 at 10:11 -0400, Robert Haas wrote:
> The two sections of the documentation that seem really
> under-emphasized to me are the GUC documentation and the SQL
> reference. The GUC documentation is all buried under "20. Server
> Configuration" and the SQL command reference is under
On Mon, Mar 18, 2024 at 10:12 AM Robert Haas wrote:
> I was looking at the documentation index this morning[1], and I can't
> help feeling like there are some parts of it that are over-emphasized
> and some parts that are under-emphasized. I'm not sure what we can do
> about this exactly, but I
On Mon, Mar 18, 2024 at 10:55 AM Matthias van de Meent
wrote:
> > I don't know what to do about "I. SQL commands". It's obviously
> > impractical to promote that to a top-level section, because it's got a
> > zillion sub-pages which I don't think we want in the top-level
> > documentation index.
On Mon, 18 Mar 2024 at 15:12, Robert Haas wrote:
I'm not going into detail about the other docs comments, I don't have
much of an opinion either way on the mentioned sections. You make good
arguments; yet I don't usually use those sections of the docs but
rather do code searches.
> I don't know
I was looking at the documentation index this morning[1], and I can't
help feeling like there are some parts of it that are over-emphasized
and some parts that are under-emphasized. I'm not sure what we can do
about this exactly, but I thought it worth writing an email and seeing
what other people
72 matches
Mail list logo
