Subject: Suggestion on reorganizing functions

From: Jeff <[email-masked]>
Date: Mon, 9 Aug 2004 13:20:33 -0400

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-masked]>
http://www.jefftrout.com/
http://www.stuarthamm.net/

---

From: Tom Lane <[email-masked]>
Date: Mon, 09 Aug 2004 16:39:43 -0400

> 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

---

From: Rod Taylor <[email-masked]>
Date: Mon, 09 Aug 2004 16:52:45 -0400

> 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.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 9 Aug 2004 23:15:53 +0200

> 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.

> documents without a rather expensive toolkit.

Well, the SGML toolchains don't produce anything useful either...

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 9 Aug 2004 23:20:33 +0200

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.

---

From: David Fetter <[email-masked]>
Date: Mon, 9 Aug 2004 14:27:37 -0700

On Mon, Aug 09, 2004 at 11:20:33PM +0200, Peter Eisentraut wrote:
> 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

Where?

Cheers,
D
-- 
David Fetter [email-masked] http://fetter.org/
phone: +1 510 893 6100   mobile: +1 415 235 3778

Remember to vote!

---

From: Tom Lane <[email-masked]>
Date: Mon, 09 Aug 2004 17:34:56 -0400

> 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

---

From: David Fetter <[email-masked]>
Date: Mon, 9 Aug 2004 14:40:10 -0700

> 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 :)

>    <primary>sequence</primary>
[snip]
> somehow, eg by adding "()" to the names or setting them in a fixed-width

Sure :)

Cheers,
D

Remember to vote!

---

From: Tom Lane <[email-masked]>
Date: Mon, 09 Aug 2004 20:20:59 -0400

> 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

---

From: Jeff <[email-masked]>
Date: Tue, 10 Aug 2004 10:03:29 -0400

> 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.