[MacPorts] #71612: Guide section 5.3.2. Installation Phase Keywords is mistitled, and should explain keyword semantics better

[MacPorts]

#71612: Guide section 5.3.2. Installation Phase Keywords is mistitled, and should
explain keyword semantics better
--------------------------+--------------------
  Reporter:  JDLH         |      Owner:  (none)
      Type:  enhancement  |     Status:  new
  Priority:  Normal       |  Milestone:
 Component:  guide        |    Version:  2.10.5
Resolution:               |   Keywords:
      Port:               |
--------------------------+--------------------

Comment (by jmroot):

 Replying to [comment:4 JDLH]:
 > Fair enough. But, think of a Tcl naive portfile-modifying contributor,
 looking at this syntax:
 > {{{
 > configure.args             --bbb
 > }}}
 >
 > Is that a procedure call?  The use of an imperative verb in the name
 might give that impression. Or is the above an assignment, to a field
 named `args` in a structure named `configure`?
 > That is the sort of elementary Tcl documentation which the Guide could
 usefully stretch to cover. Just saying that "this is an assignment
 statement to a static data structure which gets used later in the port
 process" would give the clue that the second statement overrides the
 first.

 `configure.args` is an option, which is an entirely MacPorts-specific
 construct and so will not be covered in any Tcl tutorials. That code is in
 fact a procedure call, because that is how the key-value syntax of options
 is implemented. An explanation of how options work behind the scenes would
 be a good thing to have in the internals section of the Guide.

 The procedure with the same name as the option takes any number of
 arguments and sets the corresponding variable to the concatenation of all
 the args. Every option also defines `-append`, `-prepend`, `-delete` and
 `-replace` procedures.

-- 
Ticket URL: <https://trac.macports.org/ticket/71612#comment:5>
MacPorts <https://www.macports.org/>
Ports system for macOS