[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 ryandesign):

 Replying to [ticket:71612 JDLH]:
 > The current section 5.3.2 does not appear to have any content about
 installation phase keywords. If such keywords exist, I suggest that they
 be documented in a new section, after
 [https://guide.macports.org/#reference.phases.destroot 5.3.10. "Destroot
 Phase Keywords"], and based on that section's structure.

 I can't think of any installation phase keywords. The installation phase
 is managed completely by MacPorts base; ports have no influence over it.

 > A [https://github.com/macports/macports-
 guide/pull/70#issuecomment-2558203424 comment on Pull Request #70 "guide:
 additions for subport"] says, "Please explain the rules when there are
 apparent conflicting definitions, such as configure.args in example-sub1.
 Do not assume that the reader is confident in basic TCL. (That would be
 me, for example.)"

 In my view, familiarity with Tcl is a basic requirement of contributing to
 MacPorts and explaining how the programming language works in the MacPorts
 guide feels unnecessary.

 [https://guide.macports.org/#reference.tcl-extensions It does document]
 some of the `file` commands because they're used often and as an
 introduction to the subsequent mention of shorthand commands MacPorts
 provides for those `file` commands, and other MacPorts-specific Tcl
 commands. It also already has a link to the [https://www.tcl.tk/doc/ Tcl
 documentation] which contributors should consult if they are unfamiliar
 with the language.

 > The comment refers to a subport which repeats a keyword in the main port
 definition, but with a different value. For instance, what is the result
 if a port file boils down to the sequence,
 > {{{
 > configure.args             --bbb
 > configure.args             --ddd</programlisting>
 > }}}
 > I suspect that the value of `--bbb` is completely replaced by the value
 of `--ddd</programlisting>`, but I do not see the Guide saying so. I
 suggest documenting these rules in the retitled section 5.3.2.

 In Tcl and in every other programming language I can think of, setting a
 variable overwrites the previous value so I see no need to explain that in
 the MacPorts guide.

 I do consider it bad practice to overwrite variables in subports or
 variants. As Portfiles age and get longer and pass through different
 maintainership, it becomes increasingly likely that a new contributor may
 add a flag to (for example) the `configure.args` in the global part of the
 Portfile and expect it to be used throughout the Portfile, not realizing
 that a far-down variant or subport overrides it.

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