[DOCS] 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 <[EMAIL PROTECTED]> http://www.jefftrout.com/ http://www.stuarthamm.net/ ---(end of broadcast)--- TIP 6: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] PostgreSQL.conf / runtime docs
Josh Berkus wrote: > As we've always accepted doc patches up until a few days before > release, this shouldn't be a problem, yes? (Besides, I still need to > fix the SGML libraries on my laptop ... ) If you plan to do major outline reorganizations, I suggest that you do them somewhat sooner than a few days before release, because there is also a release management effort involved in the documentation. But you can always plug in your latest measurements any time. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
Re: [DOCS] Suggestion on reorganizing functions
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 ---(end of broadcast)--- TIP 8: explain analyze is your friend
Re: [DOCS] PostgreSQL.conf / runtime docs
Peter, > If you plan to do major outline reorganizations, I suggest that you do > them somewhat sooner than a few days before release, because there is > also a release management effort involved in the documentation. But > you can always plug in your latest measurements any time. No massive re-org, we did that last version. No, here's what I want to do: 1) add a new section at the top of the docs describing the most common options that people want to set on a new installation. 2) Add notes to each item about how to decide what to set it at. 3) Add label/values for: Default Value: Set At: (when you can change it) (this latter information is there but buried in the text; it would be better put on a seperate line) 4) add notes regarding version changes (like that work_mem used to be sort_mem, and that add_missing_from will default to "false" next version) Your recommendations on tagging stuff are highly welcome; I'm still uncomfortable with SGML. -- Josh Berkus Aglio Database Solutions San Francisco ---(end of broadcast)--- TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
Re: [DOCS] Suggestion on reorganizing functions
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. ---(end of broadcast)--- TIP 4: Don't 'kill -9' the postmaster
Re: [DOCS] Suggestion on reorganizing functions
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/
---(end of broadcast)---
TIP 6: Have you searched our list archives?
http://archives.postgresql.org
Re: [DOCS] Suggestion on reorganizing functions
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/ ---(end of broadcast)--- TIP 6: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Suggestion on reorganizing functions
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!
---(end of broadcast)---
TIP 9: the planner will ignore your desire to choose an index scan if your
joining column's datatypes do not match
Re: [DOCS] Suggestion on reorganizing functions
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:
Sequence Manipulation Functions
sequence
nextval
currval
setval
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
---(end of broadcast)---
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to [EMAIL PROTECTED] so that your
message can get through to the mailing list cleanly
Re: [DOCS] Suggestion on reorganizing functions
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 :)
>
> Sequence Manipulation Functions
>
>
>sequence
>
[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!
---(end of broadcast)---
TIP 9: the planner will ignore your desire to choose an index scan if your
joining column's datatypes do not match
Re: [DOCS] Suggestion on reorganizing functions
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 ---(end of broadcast)--- TIP 2: you can get off all lists at once with the unregister command (send "unregister YourEmailAddressHere" to [EMAIL PROTECTED])
