Re: Doc reference of contrib modules

From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Josh Kupershmidt <schmiddy(at)gmail(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, PostgreSQL-documentation <pgsql-docs(at)postgresql(dot)org>
Subject: Re: Doc reference of contrib modules
Date: 2011-01-25 14:59:52
Message-ID: 201101251459.p0PExqj11486@momjian.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Josh Kupershmidt wrote:
> On Mon, Jan 24, 2011 at 10:33 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> > Suggestions?
>
> For this bit:
>
> *** 686,693 ****
> AS t1(proname name, prosrc text)
> WHERE proname LIKE 'bytea%';
> </programlisting>
> ! The <literal>dblink</> function executes a remote query (see
> ! <filename>contrib/dblink</>). It is declared to return
> <type>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 <literal>*</> should
> --- 686,693 ----
> AS t1(proname name, prosrc text)
> WHERE proname LIKE 'bytea%';
> </programlisting>
> ! The <link linkend="CONTRIB-DBLINK">dblink</> function executes
> ! a remote query. It is declared to return
> <type>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 <literal>*</> 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 ).

That is an interesting case. I didn't mention "module" here because
above this ia a dblink() function call, and we are referencing the
function call in the text. I couldn't figure out how to mention
"module" here without making the text more complex. I thought of:

The <link linkend="CONTRIB-DBLINK">dblink</> function (part of the
dblink module) executes a remote query.

but that seems awkward. Ideas?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Tom Lane 2011-01-25 15:17:06 Re: Doc reference of contrib modules
Previous Message Josh Kupershmidt 2011-01-25 04:30:58 Re: Doc reference of contrib modules