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/