[squid-dev] [PATCH] Response delay pools

[Alex Rousskov]

On 02/16/2017 04:35 AM, Amos Jeffries wrote:

> Strictly speaking anything on the line - including the directive name is
> a parameter.

To minimize bickering, I will do my best to just focus on [what I
perceive as] important disagreements and ignore everything else,
including [what I perceive as] naming/terminology failures. Please do
not misinterpret my silence on any specific topic as an agreement.


> IMO, the named any-position parameters should all have some sensible
> default we can fall back on. Simply because being able to name it
> indicates we understand it well enough to know the scope/usage and can
> figure out a reasonable default from that.

There is no logical connection between being able to name something (or
knowing its scope/usage) and being able to select the right default for
it. We could name (and must know scope/usage of) all parameters, but,
obviously, some parameter values do not have reasonable defaults. You
are trying to establish a dependency between two orthogonal issues:
having a name and having a default value.


> So we dont
> have a huge editing job to re-document lots of things calling line
> values "options".

I agree that we should not start re-documenting anything, especially if
we cannot agree on basic terminology. So please don't start.


> We also need some simple way to indicate whether the thing being
> described is optional or mandatory in squid-users responses, squid.conf
> documentation etc.  For example; "the foo option" or "the foo parameter".

There is no way to do what you want in informal English. Your attempt to
introduce precise terminology where the readers do not expect it will
fail. Moreover, the terminology is itself too rigid because some
parameters become optional depending on the usage context -- being
optional is not always an absolute quality or permanent state.

Obviously, the documentation should say which parameter is optional but
we have to be explicit about it if we want humans to understand us. Most
humans will not infer that all "options" are optional simply because the
noun is often used to describe required (in a given context) things and
because many humans do not think in English (with no good/direct
translation of the subtle difference into their thinking language).

Fortunately, it does not take much to say that a parameter is optional!


And to preempt another iteration: There is nothing wrong with using the
word "option" for optional directive parameters and preferring the word
"parameter" for the required ones, of course. We just should not expect
the reader to find a hidden message in our words or to use the same
approach.


> "the foo named any-position parameter" is not very easily written or
> read. Particularly when the sentence or paragraph describing what it
> does and why its relevant may already be quite long and difficult to
> comprehend for newcomers.

Agreed, and nobody has proposed using text like "the named any-position
parameter" in squid.conf or help emails.

Interchangeably using "foo", "the foo parameter", and/or "a foo option"
is usually sufficient. And if virtually all named parameters are
any-position, the fact that they can be placed in any position will not
even come up in the vast majority of cases.


>> For directives that support ACLs, is the acl-list in (4) always optional
>> (with either "all" or "allow all" as the default)?

> Except when a different default is better. eg. always_direct,
> never_direct, and http_access.

I agree that the ACL defaults are directive-specific. To give developers
a useful common-case guideline, we can say that it is customary for
ACL-driven directives to default to "allow all" or equivalent, but
well-justified exceptions to that rule of thumb are acceptable, and any
defaults should be documented.


Anything you want Eduard to change before the commit?


Thank you,

Alex.