[DOCS] Doc reference of contrib modules

2011-01-24 Thread Bruce Momjian 
Now that our /contrib documentation is in our SGML manual, I want to
update our docs to link to the actual contrib module documentation,
rather than just referencing contrib/module_name.  We used to have to do
that when we only had READMEs, but now we can do better.

Patch attached, and I have a github branch of this too:

https://github.com/bmomjian/postgres/compare/master...contrib_links

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f994eac..2d053ee 100644
*** /tmp/pgdiff.21665/EgdqAa_datatype.sgml	Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/GzEpPa_datatype.sgml	Mon Jan 24 15:04:28 2011
*** a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
*** 3917,3925 
  PostgreSQL provides storage and comparison
  functions for UUIDs, but the core database does not include any
  function for generating UUIDs, because no single algorithm is well
! suited for every application.  The contrib module
! contrib/uuid-ossp provides functions that implement
! several standard algorithms.
  Alternatively, UUIDs could be generated by client applications or
  other libraries invoked through a server-side function.
 
--- 3917,3925 
  PostgreSQL provides storage and comparison
  functions for UUIDs, but the core database does not include any
  function for generating UUIDs, because no single algorithm is well
! suited for every application.  The module
! uuid-ossp
! provides functions that implement several standard algorithms.
  Alternatively, UUIDs could be generated by client applications or
  other libraries invoked through a server-side function.
 
diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
index 0f390f3..006a98f 100644
*** /tmp/pgdiff.21665/4PWjMc_diskusage.sgml	Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/s8xDFc_diskusage.sgml	Mon Jan 24 15:04:28 2011
***
*** 31,40 

 You can monitor disk space in three ways:
 using the SQL functions listed in ,
!using the tools in contrib/oid2name, or
 using manual inspection of the system catalogs.
 The SQL functions are the easiest to use and are generally recommended.
-contrib/oid2name is described in .
 The remainder of this section shows how to do it by inspection of the
 system catalogs.

--- 31,39 

 You can monitor disk space in three ways:
 using the SQL functions listed in ,
!using the oid2name module, or
 using manual inspection of the system catalogs.
 The SQL functions are the easiest to use and are generally recommended.
 The remainder of this section shows how to do it by inspection of the
 system catalogs.

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index d884122..c672266 100644
*** /tmp/pgdiff.21665/Y2ePnb_high-availability.sgml	Mon Jan 24 15:04:28 2011
--- /tmp/pgdiff.21665/e9NdPb_high-availability.sgml	Mon Jan 24 15:04:28 2011
*** primary_conninfo = 'host=192.168.1.50 po
*** 967,973 
  This was the only option available in versions 8.4 and below. In this
  setup, set standby_mode off, because you are implementing
  the polling required for standby operation yourself. See
! contrib/pg_standby () for a reference
  implementation of this.
 
  
--- 967,973 
  This was the only option available in versions 8.4 and below. In this
  setup, set standby_mode off, because you are implementing
  the polling required for standby operation yourself. See
! pg_standby for a reference
  implementation of this.
 
  
*** if (!triggered)
*** 1027,1033 
  
 
  A working example of a waiting restore_command is provided
! as a contrib module named pg_standby. It
  should be used as a reference on how to correctly implement the logic
  described above. It can also be extended as needed to support specific
  configurations and environments.
--- 1027,1033 
  
 
  A working example of a waiting restore_command is provided
! in pg_standby. It
  should be used as a reference on how to correctly implement the logic
  described above. It can also be extended as needed to support specific
  configurations and environments.
*** if (!triggered)
*** 1542,1548 
  primary server and keep a query active for as long as needed to
  run queries on the standby. This prevents VACUUM from removing
  recently-dead rows and so cleanup conflicts do not occur.
! This could be done using contrib/dblink and
  pg_sleep(), or via other mechanisms. If you do this, you
  should note that this will delay cleanup of dead rows on the primary,
  which may result in undesirable table bloat. However, the

Re: [DOCS] Doc reference of contrib modules

2011-01-24 Thread Tom Lane 
Bruce Momjian  writes:
> Now that our /contrib documentation is in our SGML manual, I want to
> update our docs to link to the actual contrib module documentation,
> rather than just referencing contrib/module_name.  We used to have to do
> that when we only had READMEs, but now we can do better.

> Patch attached, and I have a github branch of this too:

This proposed patch seems quite inconsistent.  You have removed the term
"contrib" in some places and not others.  I'm fine with just referring
to stuff as "the so-and-so module" without use of the word "contrib",
but if that's what we're going to do then all the references should look
like that.

Also, I see some places where you removed the word contrib *without*
turning the reference into a link.  I think that's a seriously bad idea,
since it leaves the reader with no hint of where to look in our
thousand-page-plus manual.

regards, tom lane

-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Doc reference of contrib modules

2011-01-24 Thread Bruce Momjian 
[ repost with compressed diff]

Tom Lane wrote:
> Bruce Momjian  writes:
> > Now that our /contrib documentation is in our SGML manual, I want to
> > update our docs to link to the actual contrib module documentation,
> > rather than just referencing contrib/module_name.  We used to have to do
> > that when we only had READMEs, but now we can do better.
>
> > Patch attached, and I have a github branch of this too:
>
> This proposed patch seems quite inconsistent.  You have removed the term
> "contrib" in some places and not others.  I'm fine with just referring
> to stuff as "the so-and-so module" without use of the word "contrib",
> but if that's what we're going to do then all the references should look
> like that.

OK, I found a few more places;  new patch attached. I also updated
github:

https://github.com/bmomjian/postgres/compare/master...contrib_links

> Also, I see some places where you removed the word contrib *without*
> turning the reference into a link.  I think that's a seriously bad idea,
> since it leaves the reader with no hint of where to look in our

Well, the only place I did that was with tsearch2, and I had already
linked to it in the paragraph above so it seemed duplicative to do it
again.  I did call it "module".  You can see the result here:

http://momjian.us/tmp/pgsql/textsearch-migration.html

Suggestions?

-- 
  Bruce Momjian  http://momjian.us
  EnterpriseDB http://enterprisedb.com

  + It's impossible for everything to be true. +


/rtmp/contrib_links.gz
Description: GNU Zip compressed data

-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

Re: [DOCS] Doc reference of contrib modules

2011-01-24 Thread Josh Kupershmidt 
On Mon, Jan 24, 2011 at 10:33 PM, Bruce Momjian  wrote:
> Suggestions?

For this bit:

*** 686,693 
AS t1(proname name, prosrc text)
  WHERE proname LIKE 'bytea%';
  
!  The dblink function executes a remote query (see
!  contrib/dblink).  It is declared to return
   record since it might be used for any kind of query.
   The actual column set must be specified in the calling query so
   that the parser knows, for example, what * should
--- 686,693 
AS t1(proname name, prosrc text)
  WHERE proname LIKE 'bytea%';
  
!  The dblink function executes
!  a remote query.  It is declared to return
   record since it might be used for any kind of query.
   The actual column set must be specified in the calling query so
   that the parser knows, for example, what * should

I think the changed line should explicitly mention "dblink module",
otherwise it's easy to miss that dblink() comes from contrib.
Especially since the target page of that link:
  http://www.postgresql.org/docs/current/static/contrib-dblink.html
doesn't mention the words "contrib" or "module" anywhere (most other
contrib modules have a header saying "Appendix F. Additional Supplied
Modules" at the top of the page, but the dblink function pages don't
since they're subpages of
http://www.postgresql.org/docs/current/static/dblink.html ).

Josh

-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs