Re: Documentation of pg_badkend_pid and stats functions

Two questions: Why is pg_backend_pid documented with the stats
functions (9.19 System Information Functions) seems more logical.

Also, I can see mentioning the stats functions in the monitoring
section, but shouldn't they actually be documented in with the rest
of the functions?
--
Jim Nasby jim(at)nasby(dot)net
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)

On Apr 12, 2007, at 7:54 AM, Jim Nasby wrote:
> Two questions: Why is pg_backend_pid documented with the stats
> functions (9.19 System Information Functions) seems more logical.
>
> Also, I can see mentioning the stats functions in the monitoring
> section, but shouldn't they actually be documented in with the rest
> of the functions?

No comments? Does that mean if I write up a patch it'll be accepted?
--
Jim Nasby jim(at)nasby(dot)net
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)

Jim Nasby wrote:
> On Apr 12, 2007, at 7:54 AM, Jim Nasby wrote:
> > Two questions: Why is pg_backend_pid documented with the stats
> > functions (9.19 System Information Functions) seems more logical.
> >
> > Also, I can see mentioning the stats functions in the monitoring
> > section, but shouldn't they actually be documented in with the rest
> > of the functions?
>
> No comments? Does that mean if I write up a patch it'll be accepted?

Yea, I was wondering about that. I think the best idea would be to
reference the backend functions from the main functions page, rather
than move them.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

On May 6, 2007, at 11:44 AM, Bruce Momjian wrote:
> Jim Nasby wrote:
>> On Apr 12, 2007, at 7:54 AM, Jim Nasby wrote:
>>> Two questions: Why is pg_backend_pid documented with the stats
>>> functions (9.19 System Information Functions) seems more logical.
>>>
>>> Also, I can see mentioning the stats functions in the monitoring
>>> section, but shouldn't they actually be documented in with the rest
>>> of the functions?
>>
>> No comments? Does that mean if I write up a patch it'll be accepted?
>
> Yea, I was wondering about that. I think the best idea would be to
> reference the backend functions from the main functions page, rather
> than move them.

Well, pg_backend_pid makes no sense being in with the stats
functions, so I'll move it. I'll just include references to the other
stuff.
--
Jim Nasby jim(at)nasby(dot)net
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)

On May 7, 2007, at 11:03 AM, Jim Nasby wrote:
> On May 6, 2007, at 11:44 AM, Bruce Momjian wrote:
>> Jim Nasby wrote:
>>> On Apr 12, 2007, at 7:54 AM, Jim Nasby wrote:
>>>> Two questions: Why is pg_backend_pid documented with the stats
>>>> functions (9.19 System Information Functions) seems more logical.
>>>>
>>>> Also, I can see mentioning the stats functions in the monitoring
>>>> section, but shouldn't they actually be documented in with the rest
>>>> of the functions?
>>>
>>> No comments? Does that mean if I write up a patch it'll be accepted?
>>
>> Yea, I was wondering about that. I think the best idea would be to
>> reference the backend functions from the main functions page, rather
>> than move them.
>
> Well, pg_backend_pid makes no sense being in with the stats
> functions, so I'll move it. I'll just include references to the
> other stuff.

Turns out it didn't really make much more sense to move
pg_backend_pid either, so I went with Bruce's original idea.

Jim Nasby <decibel(at)decibel(dot)org> writes:
> <title>System Information Functions</title>

> <para>
> + In addition to the functions listed in this section, there are a number of
> + functions related to the statistics system that also provide system
> + information. See <xref linkend="monitoring-stats-views"> for more
> + information.
> + </para>

Surely a section should not *begin* with a cross-reference to someplace
else.

regards, tom lane

On Sun, May 13, 2007 at 06:48:01PM -0400, Tom Lane wrote:
> Jim Nasby <decibel(at)decibel(dot)org> writes:
>> <title>System Information Functions</title>
>
>> <para>
>> + In addition to the functions listed in this section, there
>> are a number of
>> + functions related to the statistics system that also provide
>> system
>> + information. See <xref linkend="monitoring-stats-views"> for
>> more
>> + information.
>> + </para>
>
> Surely a section should not *begin* with a cross-reference to
> someplace
> else.

My concern is that folks will see the table right below it, not find
what they're looking for there, and move on... what about immediately
after the table?
--
Jim Nasby decibel(at)decibel(dot)org
EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)

"Jim C. Nasby" <decibel(at)decibel(dot)org> writes:
> On Sun, May 13, 2007 at 06:48:01PM -0400, Tom Lane wrote:
>> Surely a section should not *begin* with a cross-reference to
>> someplace else.

> My concern is that folks will see the table right below it, not find
> what they're looking for there, and move on... what about immediately
> after the table?

Immediately after is fine with me. For that matter, you could probably
get away with putting it between the introductory para and the table
proper. I'm just allergic to sections that don't begin with a topic
sentence telling you what they are about.

regards, tom lane

On May 13, 2007, at 6:45 PM, Tom Lane wrote:
> "Jim C. Nasby" <decibel(at)decibel(dot)org> writes:
>> On Sun, May 13, 2007 at 06:48:01PM -0400, Tom Lane wrote:
>>> Surely a section should not *begin* with a cross-reference to
>>> someplace else.
>
>> My concern is that folks will see the table right below it, not find
>> what they're looking for there, and move on... what about immediately
>> after the table?
>
> Immediately after is fine with me. For that matter, you could
> probably
> get away with putting it between the introductory para and the table
> proper. I'm just allergic to sections that don't begin with a topic
> sentence telling you what they are about.

See attached. I wanted to not put it between the paragraph
referencing the table and the table itself, but couldn't think of a
better intro paragraph for the section...

Patch applied. Thanks.

---------------------------------------------------------------------------

Jim Nasby wrote:
> On May 13, 2007, at 6:45 PM, Tom Lane wrote:
> > "Jim C. Nasby" <decibel(at)decibel(dot)org> writes:
> >> On Sun, May 13, 2007 at 06:48:01PM -0400, Tom Lane wrote:
> >>> Surely a section should not *begin* with a cross-reference to
> >>> someplace else.
> >
> >> My concern is that folks will see the table right below it, not find
> >> what they're looking for there, and move on... what about immediately
> >> after the table?
> >
> > Immediately after is fine with me. For that matter, you could
> > probably
> > get away with putting it between the introductory para and the table
> > proper. I'm just allergic to sections that don't begin with a topic
> > sentence telling you what they are about.
>
> See attached. I wanted to not put it between the paragraph
> referencing the table and the table itself, but couldn't think of a
> better intro paragraph for the section...
[ Attachment, skipping... ]

>
> --
> Jim Nasby jim(at)nasby(dot)net
> EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 9: In versions below 8.0, the planner will ignore your desire to
> choose an index scan if your joining column's datatypes do not
> match

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +