pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTwo points about docs
11+ messages / 5 participants
[nested] [flat]
* Two points about docs
@ 2005-04-01 06:17 Vladimir Chukharev <chu@kemia.me.tut.fi>
0 siblings, 1 reply; 11+ messages in thread
From: Vladimir Chukharev @ 2005-04-01 06:17 UTC (permalink / raw)
To: pgsql-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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-08 03:18 Bruce Momjian <pgman@candle.pha.pa.us>
parent: Vladimir Chukharev <chu@kemia.me.tut.fi>
0 siblings, 0 replies; 11+ messages in thread
From: Bruce Momjian @ 2005-05-08 03:18 UTC (permalink / raw)
To: Vladimir Chukharev <chu@kemia.me.tut.fi>; +Cc: pgsql-docs
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
Attachments:
/bjm/diff (text/plain, 1.4K) download
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
@ 2005-05-10 01:50 Bruce Momjian <pgman@candle.pha.pa.us>
0 siblings, 1 reply; 11+ messages in thread
From: Bruce Momjian @ 2005-05-10 01:50 UTC (permalink / raw)
To: Vladimir Chukharev <chu@h33.erkki.ton.tut.fi>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 06:50 Vladimir Chukharev <chu@kemia.me.tut.fi>
parent: Bruce Momjian <pgman@candle.pha.pa.us>
0 siblings, 2 replies; 11+ messages in thread
From: Vladimir Chukharev @ 2005-05-11 06:50 UTC (permalink / raw)
To: Bruce Momjian <pgman@candle.pha.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 07:00 Michael Glaesemann <grzm@myrealbox.com>
parent: Vladimir Chukharev <chu@kemia.me.tut.fi>
1 sibling, 2 replies; 11+ messages in thread
From: Michael Glaesemann @ 2005-05-11 07:00 UTC (permalink / raw)
To: Vladimir Chukharev <chu@kemia.me.tut.fi>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 13:36 Bruce Momjian <pgman@candle.pha.pa.us>
parent: Vladimir Chukharev <chu@kemia.me.tut.fi>
1 sibling, 1 reply; 11+ messages in thread
From: Bruce Momjian @ 2005-05-11 13:36 UTC (permalink / raw)
To: Vladimir Chukharev <chu@kemia.me.tut.fi>; +Cc: pgsql-docs
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
Attachments:
/bjm/diff (text/plain, 1.0K) download
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
@ 2005-05-11 13:39 Tom Lane <tgl@sss.pgh.pa.us>
parent: Michael Glaesemann <grzm@myrealbox.com>
1 sibling, 1 reply; 11+ messages in thread
From: Tom Lane @ 2005-05-11 13:39 UTC (permalink / raw)
To: Michael Glaesemann <grzm@myrealbox.com>; +Cc: Vladimir Chukharev <chu@kemia.me.tut.fi>; pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 13:59 Tom Lane <tgl@sss.pgh.pa.us>
parent: Bruce Momjian <pgman@candle.pha.pa.us>
0 siblings, 1 reply; 11+ messages in thread
From: Tom Lane @ 2005-05-11 13:59 UTC (permalink / raw)
To: Bruce Momjian <pgman@candle.pha.pa.us>; +Cc: Vladimir Chukharev <chu@kemia.me.tut.fi>; pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 14:01 Michael Glaesemann <grzm@myrealbox.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 11+ messages in thread
From: Michael Glaesemann @ 2005-05-11 14:01 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-11 14:05 Bruce Momjian <pgman@candle.pha.pa.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 11+ messages in thread
From: Bruce Momjian @ 2005-05-11 14:05 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Vladimir Chukharev <chu@kemia.me.tut.fi>; pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Two points about docs
@ 2005-05-15 14:34 Vladimir Chukharev <chu@h33.erkki.ton.tut.fi>
parent: Michael Glaesemann <grzm@myrealbox.com>
1 sibling, 0 replies; 11+ messages in thread
From: Vladimir Chukharev @ 2005-05-15 14:34 UTC (permalink / raw)
To: Michael Glaesemann <grzm@myrealbox.com>; +Cc: pgsql-docs
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
^ permalink raw reply [nested|flat] 11+ messages in thread
end of thread, other threads:[~2005-05-15 14:34 UTC | newest]
Thread overview: 11+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2005-04-01 06:17 Two points about docs Vladimir Chukharev <chu@kemia.me.tut.fi>
2005-05-08 03:18 ` Bruce Momjian <pgman@candle.pha.pa.us>
2005-05-10 01:50 Re: Two points about docs Bruce Momjian <pgman@candle.pha.pa.us>
2005-05-11 06:50 ` Vladimir Chukharev <chu@kemia.me.tut.fi>
2005-05-11 07:00 ` Michael Glaesemann <grzm@myrealbox.com>
2005-05-11 13:39 ` Tom Lane <tgl@sss.pgh.pa.us>
2005-05-11 14:01 ` Michael Glaesemann <grzm@myrealbox.com>
2005-05-15 14:34 ` Vladimir Chukharev <chu@h33.erkki.ton.tut.fi>
2005-05-11 13:36 ` Bruce Momjian <pgman@candle.pha.pa.us>
2005-05-11 13:59 ` Tom Lane <tgl@sss.pgh.pa.us>
2005-05-11 14:05 ` Bruce Momjian <pgman@candle.pha.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox