Doc reference of contrib modules

Bruce Momjian <bruce@momjian.us> 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

[ repost with compressed diff]

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> 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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

On Mon, Jan 24, 2011 at 10:33 PM, Bruce Momjian <bruce@momjian.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 ).

Josh

Josh Kupershmidt wrote:

On Mon, Jan 24, 2011 at 10:33 PM, Bruce Momjian <bruce@momjian.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@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Bruce Momjian <bruce@momjian.us> 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 <link linkend="CONTRIB-DBLINK">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 <function>dblink()</> function (part of the
<link linkend="CONTRIB-DBLINK">dblink</> module) executes a remote query.

regards, tom lane

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> 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 <link linkend="CONTRIB-DBLINK">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 <function>dblink()</> function (part of the
<link linkend="CONTRIB-DBLINK">dblink</> module) executes a remote query.

The tag for the dblink module is:

<sect1 id="dblink">

the function's tag is:

<refentry id="CONTRIB-DBLINK">

so I believe the text in the patch is correct. (Yes, I realize those
are confusing tags.)

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Bruce Momjian <bruce@momjian.us> 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:

<sect1 id="dblink">

the function's tag is:

<refentry id="CONTRIB-DBLINK">

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

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> 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:

<sect1 id="dblink">

the function's tag is:

<refentry id="CONTRIB-DBLINK">

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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Bruce Momjian <bruce@momjian.us> 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

Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> 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 <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

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 <xref> instead of <link>.

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 <xref> instead of <link>.

Sorry. Having written README.link, you would think I would remember
that. Updated patch attached.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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

Bruce Momjian wrote:

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 <xref> instead of <link>.

Sorry. Having written README.link, you would think I would remember
that. Updated patch attached.

Applied. Thanks for all the feedback.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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