Re: [DOCS] Doc reference of contrib modules
Josh Kupershmidt wrote: > 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 ). 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 dblink function (part of the dblink module) executes a remote query. but that seems awkward. Ideas? -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- 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
Bruce Momjian writes: > 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 dblink function (part of the > dblink module) executes a remote query. > but that seems awkward. Ideas? That's not just awkward, but flat wrong, because the link points to documentation of the module not the function. Correct would be something like The dblink() function (part of the dblink module) executes a remote query. 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
Tom Lane wrote: > Bruce Momjian writes: > > 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 dblink function (part of the > > dblink module) executes a remote query. > > > but that seems awkward. Ideas? > > That's not just awkward, but flat wrong, because the link points to > documentation of the module not the function. Correct would be > something like > > The dblink() function (part of the > dblink module) executes a remote query. The tag for the dblink module is: the function's tag is: so I believe the text in the patch is correct. (Yes, I realize those are confusing tags.) -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + -- 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
Bruce Momjian writes: > Tom Lane wrote: >> That's not just awkward, but flat wrong, because the link points to >> documentation of the module not the function. > The tag for the dblink module is: > > the function's tag is: > > so I believe the text in the patch is correct. (Yes, I realize those > are confusing tags.) Oh. Please change the function's tag to something a bit saner while you're messing around with this, FUNCTION-DBLINK perhaps? I still think that a link to the contrib module's page would be a good thing to provide here. 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
Tom Lane wrote:
> Bruce Momjian writes:
> > Tom Lane wrote:
> >> That's not just awkward, but flat wrong, because the link points to
> >> documentation of the module not the function.
>
> > The tag for the dblink module is:
>
> >
>
> > the function's tag is:
>
> >
>
> > so I believe the text in the patch is correct. (Yes, I realize those
> > are confusing tags.)
>
> Oh. Please change the function's tag to something a bit saner while
> you're messing around with this, FUNCTION-DBLINK perhaps?
OK, done in attached patch. (Git does allow easier incremental patch
generation.)
> I still think that a link to the contrib module's page would be a good
> thing to provide here.
Yep, but how to do it in a clear way?
--
Bruce Momjian http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
commit 82f2051a17355ec1bc00b969052967f7d6a59817
Author: Bruce Momjian
Date: Tue Jan 25 10:52:26 2011 -0500
Raname doc link for dblink() to "CONTRIB-DBLINK-FUNCTION", for clarity.
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 0e9cd22..295544e 100644
*** /tmp/QezWFa_dblink.sgml Tue Jan 25 10:53:18 2011
--- /tmp/4vCDsa_dblink.sgml Tue Jan 25 10:53:18 2011
*** SELECT dblink_disconnect('myconn');
*** 303,309
!
dblink
3
--- 303,309
!
dblink
3
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 3227b09..b995ff1 100644
*** /tmp/ogNVLa_queries.sgml Tue Jan 25 10:53:18 2011
--- /tmp/sUYrkb_queries.sgml Tue Jan 25 10:53:18 2011
*** SELECT *
*** 686,692
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
--- 686,692
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
--
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
Bruce Momjian writes: > Tom Lane wrote: >> I still think that a link to the contrib module's page would be a good >> thing to provide here. > Yep, but how to do it in a clear way? The parenthetical wording we just discussed seemed fine to me. 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
Tom Lane wrote: > Bruce Momjian writes: > > Tom Lane wrote: > >> I still think that a link to the contrib module's page would be a good > >> thing to provide here. > > > Yep, but how to do it in a clear way? > > The parenthetical wording we just discussed seemed fine to me. OK, done with the attached patch. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + commit aa37baebccda661ab0edf9c6bf8498f1fd315152 Author: Bruce Momjian Date: Tue Jan 25 11:51:40 2011 -0500 Mention dblink module when mentioning dblink function. diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index b995ff1..4160975 100644 *** /tmp/rbqvNe_queries.sgml Tue Jan 25 11:52:08 2011 --- /tmp/J4NBEe_queries.sgml Tue Jan 25 11:52:08 2011 *** SELECT * *** 686,692 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 --- 686,693 AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; ! The dblink function ! (part of the dblink module>) 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 -- 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
On mån, 2011-01-24 at 15:07 -0500, Bruce Momjian wrote: > 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. Please use instead of . -- 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
Peter Eisentraut wrote: > On m?n, 2011-01-24 at 15:07 -0500, Bruce Momjian wrote: > > 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. > > Please use instead of . Sorry. Having written README.link, you would think I would remember that. Updated patch attached. -- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + /rtmp/contrib.diff.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
