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

 Thank you for your comments, Ryan. I believe this is one of the cases
 where expert and naive views are both helpful for a good result. I will
 supply the naïvte. :-)

 Replying to [comment:3 ryandesign]:
 > Replying to [ticket:71612 JDLH]:
 > I can't think of any installation phase keywords. The installation phase
 is managed completely by MacPorts base; ports have no influence over it.

 Good. Then I favour section 5.3 saying so explicitly, for every phase
 which has no keywords.

 > > A [https://github.com/macports/macports-
 guide/pull/70#issuecomment-2558203424 comment on Pull Request #70 "guide:
 additions for subport"] says, …"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.

 I agree that the MacPorts guide should not have to replicate all of the
 Tcl language documentation. But at the same time, one can get a long way
 in portfile development by modifying an existing portfile in reasonable
 ways, despite Tcl ignorance, and seeing if it works. It seems to me that
 it benefits MacPorts to include enough basic Tcl language hints to extend
 how far a naive portfile modifier can go.

 > ...[The Guide] already has a link to the [https://www.tcl.tk/doc/ Tcl
 documentation] which contributors should consult if they are unfamiliar
 with the language.

 Yes, that's good. A link to a Tcl tutorial like
 https://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html would also help us
 naive folks figure out how to venture beyond simple assignment statements
 to, say, syntax of `if` statements.

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

 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.

 I read in a tutorial that upstream code could define:
 {{{
 proc configure.args {arg1} {
     # do something...
 }
 }}}
 ... and would this make the above statement a procedure call, aka command,
 rather than an assignment?

 The Guide does say in
 [https://guide.macports.org/#development.introduction Section 4.1.
 "Portfile [Development] Introduction"], that a portfile is a Tcl script:

 > ...A MacPorts Portfile is a Tcl script that usually contains only the
 simple keyword/value combinations and Tcl extensions as described in the
 Portfile Reference chapter, though it may also contain arbitrary Tcl
 code....

 But [https://guide.macports.org/#reference Chapter 5. "Portfile
 Reference"] does not say this until [https://guide.macports.org/#reference
 .tcl-extensions Section 5.6. "Tcl Extensions & Useful Tcl Commands"]:

 > A MacPorts Portfile is a Tcl script, so it may contain any arbitrary Tcl
 code you may learn about in the Tcl documentation.

 I think it would be helpful to move this up to a new section 5.1, which
 lays out a reference to the basics of portfiles.

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

 That sounds like a good tip to add to
 [https://guide.macports.org/#development.practices Section 4.7. "Portfile
 Best Practices"]. It also sounds like a different topic than either of the
 two concerns that motivated this ticket, so I would suggest it belongs in
 its own pull request.

 So, my scope is creeping onwards to include a new Section 5.1 to state
 some obvious basics about Portfiles, as well as to to change section 5.3's
 "Installation Phase" wording, and say explicitly that there are no
 keywords for the phases no currently mentioned. Would such a pull request
 be helpful?

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