Re: [DOCS] [HACKERS] Contrib modules documentation online
Albert, (crossed over to -docs, where it really belongs) > I've been working on converting the current README files for all contrib > modules into sgml and add it to the documentation. There are still some > fixes to do but i'd like to have some feedback. Indeed, it wasn't agreed to > have all if any of the modules together with the core documentation. > > You can see the docs on [1] in chapter VIII. If you think these could be a > good addition, please fill free to comment on how you think sections should > be organized to be consistent and easy to read. > > [1] http://www.nan-tic.com/ftp/pgdoc Wow, this is really, really cool! You're my hero. I'm very strongly in favor of having this documentation. However, I think it might make sense to put "Contrib Modules" as a section under either "Reference" or "Appendices". Also, I don't think it's necessary to make each command option a separate subchapter, but I can see how that would be hard to avoid in an automated system. Guys, would it be out of the question to do this in 8.3? Please please? If we go ahead with this, I'll commit to doing a contrib README cleanup so the doc system works better. -- Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
On Wed, Aug 29, 2007 at 10:09:07AM -0700, Josh Berkus wrote: > Albert, > > (crossed over to -docs, where it really belongs) > > > I've been working on converting the current README files for all contrib > > modules into sgml and add it to the documentation. There are still some > > fixes to do but i'd like to have some feedback. Indeed, it wasn't agreed to > > have all if any of the modules together with the core documentation. > > > > You can see the docs on [1] in chapter VIII. If you think these could be a > > good addition, please fill free to comment on how you think sections should > > be organized to be consistent and easy to read. > > > > [1] http://www.nan-tic.com/ftp/pgdoc > > Wow, this is really, really cool! You're my hero. > > I'm very strongly in favor of having this documentation. However, I think it > might make sense to put "Contrib Modules" as a section under either > "Reference" or "Appendices". Also, I don't think it's necessary to make each > command option a separate subchapter, but I can see how that would be hard to > avoid in an automated system. > > Guys, would it be out of the question to do this in 8.3? Please please? > > If we go ahead with this, I'll commit to doing a contrib README cleanup so > the > doc system works better. One question... would there still be a README in each contrib directory? I think getting this stuff in the docs is great, but the README in the source is also very valuable and I'd hate to lose it. -- Decibel!, aka Jim Nasby[EMAIL PROTECTED] EnterpriseDB http://enterprisedb.com 512.569.9461 (cell) pgpoU23RIWqFJ.pgp Description: PGP signature
Re: [DOCS] [HACKERS] Contrib modules documentation online
Josh Berkus <[EMAIL PROTECTED]> writes: > If we go ahead with this, I'll commit to doing a contrib README > cleanup so the doc system works better. Why wouldn't we just remove the README files altogether? I can't see maintaining duplicate sets of documentation. regards, tom lane ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [DOCS] [HACKERS] Contrib modules documentation online
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Tom Lane wrote: > Josh Berkus <[EMAIL PROTECTED]> writes: >> If we go ahead with this, I'll commit to doing a contrib README >> cleanup so the doc system works better. > > Why wouldn't we just remove the README files altogether? I can't > see maintaining duplicate sets of documentation. +1 Athough I could see a README at the top of contrib that says, contrib documentation is now here link / directory etc... Joshua D. Drake > > regards, tom lane > > ---(end of broadcast)--- > TIP 5: don't forget to increase your free space map settings > - -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 24x7/Emergency: +1.800.492.2240 PostgreSQL solutions since 1997 http://www.commandprompt.com/ UNIQUE NOT NULL Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate PostgreSQL Replication: http://www.commandprompt.com/products/ -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFG1bQQATb/zqfZUUQRAuYoAJ95zQkchY8pSq2BCyiy62ZAbA0hGgCdEHKt SXzpwREgcgVNXjolnQh927o= =mawb -END PGP SIGNATURE- ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
On Wed, 2007-08-29 at 13:53 -0400, Tom Lane wrote: > Why wouldn't we just remove the README files altogether? I can't > see maintaining duplicate sets of documentation. I agree that duplication is bad, but I think README files in the individual contrib directories is useful and worth keeping: if I'm about to install a contrib module and want to learn how to install and use it, this change would only make that information *more* difficult to find. I wonder if it would be possible to keep the master version of the contrib docs as SGML, and generate plaintext READMEs from it during the documentation build. -Neil ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] [HACKERS] Contrib modules documentation online
Tom Lane wrote: Josh Berkus <[EMAIL PROTECTED]> writes: If we go ahead with this, I'll commit to doing a contrib README cleanup so the doc system works better. Why wouldn't we just remove the README files altogether? I can't see maintaining duplicate sets of documentation. Right. Also, let's recall what has previously been discussed for contrib, namely that we break it out into standard modules (think Perl standard modules) and other tools, and that we abandon the wholly misleading "contrib" name altogether. I really want to see that happen next release. Getting the modules properly documented is a very important milestone along the way to getting that done. Maybe then the modules will be considered more first class citizens (until the buildfarm came along they were often hardly tested at all). cheers andrew ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
On 29/08/2007, Neil Conway <[EMAIL PROTECTED]> wrote: > > I wonder if it would be possible to keep the master version of the > contrib docs as SGML, and generate plaintext READMEs from it during the > documentation build. > Hello Neil, I think I'm doing something similar but not with README files. Currently I'm writing the FAQ into Docbook XML, that's why we can build the HTML and plain text at one. I'm going to finish this week then I'll show the results. > -- http://www.advogato.org/person/mgonzalez/ ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] [HACKERS] Contrib modules documentation online
On 8/29/07, Mario Gonzalez <[EMAIL PROTECTED]> wrote: > On 29/08/2007, Neil Conway <[EMAIL PROTECTED]> wrote: > > > > I wonder if it would be possible to keep the master version of the > > contrib docs as SGML, and generate plaintext READMEs from it during the > > documentation build. > > > > Hello Neil, I think I'm doing something similar but not with README > files. Currently I'm writing the FAQ into Docbook XML, that's why we > can build the HTML and plain text at one. While I like the idea of the READMEs from contrib being in the docs, I can't tell you the number of times I've installed a contrib module in a dark ops center at 2am with no html browser handy (or at best a text based one) or with no access to external internet etc... and just needed a line or two from the README file that came with the contrib module. Could the contrib README files couldn't be generated from the same source as the docs (i.e. sgml) and then put into the appropriate contrib/module/ directory. ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] [HACKERS] Contrib modules documentation online
On Aug 29, 2007, at 13:27 , Andrew Dunstan wrote: Also, let's recall what has previously been discussed for contrib, namely that we break it out into standard modules (think Perl standard modules) and other tools, and that we abandon the wholly misleading "contrib" name altogether. I really want to see that happen next release. +1 Michael Glaesemann grzm seespotcode net ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] [HACKERS] Contrib modules documentation online
Greg, > Are you suggesting to add an additional piece of work to the already > behind schedule 8.3 timeline when there's already this idea floating > around to overhaul the entire contrib structure in 8.4, which may very > well make much of that work redundant? Albert's work is cool and all, but > from from back here where I sit I'd expect anyone in a position to > integrate it into 8.3 properly should be working on something that's > already on the to-do list instead. Or the contrib overhaul may *not* get into 8.4 (ala updatable views). Having the contrib stuff in the main docs would remove one of the largest barriers to people knowing about the contrib features. Further, you know we don't finish the docs until beta. Ever. > I know I'm about to dump a big stack of 8.3 data onto the list I'd > appreciate some attention from you on, rather than having you distracted > cleaning up documentation that's perfectly functional for now. What kind of data? On bgwriter_lru autotuning? -- Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] [HACKERS] Contrib modules documentation online
Josh Berkus wrote: Greg, Are you suggesting to add an additional piece of work to the already behind schedule 8.3 timeline when there's already this idea floating around to overhaul the entire contrib structure in 8.4, which may very well make much of that work redundant? Albert's work is cool and all, but from from back here where I sit I'd expect anyone in a position to integrate it into 8.3 properly should be working on something that's already on the to-do list instead. Or the contrib overhaul may *not* get into 8.4 (ala updatable views). Having the contrib stuff in the main docs would remove one of the largest barriers to people knowing about the contrib features. I don't agree with Greg that we shouldn't make this docs improvement. I do think we should do it in such a way that it will fit with our plans for the future. cheers andrew ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
Scott Marlowe escribió: > Could the contrib README files couldn't be generated from the same > source as the docs (i.e. sgml) and then put into the appropriate > contrib/module/ directory. Sure they can. We already do that for INSTALL for example. -- Alvaro Herrera http://www.PlanetPostgreSQL.org/ ¡Ja ja ja! ¡Sólo hablaba en serio! ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
On 8/29/07, Alvaro Herrera <[EMAIL PROTECTED]> wrote: > Scott Marlowe escribió: > > > Could the contrib README files couldn't be generated from the same > > source as the docs (i.e. sgml) and then put into the appropriate > > contrib/module/ directory. > > Sure they can. We already do that for INSTALL for example. OK, s/Could/May/ up there. :) ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] [HACKERS] Contrib modules documentation online
Josh Berkus <[EMAIL PROTECTED]> writes: > Further, you know we don't finish the docs until beta. Ever. Right, working on docs is a standard beta-period activity. I think Greg is suggesting that right now is not the time to think about improving contrib docs --- right now is the time to keep our eyes on the ball and *get* to beta. If you've got time to worry about it afterward, do so then. regards, tom lane ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] [HACKERS] Contrib modules documentation online
> > I'm very strongly in favor of having this documentation. However, I think > it might make sense to put "Contrib Modules" as a section under either > "Reference" or "Appendices". Also, I don't think it's necessary to make > each command option a separate subchapter, but I can see how that would be > hard to avoid in an automated system. It's not an automated system, README files have different structures so it's all manual work. That's why I asked how you think it should be organized. Anyone else thinks we should put it in Reference or Appendixes? About command options if done different things, it depends on the module I need to revisit this. I also think one command per subchapter isn't very handy. There's also the install issue. By now it's on the introduction of the chapter. And I've repeated it in some of the modules, not all. Do you think it be better put the exact instructions for compiling and installing for each one? What about 'extra' notes, such us some performance tests, and so one. Some of the notes should probably stay in the README files, just like the README files that can be found in some dirs of core. So I'd keep information targeted to developers into the README's and general info into the main doc. > > Guys, would it be out of the question to do this in 8.3? Please please? I will try to have everything before 8.3. I'd like it gave very little or no work to core developers. If so many people is interested you can help me revise it before the final version. By the way, if somebody has updated any of the contrib README files recently, please send me an e-mail and I'll check if I have the last changes in. -- Albert Cervera i Areny http://www.NaN-tic.com ---(end of broadcast)--- TIP 6: explain analyze is your friend
Re: [DOCS] [HACKERS] Contrib modules documentation online
Albert Cervera i Areny wrote: I'm very strongly in favor of having this documentation. However, I think it might make sense to put "Contrib Modules" as a section under either "Reference" or "Appendices". Also, I don't think it's necessary to make each command option a separate subchapter, but I can see how that would be hard to avoid in an automated system. It's not an automated system, README files have different structures so it's all manual work. That's why I asked how you think it should be organized. Anyone else thinks we should put it in Reference or Appendixes? I would far rather have a new top level heading. Something like "Standard Modules and Tools". (Please avoid the use of the word "contrib"). If not, than as a sub-chapter of "References". I don't think it belongs in the Appendixes. cheers andrew ---(end of broadcast)--- TIP 6: explain analyze is your friend
