Thread: man pages for contrib programs
... would be really nice to have. Especially pgbench and pg_upgrade for me, but it would be useful to have man pages for everything. Unfortunately, we can't just replace the sect1's in in Appendix F [0] with refentry's, because the content model of DocBook doesn't allow that. (You can't have a mixed sequence of sect1 and refentry, only one or the other.) [0] http://www.postgresql.org/docs/devel/static/contrib.html Which leads to a somewhat related point. The current content listing in Appendix F mixes extensions (backend modules) with client and server programs. Who can guess which is which here: ... pg_archivecleanup pgbench pg_buffercache pgcrypto pg_freespacemap pgrowlocks pg_standby pg_stat_statements ... I think it would be useful to split this up into three sections: F.1. Extensions F.2. Client Applications F.3. Server Applications where the first looks like now and the other two contain the refentry pages. (This could also serve as a hint to packagers to split their -contrib packages, so that say installing pgbench doesn't pull in a boatload of other stuff.) We could also consider making two separate appendixes. Maybe that would result in a better table of contents. Comments?
Excerpts from Peter Eisentraut's message of mié abr 04 15:53:20 -0300 2012: > ... would be really nice to have. Especially pgbench and pg_upgrade for > me, but it would be useful to have man pages for everything. > > Unfortunately, we can't just replace the sect1's in in Appendix F [0] > with refentry's, because the content model of DocBook doesn't allow > that. (You can't have a mixed sequence of sect1 and refentry, only one > or the other.) Hm, would it work to have something like <sect1> &pgbench; </sect1> <refentry> &pgbench; </refentry> so that we get both? Probably with some conditional to avoid duplicate output in html/pdf. (Why isn't this a problem for the SPI pages or dblink?) > I think it would be useful to split this up into three sections: > > F.1. Extensions > F.2. Client Applications > F.3. Server Applications > > where the first looks like now and the other two contain the refentry > pages. +1, but is there something that would not fit in either category? Not sure if we have a SGML page for init-scripts for instance. If you're going to monkey around in this general, please also look at the README. It should probably just go away. -- Álvaro Herrera <alvherre@commandprompt.com> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On ons, 2012-04-04 at 16:29 -0300, Alvaro Herrera wrote: > > Unfortunately, we can't just replace the sect1's in in Appendix F [0] > > with refentry's, because the content model of DocBook doesn't allow > > that. (You can't have a mixed sequence of sect1 and refentry, only one > > or the other.) > > Hm, would it work to have something like > <sect1> &pgbench; </sect1> <refentry> &pgbench; </refentry> > so that we get both? Probably with some conditional to avoid duplicate > output in html/pdf. I don't think I follow what you are trying to do there. > (Why isn't this a problem for the SPI pages or dblink?) The don't mix sects and refentries at the same level. > > I think it would be useful to split this up into three sections: > > > > F.1. Extensions > > F.2. Client Applications > > F.3. Server Applications > > > > where the first looks like now and the other two contain the refentry > > pages. > > +1, but is there something that would not fit in either category? Not > sure if we have a SGML page for init-scripts for instance. No, everything we have documented fits in those categories. > If you're going to monkey around in this general, please also look at > the README. It should probably just go away. Indeed.
On 4 April 2012 19:53, Peter Eisentraut <peter_e@gmx.net> wrote: > ... would be really nice to have. Especially pgbench and pg_upgrade for > me, but it would be useful to have man pages for everything. > > Unfortunately, we can't just replace the sect1's in in Appendix F [0] > with refentry's, because the content model of DocBook doesn't allow > that. (You can't have a mixed sequence of sect1 and refentry, only one > or the other.) > > [0] http://www.postgresql.org/docs/devel/static/contrib.html > > Which leads to a somewhat related point. The current content listing in > Appendix F mixes extensions (backend modules) with client and server > programs. Who can guess which is which here: > > ... > pg_archivecleanup > pgbench > pg_buffercache > pgcrypto > pg_freespacemap > pgrowlocks > pg_standby > pg_stat_statements > ... > > I think it would be useful to split this up into three sections: > > F.1. Extensions > F.2. Client Applications > F.3. Server Applications This is something I raised previously, but it didn't really attract much comment: http://archives.postgresql.org/pgsql-hackers/2011-10/msg00781.php +1 to anything that separates these out. Cramming them into one list like we currently have is confusing. -- Thom
On Wed, Apr 4, 2012 at 4:10 PM, Thom Brown <thom@linux.com> wrote: > +1 to anything that separates these out. Cramming them into one list > like we currently have is confusing. +1 as well. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On ons, 2012-04-04 at 21:53 +0300, Peter Eisentraut wrote: > I think it would be useful to split this up into three sections: > F.1. Extensions > F.2. Client Applications > F.3. Server Applications > where the first looks like now and the other two contain the refentry > pages. > We could also consider making two separate appendixes. Maybe that > would result in a better table of contents. I've played around with this a little bit to see how the tables of contents etc. turn out. I think the best approach is to have two appendixes F. Additional Supplied Extensions with one sect1 per extension, like now, and G. Additional Supplied Applications with two subsections Client and Server Applications, and one refentry per application. That would end up looking much like the SPI chapter.
On 11 April 2012 21:29, Peter Eisentraut <peter_e@gmx.net> wrote: > On ons, 2012-04-04 at 21:53 +0300, Peter Eisentraut wrote: >> I think it would be useful to split this up into three sections: > >> F.1. Extensions >> F.2. Client Applications >> F.3. Server Applications > >> where the first looks like now and the other two contain the refentry >> pages. > >> We could also consider making two separate appendixes. Maybe that >> would result in a better table of contents. > > I've played around with this a little bit to see how the tables of > contents etc. turn out. I think the best approach is to have two > appendixes > > F. Additional Supplied Extensions > > with one sect1 per extension, like now, and > > G. Additional Supplied Applications > > with two subsections Client and Server Applications, and one refentry > per application. That would end up looking much like the SPI chapter. Could you clarify what you're defining to be a client application and a server application? This could be confusing as we already have sections under Reference called "PostgreSQL Client Applications" and "PostgreSQL Server Applications", visible in the root table of contents. -- Thom
On ons, 2012-04-11 at 21:42 +0100, Thom Brown wrote: > > G. Additional Supplied Applications > > > > with two subsections Client and Server Applications, and one refentry > > per application. That would end up looking much like the SPI chapter. > > Could you clarify what you're defining to be a client application and > a server application? This could be confusing as we already have > sections under Reference called "PostgreSQL Client Applications" and > "PostgreSQL Server Applications", visible in the root table of > contents. > By the same criteria as the main reference: client applications can run anywhere and connect to a server, server applications run on the same host as the database server.
On 11 April 2012 21:58, Peter Eisentraut <peter_e@gmx.net> wrote: > On ons, 2012-04-11 at 21:42 +0100, Thom Brown wrote: >> Could you clarify what you're defining to be a client application and >> a server application? This could be confusing as we already have >> sections under Reference called "PostgreSQL Client Applications" and >> "PostgreSQL Server Applications", visible in the root table of >> contents. >> > By the same criteria as the main reference: client applications can run > anywhere and connect to a server, server applications run on the same > host as the database server. Fair enough. So will you be classifying things like auto_explain and auth_delay as "extensions"? (i.e. things which aren't installed via CREATE EXTENSION) -- Thom
On ons, 2012-04-11 at 22:10 +0100, Thom Brown wrote: > On 11 April 2012 21:58, Peter Eisentraut <peter_e@gmx.net> wrote: > > On ons, 2012-04-11 at 21:42 +0100, Thom Brown wrote: > >> Could you clarify what you're defining to be a client application and > >> a server application? This could be confusing as we already have > >> sections under Reference called "PostgreSQL Client Applications" and > >> "PostgreSQL Server Applications", visible in the root table of > >> contents. > >> > > By the same criteria as the main reference: client applications can run > > anywhere and connect to a server, server applications run on the same > > host as the database server. > > Fair enough. > > So will you be classifying things like auto_explain and auth_delay as > "extensions"? (i.e. things which aren't installed via CREATE > EXTENSION) Good question. I guess we could keep the original name "... Modules" for that chapter.
Peter Eisentraut <peter_e@gmx.net> writes: > Good question. I guess we could keep the original name "... Modules" > for that chapter. Those are a kind of server application in my mind, I think we want to keep using “module” to mean the shared library file we load at runtime, be it a .so, a .dylib or a .dll. That said, those non-extension stuff are most often just a module. Regards, -- Dimitri Fontaine http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support