Re: [HACKERS] man pages for contrib programs

2012-04-16 Thread Dimitri Fontaine
Peter Eisentraut pete...@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

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-12 Thread Peter Eisentraut
On ons, 2012-04-11 at 22:10 +0100, Thom Brown wrote:
 On 11 April 2012 21:58, Peter Eisentraut pete...@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.



-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-11 Thread Peter Eisentraut
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.


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-11 Thread Thom Brown
On 11 April 2012 21:29, Peter Eisentraut pete...@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

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-11 Thread Peter Eisentraut
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.


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-11 Thread Thom Brown
On 11 April 2012 21:58, Peter Eisentraut pete...@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

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


[HACKERS] man pages for contrib programs

2012-04-04 Thread Peter Eisentraut
... 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?



-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-04 Thread Alvaro Herrera

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 alvhe...@commandprompt.com
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-04 Thread Peter Eisentraut
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.



-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-04 Thread Thom Brown
On 4 April 2012 19:53, Peter Eisentraut pete...@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

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers


Re: [HACKERS] man pages for contrib programs

2012-04-04 Thread Robert Haas
On Wed, Apr 4, 2012 at 4:10 PM, Thom Brown t...@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

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers