Thread: Two points about docs

Two points about docs

From
"Vladimir Chukharev"
Date:
Hi,

I think that docs can be improved a bit in two places.

1. Description of SELECT ( http://www.postgresql.org/docs/8.0/static/sql-select.html )
says 'SELECT retrieves rows from one or more tables.' This is not perfectly
correct, because 0 tables can be used like in 'SELECT 1;'. When I tried to find
how I can check the meaning of some simple function, at first attempt I really
thought that SELECT cannot be used without tables.

Chapter 7.1 also says that the simpleast query is 'SELECT * FROM table1;',
but at least the example 'SELECT 3 * 4;' is close enough to catch an eye.

2. 'Chapter 9. Functions and Operators' has no reference to server side
functions for large object manipulation (lo_creat et al.) Yesterday wanted
to check the names of those functions (I remembered there are some in psql).
So, first I found that blob is a keyword, but is not implemented. Then I tried
to find them in Chapter 9. I just couldn't beleave it's not there. Then I tried
to find a list of all functions, similar to list of all keywords. And only
after all that I found the location of the lo_* functions.

Well, may it is just me, of course. I don't know...

--
V.Chukharev

Re: Two points about docs

From
Bruce Momjian
Date:
I have added your first two suggestions.   Not sure where to put the
large object links in the function section.  It seems out of place there
to me.

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

Vladimir Chukharev wrote:
> Hi,
>
> I think that docs can be improved a bit in two places.
>
> 1. Description of SELECT ( http://www.postgresql.org/docs/8.0/static/sql-select.html )
> says 'SELECT retrieves rows from one or more tables.' This is not perfectly
> correct, because 0 tables can be used like in 'SELECT 1;'. When I tried to find
> how I can check the meaning of some simple function, at first attempt I really
> thought that SELECT cannot be used without tables.
>
> Chapter 7.1 also says that the simpleast query is 'SELECT * FROM table1;',
> but at least the example 'SELECT 3 * 4;' is close enough to catch an eye.
>
> 2. 'Chapter 9. Functions and Operators' has no reference to server side
> functions for large object manipulation (lo_creat et al.) Yesterday wanted
> to check the names of those functions (I remembered there are some in psql).
> So, first I found that blob is a keyword, but is not implemented. Then I tried
> to find them in Chapter 9. I just couldn't beleave it's not there. Then I tried
> to find a list of all functions, similar to list of all keywords. And only
> after all that I found the location of the lo_* functions.
>
> Well, may it is just me, of course. I don't know...
>
> --
> V.Chukharev
>
> ---------------------------(end of broadcast)---------------------------
> TIP 8: explain analyze is your friend
>

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/sgml/queries.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/queries.sgml,v
retrieving revision 1.33
diff -c -c -r1.33 queries.sgml
*** doc/src/sgml/queries.sgml    22 Jan 2005 22:56:36 -0000    1.33
--- doc/src/sgml/queries.sgml    8 May 2005 03:07:04 -0000
***************
*** 34,40 ****
    </para>

    <para>
!    The simplest kind of query has the form
  <programlisting>
  SELECT * FROM table1;
  </programlisting>
--- 34,40 ----
    </para>

    <para>
!    A simple kind of query has the form
  <programlisting>
  SELECT * FROM table1;
  </programlisting>
Index: doc/src/sgml/ref/select.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v
retrieving revision 1.86
diff -c -c -r1.86 select.sgml
*** doc/src/sgml/ref/select.sgml    28 Apr 2005 21:47:10 -0000    1.86
--- doc/src/sgml/ref/select.sgml    8 May 2005 03:07:06 -0000
***************
*** 47,53 ****
    <title>Description</title>

    <para>
!    <command>SELECT</command> retrieves rows from one or more tables.
     The general processing of <command>SELECT</command> is as follows:

     <orderedlist>
--- 47,53 ----
    <title>Description</title>

    <para>
!    <command>SELECT</command> retrieves rows from zero or more tables.
     The general processing of <command>SELECT</command> is as follows:

     <orderedlist>

Re: Two points about docs

From
Bruce Momjian
Date:
Vladimir Chukharev wrote:
> On Sun, 08 May 2005 06:18:04 +0300, Bruce Momjian <pgman@candle.pha.pa.us> wrote:
>
> > I have added your first two suggestions.   Not sure where to put the
> > large object links in the function section.  It seems out of place there
> > to me.
>
> Thanks!
>
> About the link to the lo_* functions. I thought about adding
> a sentence to Charpter 9 like 'And functions to manipulate large
> objects are presented in Charpter 28.' right after the phrase
> 'Users can also define their own functions and operators, as
> described in Part V.'
>
> Do you think it's suitable?

Not really.  We don't mention pg_stat_activity functions either.  I
think people have to realize that some functions are covered in other
sections of the manual.  There is a clearly titled section for large
objeccts.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Re: Two points about docs

From
"Vladimir Chukharev"
Date:
On Tue, 10 May 2005 04:50:16 +0300, Bruce Momjian <pgman@candle.pha.pa.us> wrote:

> Vladimir Chukharev wrote:
>> About the link to the lo_* functions. I thought about adding
>> a sentence to Charpter 9 like 'And functions to manipulate large
>> objects are presented in Charpter 28.' right after the phrase
>> 'Users can also define their own functions and operators, as
>> described in Part V.'
>>
>> Do you think it's suitable?
>
> Not really.  We don't mention pg_stat_activity functions either.  I
> think people have to realize that some functions are covered in other
> sections of the manual.  There is a clearly titled section for large
> objeccts.

OK, what about writing down this idea? "Not all functions are listed
in this Chapter, some are in other sections of the manual."

And I still think that an additional Appendix with a list of all
functions and referencies to their descriptions would be very usefull.
Can you comment on that?

Best regards,
--
V.Chukharev

Re: Two points about docs

From
Michael Glaesemann
Date:
On May 11, 2005, at 15:50, Vladimir Chukharev wrote:
> And I still think that an additional Appendix with a list of all
> functions and referencies to their descriptions would be very usefull.
> Can you comment on that?

This has been brought up in the past. I don't think there's any reason
there can't be one. Want to make a function appendix? :)

Michael Glaesemann
grzm myrealbox com


Re: Two points about docs

From
Bruce Momjian
Date:
Vladimir Chukharev wrote:
> On Tue, 10 May 2005 04:50:16 +0300, Bruce Momjian <pgman@candle.pha.pa.us> wrote:
>
> > Vladimir Chukharev wrote:
> >> About the link to the lo_* functions. I thought about adding
> >> a sentence to Charpter 9 like 'And functions to manipulate large
> >> objects are presented in Charpter 28.' right after the phrase
> >> 'Users can also define their own functions and operators, as
> >> described in Part V.'
> >>
> >> Do you think it's suitable?
> >
> > Not really.  We don't mention pg_stat_activity functions either.  I
> > think people have to realize that some functions are covered in other
> > sections of the manual.  There is a clearly titled section for large
> > objeccts.
>
> OK, what about writing down this idea? "Not all functions are listed
> in this Chapter, some are in other sections of the manual."

OK, done.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.245
diff -c -c -r1.245 func.sgml
*** doc/src/sgml/func.sgml    13 Apr 2005 00:20:10 -0000    1.245
--- doc/src/sgml/func.sgml    11 May 2005 13:32:41 -0000
***************
*** 32,38 ****
     <acronym>SQL</acronym> standard. Some of the extended functionality
     is present in other <acronym>SQL</acronym> database management
     systems, and in many cases this functionality is compatible and
!    consistent between the various implementations.
    </para>


--- 32,40 ----
     <acronym>SQL</acronym> standard. Some of the extended functionality
     is present in other <acronym>SQL</acronym> database management
     systems, and in many cases this functionality is compatible and
!    consistent between the various implementations.  This chapter is also
!    not exhaustive;  additional functions appear in relivant sections of
!    the manual.
    </para>



Re: Two points about docs

From
Tom Lane
Date:
Michael Glaesemann <grzm@myrealbox.com> writes:
> On May 11, 2005, at 15:50, Vladimir Chukharev wrote:
>> And I still think that an additional Appendix with a list of all
>> functions and referencies to their descriptions would be very usefull.
>> Can you comment on that?

> This has been brought up in the past. I don't think there's any reason
> there can't be one. Want to make a function appendix? :)

I think this is more conventionally called an index ;-)

            regards, tom lane

Re: Two points about docs

From
Michael Glaesemann
Date:
On May 11, 2005, at 22:39, Tom Lane wrote:

> Michael Glaesemann <grzm@myrealbox.com> writes:
>
>> This has been brought up in the past. I don't think there's any reason
>> there can't be one. Want to make a function appendix? :)
>
> I think this is more conventionally called an index ;-)

