Re: GUC context information in the document.

From: Kyotaro HORIGUCHI <horiguchi(dot)kyotaro(at)lab(dot)ntt(dot)co(dot)jp>
To: tgl(at)sss(dot)pgh(dot)pa(dot)us
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: GUC context information in the document.
Date: 2015-04-09 07:01:41
Message-ID: 20150409.160141.21456423.horiguchi.kyotaro@lab.ntt.co.jp
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hello, thank you for the comment.

At Tue, 31 Mar 2015 15:07:08 -0400, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote in <24663(dot)1427828828(at)sss(dot)pgh(dot)pa(dot)us>
> Kyotaro HORIGUCHI <horiguchi(dot)kyotaro(at)lab(dot)ntt(dot)co(dot)jp> writes:
> > If I'm not missing anyting, putting stereotyped information about
> > GUC contexts like following would be usable.
>
> >> share_buffers (integer), (effective after server restart)
>
> >> log_destination (string), (effetive after config reload)
>
> >> log_min_duration_statement (integer), (effective in-session, superuser only)
>
> >> DateStyle (string), (effective in-session)
>
> > What do you think about this?
>
> TBH, those don't seem like improvements over the existing boilerplate
> texts, particularly not the last two.
>
> I follow the general idea of getting rid of the boilerplate sentences
> in favor of an annotation similar to the variable datatype notations;
> but such annotations would have to be *very* carefully wordsmithed
> to be both precise and understandable yet brief enough to fit ... and
> these are not. I'm not sure such a goal is possible at all.

Exactly. Inappropriate wording results in simply moving the
problem to another place, and I know I am completely not fit the
work..

> If we were to go in this direction, I'd favor just annotating with
> the same context keywords that we already expose to users in the
> pg_settings view, ie more like
>
> shared_buffers (integer, postmaster context)

This was an choice came to me but I feel it a little difficult to
recognize for users. But since any possible (simple) wording
won't tell what itself precisely means, and it would be easy to
maintain for developers, it seems the best way now.

> and then we'd need some introductory text in section 18.1 that defines
> these keywords. Maybe we could move the text about them that's currently
> associated with the pg_settings view (section 48.69 ATM).
>
> But TBH, I'm not sure that anything like this would reduce the number
> of questions. It's basically relying on the assumption that people would
> read section 18.1 before asking, and that's a shaky assumption.

Mmm. I completely agree with you about the first question for the
questioner. I hope that no second question comes (for the
questioner alone) if we could say "Hem, the answer for your
question is written here in the documentation.". But on the other
hand, I personally think that it is very similar to "Hem, the SQL
statement below gives you the answer for your question.".

Ok, this porposal doesn't seem to get approvals so much. I'll try
the second way above for the time being.

regards,

--
Kyotaro Horiguchi
NTT Open Source Software Center

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Michael Paquier 2015-04-09 07:06:17 Re: Making src/test/ssl more robust
Previous Message Dean Rasheed 2015-04-09 06:56:44 Re: Row security violation error is misleading