Re: Documentation for SET var_name FROM CURRENT - Mailing list pgsql-hackers

Amit Kapila-2 wrote
> On Tue, Oct 1, 2013 at 10:25 AM, David Johnston <

> polobo@

> > wrote:
>> Amit Kapila-2 wrote
>>> While reading documentation for SET command, I observed that FROM
>>> CURRENT syntax and its description is missing from SET command's
>>> syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html).
>>>
>>> Do you think that documentation should be updated for the same or is
>>> there any reason why it is not documented?
>>
>> It is documented as part of "CREATE FUNCTION" since its use is only valid
>> in
>> that context.
> 
>    Not only as part of "CREATE FUNCTION", but as part of "ALTER
> DATABASE", "ALTER ROLE", "ALTER FUNCTION" syntax as well. In all these
> places other syntax of "SET" is also used and described.
> I think you are right that syntax 
> <SET .. FROM CURRENT>
>  is mainly used
> in context with few other SQL statements, but as it is part of SET
> command, so isn't it better to mention the syntax on SET page and may
> be explain a bit about its usage?
> 
>> The paragraph with the link to CREATE FUNCTION seems
>> sufficient to notify and direct people to the needed description for
>> this.
> 
>    After explaining the usage in short, may be can provide links to
> all other statements where it can be used, but I think syntax 
> <SET ..
> FROM CURRENT>
>  should be there with SET command's other syntax.

FROM CURRENT is only valid as part of the SET sub-command attached to CREATE
FUNCTION.

Yes, a number of SQL commands take a sub-command called SET.  These are not
the same as the Top-level SQL SET command and have their own rules and
syntax defined on the parent command's page.  They share a key word to make
the grammar and usage saner but these are semantically different statements.

A paragraph cross-referencing where SET sub-commands exist has merit but
since the main SET command does not accept FROM CURRENT it (FC) should not
be included in its page directly.

If you want to put forth an actual documentation change and get a concrete
opinion then by all means.  If you want someone else to do it I'm detailing
why that is unlikely to happen.

The link to section 18.1 from the SET command documentation covers most of
the other relevant info about how to go about configuring the system.  The
SQL command reference is generally a much more narrow scope focusing on the
syntax of the specific command listed.  The current documentation for SET
conforms to this reality.

We both know how the settings sub-system works.  I don't see many novice
questions, though my only exposure is the mailing list, about this kind of
thing so the documentation seems effective.  Other than supposed
completeness are there other reasons you feel a change regarding FROM
CURRENT or SETtings in general need modification?

David J.






--
View this message in context:
http://postgresql.1045698.n5.nabble.com/Documentation-for-SET-var-name-FROM-CURRENT-tp5772920p5772958.html
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.