Hehe :) Thanks, Tom! I don't know how the "i" and "e" got swapped
around, and that initial "app" is a complete mystery to me. Have to
check my mail software, I think. ;)

Michael Glaesemann
grzm myrealbox com


Re: Two points about docs

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> !    consistent between the various implementations.  This chapter is also
> !    not exhaustive;  additional functions appear in relivant sections of
> !    the manual.

"relevant", please.

            regards, tom lane

Re: Two points about docs

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > !    consistent between the various implementations.  This chapter is also
> > !    not exhaustive;  additional functions appear in relivant sections of
> > !    the manual.
>
> "relevant", please.

Yea, Neil got it.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Re: Two points about docs

From
"Vladimir Chukharev"
Date:
On Wed, 11 May 2005 10:00:02 +0300, Michael Glaesemann <grzm@myrealbox.com> wrote:

>
> On May 11, 2005, at 15:50, Vladimir Chukharev wrote:
>> And I still think that an additional Appendix with a list of all
>> functions and referencies to their descriptions would be very usefull.
>> Can you comment on that?
>
> This has been brought up in the past. I don't think there's any reason
> there can't be one. Want to make a function appendix? :)

OK, now I am trying to make the index. It will take time though, since
I can turn to it only when I'm _really sick_ with my PhD thesis :)

I made the list with psql \df command, and already found that
there is neither lo_write nor lo_read, but lowrite and loread instead...
Any idea what's wrong?

In addition I can find nothing about RI_FKey_* function.
Can you direct me please?

> Michael Glaesemann
> grzm myrealbox com

--
V.Chukharev