Thread: Two points about docs
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
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>
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
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
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
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>
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
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
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
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
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