Thread: pgsql: Document txid functions.

Log Message:
-----------
Document txid functions.

Marko Kreen

Modified Files:
--------------
    pgsql/doc/src/sgml:
        datatype.sgml (r1.212 -> r1.213)
        (http://developer.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/datatype.sgml?r1=1.212&r2=1.213)
        func.sgml (r1.406 -> r1.407)
        (http://developer.postgresql.org/cvsweb.cgi/pgsql/doc/src/sgml/func.sgml?r1=1.406&r2=1.407)

momjian@postgresql.org (Bruce Momjian) writes:
> Log Message:
> -----------
> Document txid functions.

Please revert this change.  It makes these functions far more prominent
than is justified.

            regards, tom lane

Tom Lane wrote:
> momjian@postgresql.org (Bruce Momjian) writes:
> > Log Message:
> > -----------
> > Document txid functions.
>
> Please revert this change.  It makes these functions far more prominent
> than is justified.

Have you looked at the output?  My commit message wasn't clear.  What
the patch basically does is add a table that explains the txid fields,
and has a column for the functions:

    http://momjian.us/main/writings/pgsql/sgml/datatype-txid-snapshot.html


--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

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

Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> momjian@postgresql.org (Bruce Momjian) writes:
> Log Message:
> -----------
> Document txid functions.
>>
>> Please revert this change.  It makes these functions far more prominent
>> than is justified.

> Have you looked at the output?

Yes, I did.  I don't like giving these function their own <sect1>
heading --- if they deserve it, then why not every other little group of
functions under System Information Functions and System Administration
Functions too?  I also find it entirely unreasonable to treat the
datatype as a major datatype category.

I thought the stuff was adequately documented already, which is why I
suggest just reverting this.

            regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Tom Lane wrote:
> >> momjian@postgresql.org (Bruce Momjian) writes:
> > Log Message:
> > -----------
> > Document txid functions.
> >>
> >> Please revert this change.  It makes these functions far more prominent
> >> than is justified.
>
> > Have you looked at the output?
>
> Yes, I did.  I don't like giving these function their own <sect1>
> heading --- if they deserve it, then why not every other little group of
> functions under System Information Functions and System Administration
> Functions too?  I also find it entirely unreasonable to treat the
> datatype as a major datatype category.
>
> I thought the stuff was adequately documented already, which is why I
> suggest just reverting this.

OK, so how about removing just the "Query Function" column.  I thought
the field descriptions where useful.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

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

Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> I thought the stuff was adequately documented already, which is why I
>> suggest just reverting this.

> OK, so how about removing just the "Query Function" column.  I thought
> the field descriptions where useful.

What I'm objecting to is the <sect1> status.

If you want to keep the verbal descriptions of the snapshot components
I'd suggest sticking them below the existing table that describes the
functions.  This is the way we have historically handled additional info
for functions that belong on the System Functions pages.

            regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Tom Lane wrote:
> >> I thought the stuff was adequately documented already, which is why I
> >> suggest just reverting this.
>
> > OK, so how about removing just the "Query Function" column.  I thought
> > the field descriptions where useful.
>
> What I'm objecting to is the <sect1> status.
>
> If you want to keep the verbal descriptions of the snapshot components
> I'd suggest sticking them below the existing table that describes the
> functions.  This is the way we have historically handled additional info
> for functions that belong on the System Functions pages.

OK, done.  They are at the bottom of this page:

    http://momjian.us/main/writings/pgsql/sgml/functions-info.html

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

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