[squid-dev] [PATCH] Response delay pools

[Amos Jeffries]

On 16/02/2017 11:43 a.m., Alex Rousskov wrote:
> On 01/22/2017 12:52 PM, Amos Jeffries wrote:
>>  - a config line should have roughly this generic structure:
>>    1) directive (first label, which determines the syntax)
>>    2) parameters (mandatory values, fixed positions for each one)
>>    3) options (values that may be absent, using key[=value] syntax).
>>    4) acl-list (if relevant)
> 
> 
> Just for the record in case somebody tries to use the above as guidance
> for future work:
> 
> Item (2) is too rigid IMO: Required parameters may be named. And if
> there is more than one or two required parameters, they _should_ be
> named. Named parameters/options should not require fixed positions, of
> course.


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

parameters - plural of parameter - "any of a set of physical properties
whose values determine the characteristics or behavior of something"

In absence of a well-known word specifically implying mandatory-ness of
a parameter I choose to use 'parameter(s)' for that part of the
directive line which cannot be omitted (i.e. mandatory fixed-position
bits [if any]).


> 
> The "absent values" remark in item (3) applies to all all key=value
> parameters, both optional and required -- a named parameter value may be
> optional even if the parameter itself is required.
> 
> In summary, new directives should usually look like this:
> 
>   1) directive name
>   2) unnamed fixed-position parameter or two; keep this list short!
>   3) named any-position parameters
>   4) acl-list; may contain actions
> 
> Items 2, 3, and/or 4 may not be present/supported.
> 
> Some parameters may be optional.

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.

In which case *all* those parameters in (3) are optional in terms of
whether they can be omitted from squid.conf. None of them are mandatory.


So we might as well use the word with already well-known meaning and
implication of optional-ness to describe those optional parameters.

options - plural of option - "a thing which may be chosen; an
alternative course of action; an item that is offered in addition to or
in place of standard"


> 
> Named parameters have name=value syntax. Parameter names use dashes
> (boo-bar), not underscores/camelCase/etc. (not foo_bar/fooBar/foobar).
> Some named key=value parameters may support optional values.
> 
> I hope this is all common-sense and not be controversial!
> 

Not too much. I am looking at this mostly with an eye on existing
directives and not deviating from existing pattern too much. So we dont
have a huge editing job to re-document lots of things calling line
values "options".

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

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


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


> 
> @Eduard, I believe the last version of your patch satisfies the above
> rules but please correct me if I am wrong.
> 
> 
> Thank you,
> 
> Alex.
> 

Amos