Created attachment 212766 [details] svn diff from head/ 5.4.3 USE_GITHUB describes the available variables, but doesn't speak very clearly about GH_TUPLE's group parameter. The group is only mentioned in the format, and the lack of : as a separator between group and subdir is not mentioned at all. I propose adding a couple bits of clarification to the description field, please see attached svn diff. QA: Build-tested and rendered ok. igor is happy with the lines I changed.
Created attachment 212788 [details] svn diff from head/
I do not see the point of the change. group is only the grouping mechanism, and the "format" describes precisely how to fill up the variable.
(In reply to Mathieu Arnold from comment #2) > I do not see the point of the change. I disagree. Coming in as a novice porter, and one who took part in the discussion about documenting this better in IRC, I found that bit confusing as well when I first read through the Porter's Handbook. I believe that when newcomers find documentation language confusing, something has to give, and that something shouldn't be the newcomers' goodwill and interest in porting.
(In reply to Mathieu Arnold from comment #2) Yes, it is technically all documented, but it took me a while to figure it out. I suppose this is easy to grasp if one is familiar with the grouping in the first place, but it's not overly clear where to look if one doesn't have that baggage. I ended up looking at how it had been solved in other ports before going back to reading and understanding the Porter's Handbook with newly acquired knowledge from the tree. A clarification like this would have made it much easier for me, and not unlikely for others in similar situations. There is also a review[1] for this, as I'm not sure if Bugzilla or Phabricator is the best way of handling it. [1] https://reviews.freebsd.org/D24208
(In reply to Vidar Karlsen from comment #4) I just found out unrelatedly about ports-mgmt/modules2tuple, and I'm wondering: would it help with your use case?
(In reply to PauAmma from comment #5) Thanks for the tip. This might be useful in certain cases, but the issue at hand is unclear documentation, not lack of tooling.
(In reply to Mathieu Arnold from comment #2) See https://docs.freebsd.org/en/books/fdp-primer/overview/#overview-documentation-ecosystem
I just stumbled upon related problem with GH_TUPLE. Having GH_TUPLE= input-output-hk:cardano-base:0f3a867493059e650cda69e20a5cbf1ace289a57:dist-newstyle/src/cardano-b_-c8db9876882556ed results in The input-output-hk:cardano-base:0f3a867493059e650cda69e20a5cbf1ace289a57:dist-newstyle/src/cardano-b_-c8db9876882556ed GH_TUPLE line has a tag containing something else than [a-zA-Z0-9_] *** Error code 1 which is highly misleading error message. By trial and error I figured out that the problem is actually not with tagname, but the last part of the tuple. For instance, replacing "dist-newstyle" with "dist_newstyle" makes the problem go away. It'd be great to have an even more detailed explanation on the ``` Note that <replaceable>group</replaceable> and <replaceable>/subdir</replaceable> are not separated by a <literal>:</literal> like the other parameters.</entry> ``` part from the patch.
(In reply to Gleb Popov from comment #8) > It'd be great to have an even more detailed explanation Absolutely. Do you have any suggestions on how to phrase it?