Обсуждение: Contrib modules documentation online
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
There is a problem with line feeds for contrib/xml2: http://www.nan-tic.com/ftp/pgdoc/xml2.html As for idea itself, I find it very useful (besides usability improvements, it would help to promote Postgres advanced features). On 8/29/07, Albert Cervera i Areny <albert@nan-tic.com> wrote: > 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 > > ---------------------------(end of broadcast)--------------------------- > TIP 4: Have you searched our list archives? > > http://archives.postgresql.org > -- Best regards, Nikolay
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
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 decibel@decibel.org EnterpriseDB http://enterprisedb.com 512.569.9461 (cell)
Вложения
Josh Berkus <josh@agliodbs.com> 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
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Tom Lane wrote:
> Josh Berkus <josh@agliodbs.com> 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-----
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
Tom Lane wrote: > Josh Berkus <josh@agliodbs.com> 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
On 29/08/2007, Neil Conway <neilc@samurai.com> 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/
On Wed, 29 Aug 2007, Josh Berkus wrote: > Guys, would it be out of the question to do this in 8.3? Please please? 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. 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. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
On 8/29/07, Mario Gonzalez <gonzalemario@gmail.com> wrote: > On 29/08/2007, Neil Conway <neilc@samurai.com> 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.
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
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
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
Josh Berkus wrote: > Having the contrib stuff in the main docs would remove one of the largest barriers > to people knowing about the contrib features. > Using PostgreSQL since Version 7.1.3 and reading this List since - I dont't know exactly but my current archives start in 2003 which was the last time I crashed my system - Albert's work is actually the first piece of contrib documentation I ever read. I always knew about contrib but as I haven't been missing any feature in the core distribution (well - actually I've been missing PL/R until it came up - but as you know it's not in contrib ;-) I never found time to dig into the contrib directories and README's. Now that I did I'm pretty amazed about the nice features I've never thought about. > Further, you know we don't finish the docs until beta. Ever. > Whenever you want - but do it. I also highly appreciate Albert's Idea/Work. Regards, Brar
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!
On Wed, 29 Aug 2007, Josh Berkus wrote: > Further, you know we don't finish the docs until beta. Ever. In that context, as long as the documentation cleanup doesn't slow the schedule for when beta starts I think it would be a great thing to slip into 8.3. In fact, if those are going higher-profile, I may slip an update into the docs for pg_buffercache with the queries I keep recommending people look at. > What kind of data? On bgwriter_lru autotuning? That would be my data; HOT is in a similar category. I have many test results to pass along, and I'd like to know that the people who might help confirm/deny what I've discovered are as focused as I've been on trying to wrap all this up already, before wandering into new tangents that aren't already blocking the schedule. That's all I'm saying. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
On 8/29/07, Alvaro Herrera <alvherre@commandprompt.com> 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. :)
Josh Berkus <josh@agliodbs.com> 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
> > 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
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
Andrew Dunstan a écrit : > > > 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. > Appendixes or References are fine to me but not on a top level heading. References would certainly be my (light) preference. If you can find a way to keep each one of them on a single page, it would be best. Having one page for the installation procedure only (see for example this page http://www.nan-tic.com/ftp/pgdoc/x76728.html) is a little too much. Anyways, great work, Albert. Thanks. Regards. -- Guillaume. <!-- http://abs.traduc.org/ http://lfs.traduc.org/ http://docs.postgresqlfr.org/ -->
Am Mittwoch, 29. August 2007 20:18 schrieb Neil Conway: > 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. Using asciidoc you could do it the other way around. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Am Mittwoch, 29. August 2007 20:27 schrieb Andrew Dunstan: > Also, let's recall what has previously been discussed for contrib, > namely that we break it out into standard modules But that would also mean that the documentation system is somewhat modularized. That is, if I deinstall some module, it disappears from the documentation. And if I install a module from some other place, its documentation would appear in the same place where the other modules already show up. I haven't seen the inside of the current proposal, but if it just copies the SGML-converted documentation into the documentation directory with everything else, it doesn't quite accomplish that. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > Am Mittwoch, 29. August 2007 20:27 schrieb Andrew Dunstan: > >> Also, let's recall what has previously been discussed for contrib, >> namely that we break it out into standard modules >> > > But that would also mean that the documentation system is somewhat > modularized. What? No it doesn't. You have missed the key word in the sentence above: "standard". The idea is that the docs will describe the *standard* modules, i.e. those that ship with the PostgreSQL core distribution (because they are currently in contrib). If you want to design a pluggable documentation system then go for it, but it's not required by what I understand is the consensus plan for contrib. cheers andrew
Andrew Dunstan <andrew@dunslane.net> writes:
> If you want to design a pluggable documentation system then go for it,
> but it's not required by what I understand is the consensus plan for
> contrib.
I thought a large part of the desire was to improve the visibility of
the contrib docs, ie, put the docs under the noses of people who have
*not* installed or even heard of the modules. So "it's not in the docs
unless you installed it" seems counter to the point.
regards, tom lane
Am Donnerstag, 30. August 2007 15:13 schrieb Andrew Dunstan:
> What? No it doesn't. You have missed the key word in the sentence above:
> "standard". The idea is that the docs will describe the *standard*
> modules, i.e. those that ship with the PostgreSQL core distribution
> (because they are currently in contrib).
>
> If you want to design a pluggable documentation system then go for it,
> but it's not required by what I understand is the consensus plan for
> contrib.
That brings up additional questions such as what is standard and whose
consensus. You initially referred to Perl, and I note that Perl modules
shipped with the main Perl package ("standard"?) and those that are not
provide access to their facilities in identical ways. That's as far as I can
read your mind anyway. ;-)
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
Am Donnerstag, 30. August 2007 15:26 schrieb Tom Lane: > I thought a large part of the desire was to improve the visibility of > the contrib docs, ie, put the docs under the noses of people who have > *not* installed or even heard of the modules. So "it's not in the docs > unless you installed it" seems counter to the point. I thought the point was to make the extensibility features of PostgreSQL more usable so people would be more inclined to use them. The assumption being that the problem is not finding things but the hesitation against using "unofficial" things. Moving everything to the main blob of things seems to go against that idea. So perhaps some market research is required to clarify the actual requirements and goals. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > Am Donnerstag, 30. August 2007 15:26 schrieb Tom Lane: > >> I thought a large part of the desire was to improve the visibility of >> the contrib docs, ie, put the docs under the noses of people who have >> *not* installed or even heard of the modules. So "it's not in the docs >> unless you installed it" seems counter to the point. >> > > I thought the point was to make the extensibility features of PostgreSQL more > usable so people would be more inclined to use them. The assumption being > that the problem is not finding things but the hesitation against > using "unofficial" things. Moving everything to the main blob of things > seems to go against that idea. > > So perhaps some market research is required to clarify the actual requirements > and goals. > > The idea that seemed to gain traction last time this was discussed was to treat the contrib modules as standard, included in the core distribution as examples of how modules work, and as modules that have moderately wide use (not sure how true that is of all of them, but I don't see any great point in pushing them out.) Quite apart from anything else, keeping them part of the main distribution helps us to validate the module process via buildfarm etc. So this isn't just "moving everything to the main blob of things". If you want to pay for market research then feel free ;-) cheers andrew