Bug 245110 - Porter's handbook 5.4.3: clarify group in GH_TUPLE
Summary: Porter's handbook 5.4.3: clarify group in GH_TUPLE
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-doc (Nobody)
URL: https://docs.freebsd.org/en/books/por...
Depends on:
Reported: 2020-03-27 19:16 UTC by Vidar Karlsen
Modified: 2022-03-26 20:06 UTC (History)
1 user (show)

See Also:

svn diff from head/ (1.27 KB, patch)
2020-03-27 19:16 UTC, Vidar Karlsen
no flags Details | Diff
svn diff from head/ (1.27 KB, patch)
2020-03-28 12:35 UTC, Vidar Karlsen
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Vidar Karlsen 2020-03-27 19:16:21 UTC
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.

Build-tested and rendered ok.
igor is happy with the lines I changed.
Comment 1 Vidar Karlsen 2020-03-28 12:35:47 UTC
Created attachment 212788 [details]
svn diff from head/
Comment 2 Mathieu Arnold freebsd_committer 2020-03-29 15:53:54 UTC
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.
Comment 3 PauAmma freebsd_triage 2020-03-30 20:35:46 UTC
(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.
Comment 4 Vidar Karlsen 2020-03-31 17:34:49 UTC
(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
Comment 5 PauAmma freebsd_triage 2022-01-18 01:01:46 UTC
(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?
Comment 6 Vidar Karlsen 2022-01-18 20:55:29 UTC
(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.
Comment 7 PauAmma freebsd_triage 2022-03-26 19:51:10 UTC
(In reply to Mathieu Arnold from comment #2)

See https://docs.freebsd.org/en/books/fdp-primer/overview/#overview-documentation-ecosystem