[MacPorts] #71612: Guide section 5.3.2. Installation Phase Keywords is mistitled, and should explain keyword semantics better
MacPorts
noreply at macports.org
Sat Dec 21 21:09:53 UTC 2024
#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
Keywords: | Port:
-------------------------+--------------------
Presently the [https://guide.macports.org/#reference.phases.installation
Guide, section 5.3.2. "Installation Phase Keywords"] does not in fact
explain keywords which affect the installation phase. It introduces some
semantics of keywords, and it explains the behaviour of Keyword List
Modifiers like `-append`, and of Keyword Argument Modifiers like
`.pre_args`. So, I propose that this section be retitled something like,
"About Keywords".
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.
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.)" 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.
According to [https://github.com/macports/macports-
guide/blame/master/guide/xml/portfile-phase.xml#L165 gitblame of this
section's source], as best I understand it, the current title and content
of this section was transferred into the Guide from a macports man page
back in 2007, and has not been rewritten since.
--
Ticket URL: <https://trac.macports.org/ticket/71612>
MacPorts <https://www.macports.org/>
Ports system for macOS
More information about the macports-tickets
mailing list