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: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-doc (Nobody)
URL: https://docs.freebsd.org/en/books/por...
Keywords:
Depends on:
Blocks:
 
Reported: 2020-03-27 19:16 UTC by Vidar Karlsen
Modified: 2022-08-13 09:40 UTC (History)
2 users (show)

See Also:


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

QA:
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 freebsd_triage 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 Pau Amma 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 Pau Amma 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 Pau Amma 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
Comment 8 Gleb Popov freebsd_committer freebsd_triage 2022-07-20 08:01:23 UTC
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.
Comment 9 Vidar Karlsen 2022-07-23 14:43:09 UTC
(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?