File_fdw documentation patch to clarify OPTIONS clause

Started by Mike Blackwellover 12 years ago4 messages

mike.blackwell@rrd.com

over 12 years ago

1 attachment(s)

The file_fdw documentation for the OPTIONS clause references the COPY
command's documentation. In the case of COPY, the value for some options
(e.g. HEADER, OIDS, ...) is optional. While the file_fdw documentation
makes no mention of it, the values for all options are required.

Attached is a patch to add a note to the docs mentioning this fact.

__________________________________________________________________________________
*Mike Blackwell | Technical Analyst, Distribution Services/Rollout
Management | RR Donnelley*
1750 Wallace Ave | St Charles, IL 60174-3401
Office: 630.313.7818
Mike.Blackwell@rrd.com

http://www.rrdonnelley.com

<http://www.rrdonnelley.com/>
* <Mike.Blackwell@rrd.com>*

Attachments:

file-fdw-doc.patchapplication/octet-stream; name=file-fdw-doc.patchDownload

diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml
index 8c52761..d7e508d 100644
--- a/doc/src/sgml/file-fdw.sgml
+++ b/doc/src/sgml/file-fdw.sgml
@@ -112,6 +112,10 @@
  </variablelist>
 
  <para>
+  Note that, unlike <command>COPY</>, an option's value is always required here.
+ </para>
+
+ <para>
   A column of a foreign table created using this wrapper can have the
   following options:
  </para>

Robert Haas

robertmhaas@gmail.com

over 12 years ago

In reply to: Mike Blackwell (#1)

Re: File_fdw documentation patch to clarify OPTIONS clause

On Fri, Sep 20, 2013 at 4:26 PM, Mike Blackwell <mike.blackwell@rrd.com> wrote:

The file_fdw documentation for the OPTIONS clause references the COPY
command's documentation. In the case of COPY, the value for some options
(e.g. HEADER, OIDS, ...) is optional. While the file_fdw documentation
makes no mention of it, the values for all options are required.

Attached is a patch to add a note to the docs mentioning this fact.

I think this would be a good thing to document, but it took me a
minute to properly understand what you were saying. So I'd like to
suggest slightly different wording: "Note that while COPY allows
options such as OIDS and HEADER to be specified without a
corresponding value, the foreign data wrapper syntax requires a value
to be present in all cases. To activate COPY options normally
supplied without a value, you can instead pass the value TRUE."

Other suggestions welcome if you don't like that text...

--
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

Mike Blackwell

mike.blackwell@rrd.com

over 12 years ago

In reply to: Robert Haas (#2)

1 attachment(s)

Re: File_fdw documentation patch to clarify OPTIONS clause

Robert,

Thanks for the reply. I have no objections to clarifying the note.
Attached is a patch with the text you suggested.

Mike

<http://www.rrdonnelley.com/>
* <Mike.Blackwell@rrd.com>*

On Mon, Sep 23, 2013 at 11:42 AM, Robert Haas <robertmhaas@gmail.com> wrote:

Show quoted text

On Fri, Sep 20, 2013 at 4:26 PM, Mike Blackwell <mike.blackwell@rrd.com>
wrote:

The file_fdw documentation for the OPTIONS clause references the COPY
command's documentation. In the case of COPY, the value for some options
(e.g. HEADER, OIDS, ...) is optional. While the file_fdw documentation
makes no mention of it, the values for all options are required.

Attached is a patch to add a note to the docs mentioning this fact.

I think this would be a good thing to document, but it took me a
minute to properly understand what you were saying. So I'd like to
suggest slightly different wording: "Note that while COPY allows
options such as OIDS and HEADER to be specified without a
corresponding value, the foreign data wrapper syntax requires a value
to be present in all cases. To activate COPY options normally
supplied without a value, you can instead pass the value TRUE."

Other suggestions welcome if you don't like that text...

--
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

Attachments:

file-fdw-doc.patchapplication/octet-stream; name=file-fdw-doc.patchDownload

diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml
index 8c52761..9385b26 100644
--- a/doc/src/sgml/file-fdw.sgml
+++ b/doc/src/sgml/file-fdw.sgml
@@ -112,6 +112,14 @@
  </variablelist>
 
  <para>
+  Note that while <command>COPY</> allows options such as OIDS and HEADER 
+  to be specified without a corresponding value, the foreign data wrapper
+  syntax requires a value to be present in all cases.  To activate 
+  <command>COPY</> options normally supplied without a value, you can
+  instead pass the value TRUE. 
+ </para>
+
+ <para>
   A column of a foreign table created using this wrapper can have the
   following options:
  </para>

Robert Haas

robertmhaas@gmail.com

over 12 years ago

In reply to: Mike Blackwell (#3)

Re: File_fdw documentation patch to clarify OPTIONS clause

On Mon, Sep 23, 2013 at 2:24 PM, Mike Blackwell <mike.blackwell@rrd.com> wrote:

Thanks for the reply. I have no objections to clarifying the note.
Attached is a patch with the text you suggested.

Committed, thanks. Per relatively-usual practice for doc
clarifications, I back-patched this one release but not further.

--
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