public inbox for [email protected]
help / color / mirror / Atom feedSuggestion on reorganizing functions
10+ messages / 5 participants
[nested] [flat]
* Suggestion on reorganizing functions
@ 2004-08-09 17:20 Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
0 siblings, 1 reply; 10+ messages in thread
From: Jeff @ 2004-08-09 17:20 UTC (permalink / raw)
To: pgsql-docs
After some discussion on IRC about improvments that could be made to
the documentation I have a suggestion. Note: I don't have much time to
work on it and I'm not an sgml-wiz.
(Note: Using .html names of things as I don't know what sgml makes what)
The basic idea is to make the equivalent of sql-commands.html (A flat
list of all SQL commands) but for functions. Usually when I need to
go find functions it involves google. The flat list would allow a Joe
User to come along and scroll down to find out what FOOBAR() is instead
of going to functions.html and trying to decide what type of function
FOOBAR is.
The organization by category is useful (ie getting all date manip
functions) but the flat list would also be quite useful - especially if
you are a newcomer to PG and are trying to dissect some code.
One idea to solve it would to have the flat list link to
functions-foo.html#FOOBAR - this would allow both methods of
organization and only having function definitions in one spot.
Perhaps there is some other spiffy sgml way of defining the type of
function FOOBAR() is inside the sgml? We could have it scan all the
little sgml files for functions (ala ref/ files) and automatically
make function-TYPE.html files?
any thoughts?
--
Jeff Trout <[email protected]>
http://www.jefftrout.com/
http://www.stuarthamm.net/
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
@ 2004-08-09 20:39 ` Tom Lane <[email protected]>
2004-08-09 20:52 ` Re: Suggestion on reorganizing functions Rod Taylor <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
0 siblings, 2 replies; 10+ messages in thread
From: Tom Lane @ 2004-08-09 20:39 UTC (permalink / raw)
To: Jeff <[email protected]>; +Cc: pgsql-docs
Jeff <[email protected]> writes:
> One idea to solve it would to have the flat list link to
> functions-foo.html#FOOBAR - this would allow both methods of
> organization and only having function definitions in one spot.
Basically what you're proposing is an index.
I am not sure if DocBook could handle generating an index covering just
functions, or if we'd have to merge it with the general index. If the
latter then it's pretty much done already. (We may have missed indexing
some function descriptions, but certainly a lot of them have an index entry.)
regards, tom lane
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
@ 2004-08-09 20:52 ` Rod Taylor <[email protected]>
2004-08-09 21:15 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
1 sibling, 1 reply; 10+ messages in thread
From: Rod Taylor @ 2004-08-09 20:52 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Jeff <[email protected]>; pgsql-docs
On Mon, 2004-08-09 at 16:39, Tom Lane wrote:
> Jeff <[email protected]> writes:
> > One idea to solve it would to have the flat list link to
> > functions-foo.html#FOOBAR - this would allow both methods of
> > organization and only having function definitions in one spot.
>
> Basically what you're proposing is an index.
>
> I am not sure if DocBook could handle generating an index covering just
> functions, or if we'd have to merge it with the general index. If the
> latter then it's pretty much done already. (We may have missed indexing
> some function descriptions, but certainly a lot of them have an index entry.)
If we were using XML based docbook we could use an xmlinclude to
generate this type of content on the fly during output generation.
The big snag is that XML Docbook does not produce very nice printable
documents without a rather expensive toolkit.
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 20:52 ` Re: Suggestion on reorganizing functions Rod Taylor <[email protected]>
@ 2004-08-09 21:15 ` Peter Eisentraut <[email protected]>
0 siblings, 0 replies; 10+ messages in thread
From: Peter Eisentraut @ 2004-08-09 21:15 UTC (permalink / raw)
To: Rod Taylor <[email protected]>; Tom Lane <[email protected]>; +Cc: Jeff <[email protected]>; pgsql-docs
Rod Taylor wrote:
> If we were using XML based docbook we could use an xmlinclude to
> generate this type of content on the fly during output generation.
We can also include random SGML files "on the fly". This is how the
index is built in the first place. I doubt that will be the problem.
> The big snag is that XML Docbook does not produce very nice printable
> documents without a rather expensive toolkit.
Well, the SGML toolchains don't produce anything useful either...
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
@ 2004-08-09 21:20 ` Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
1 sibling, 1 reply; 10+ messages in thread
From: Peter Eisentraut @ 2004-08-09 21:20 UTC (permalink / raw)
To: Tom Lane <[email protected]>; Jeff <[email protected]>; +Cc: pgsql-docs
Tom Lane wrote:
> I am not sure if DocBook could handle generating an index covering
> just functions, or if we'd have to merge it with the general index.
I think it's possible -- with a bit of programming work. I doubt,
however, that it's going to be all that useful. We're already having
trouble categorizing things like IS NULL (function?, operator?, special
construct?). A function index would be quite unreliable ("It's not in
the function index, so it's not supported."). Feel free to add general
index entries for all functions, though.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
@ 2004-08-09 21:27 ` David Fetter <[email protected]>
2004-08-09 21:34 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
0 siblings, 1 reply; 10+ messages in thread
From: David Fetter @ 2004-08-09 21:27 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: Tom Lane <[email protected]>; Jeff <[email protected]>; pgsql-docs
On Mon, Aug 09, 2004 at 11:20:33PM +0200, Peter Eisentraut wrote:
> Tom Lane wrote:
> > I am not sure if DocBook could handle generating an index covering
> > just functions, or if we'd have to merge it with the general
> > index.
>
> I think it's possible -- with a bit of programming work. I doubt,
> however, that it's going to be all that useful. We're already
> having trouble categorizing things like IS NULL (function?,
> operator?, special construct?).
For docs, redundancy is fine, at least at the output level :)
> A function index would be quite unreliable ("It's not in the
> function index, so it's not supported."). Feel free to add general
> index entries for all functions, though.
Where?
Cheers,
D
--
David Fetter [email protected] http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
@ 2004-08-09 21:34 ` Tom Lane <[email protected]>
2004-08-09 21:40 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
0 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2004-08-09 21:34 UTC (permalink / raw)
To: David Fetter <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Jeff <[email protected]>; pgsql-docs
David Fetter <[email protected]> writes:
> On Mon, Aug 09, 2004 at 11:20:33PM +0200, Peter Eisentraut wrote:
>> A function index would be quite unreliable ("It's not in the
>> function index, so it's not supported."). Feel free to add general
>> index entries for all functions, though.
> Where?
In func.sgml. For example, this section seems adequately well indexed:
<sect1 id="functions-sequence">
<title>Sequence Manipulation Functions</title>
<indexterm>
<primary>sequence</primary>
</indexterm>
<indexterm>
<primary>nextval</primary>
</indexterm>
<indexterm>
<primary>currval</primary>
</indexterm>
<indexterm>
<primary>setval</primary>
</indexterm>
One thought though is that it's not clear when looking at the index that
these entries are function names. Would it be useful to decorate them
somehow, eg by adding "()" to the names or setting them in a fixed-width
font?
regards, tom lane
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
2004-08-09 21:34 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
@ 2004-08-09 21:40 ` David Fetter <[email protected]>
2004-08-10 00:20 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
0 siblings, 1 reply; 10+ messages in thread
From: David Fetter @ 2004-08-09 21:40 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Jeff <[email protected]>; pgsql-docs
On Mon, Aug 09, 2004 at 05:34:56PM -0400, Tom Lane wrote:
> David Fetter <[email protected]> writes:
> > On Mon, Aug 09, 2004 at 11:20:33PM +0200, Peter Eisentraut wrote:
> >> A function index would be quite unreliable ("It's not in the
> >> function index, so it's not supported."). Feel free to add general
> >> index entries for all functions, though.
>
> > Where?
>
> In func.sgml. For example, this section seems adequately well indexed:
I think Jeff's original point was that he wanted some kind of index
for all functions, not just ones you already know how to classify.
Thanks for the pointer :)
> <sect1 id="functions-sequence">
> <title>Sequence Manipulation Functions</title>
>
> <indexterm>
> <primary>sequence</primary>
> </indexterm>
[snip]
> One thought though is that it's not clear when looking at the index that
> these entries are function names. Would it be useful to decorate them
> somehow, eg by adding "()" to the names or setting them in a fixed-width
> font?
Sure :)
Cheers,
D
--
David Fetter [email protected] http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
2004-08-09 21:34 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:40 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
@ 2004-08-10 00:20 ` Tom Lane <[email protected]>
2004-08-10 14:03 ` Re: Suggestion on reorganizing functions Jeff <[email protected]>
0 siblings, 1 reply; 10+ messages in thread
From: Tom Lane @ 2004-08-10 00:20 UTC (permalink / raw)
To: David Fetter <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; Jeff <[email protected]>; pgsql-docs
David Fetter <[email protected]> writes:
> I think Jeff's original point was that he wanted some kind of index
> for all functions, not just ones you already know how to classify.
I thought his point was that he didn't fully know how the docs have
already classified functions, and therefore didn't know which page to
look on to find a given one. This seems a legitimate gripe to me, and
one that can be cured with a more complete index.
regards, tom lane
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: Suggestion on reorganizing functions
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:20 ` Re: Suggestion on reorganizing functions Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
2004-08-09 21:34 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
2004-08-09 21:40 ` Re: Suggestion on reorganizing functions David Fetter <[email protected]>
2004-08-10 00:20 ` Re: Suggestion on reorganizing functions Tom Lane <[email protected]>
@ 2004-08-10 14:03 ` Jeff <[email protected]>
0 siblings, 0 replies; 10+ messages in thread
From: Jeff @ 2004-08-10 14:03 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: David Fetter <[email protected]>; Peter Eisentraut <[email protected]>; pgsql-docs
On Aug 9, 2004, at 8:20 PM, Tom Lane wrote:
> David Fetter <[email protected]> writes:
>> I think Jeff's original point was that he wanted some kind of index
>> for all functions, not just ones you already know how to classify.
>
> I thought his point was that he didn't fully know how the docs have
> already classified functions, and therefore didn't know which page to
> look on to find a given one. This seems a legitimate gripe to me, and
> one that can be cured with a more complete index.
>
Exactly.
or if you are trying to remember a function - say "Oh whats that thing?
Colace? Coerce? [scrolls] Ahh! Coalesce!"
The trouble seems to be getting that list automatically generated from
the existing SGML.
--
Jeff Trout <[email protected]>
http://www.jefftrout.com/
http://www.stuarthamm.net/
^ permalink raw reply [nested|flat] 10+ messages in thread
end of thread, other threads:[~2004-08-10 14:03 UTC | newest]
Thread overview: 10+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2004-08-09 17:20 Suggestion on reorganizing functions Jeff <[email protected]>
2004-08-09 20:39 ` Tom Lane <[email protected]>
2004-08-09 20:52 ` Rod Taylor <[email protected]>
2004-08-09 21:15 ` Peter Eisentraut <[email protected]>
2004-08-09 21:20 ` Peter Eisentraut <[email protected]>
2004-08-09 21:27 ` David Fetter <[email protected]>
2004-08-09 21:34 ` Tom Lane <[email protected]>
2004-08-09 21:40 ` David Fetter <[email protected]>
2004-08-10 00:20 ` Tom Lane <[email protected]>
2004-08-10 14:03 ` Jeff <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox