Thread: Suggestion on reorganizing functions
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 <jeff@jefftrout.com> http://www.jefftrout.com/ http://www.stuarthamm.net/
Jeff <threshar@torgo.978.org> 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
On Mon, 2004-08-09 at 16:39, Tom Lane wrote: > Jeff <threshar@torgo.978.org> 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.
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/
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/
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 david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
David Fetter <david@fetter.org> 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
On Mon, Aug 09, 2004 at 05:34:56PM -0400, Tom Lane wrote:
> David Fetter <david@fetter.org> 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 david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778
Remember to vote!
David Fetter <david@fetter.org> 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
On Aug 9, 2004, at 8:20 PM, Tom Lane wrote: > David Fetter <david@fetter.org> 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 <jeff@jefftrout.com> http://www.jefftrout.com/ http://www.stuarthamm.net/