[phb]: Document inclusion of Makefile.* files

[fernape]

Summary

Document the automatic inclusion of several Makefile.* files.
Also mention idiomatic splitting of pkg-plist.* files.

PR: 244742
Reported by: salvadore@

Test Plan

• Apply patch
• make documentation

[carlavilla]

Ok but use the one sentence per line please, no need to update the review, can be changed in the commit.
Apart from that ok from docs side :)

[fernape]

In D41625#948632, @carlavilla wrote:

Ok but use the one sentence per line please, no need to update the review, can be changed in the commit.
Apart from that ok from docs side :)

Ummm.. I think I did. Did I miss one?
Maybe the confusion is that the lines are wrapped at 80 characters?

[carlavilla]

documentation/content/en/books/porters-handbook/special/_index.adoc

57

This line for example, maybe you have something configured in your editor.

[ceri]

In D41625#948632, @carlavilla wrote:

Ok but use the one sentence per line please, no need to update the review, can be changed in the commit.
Apart from that ok from docs side :)

There is a fair bit that needs to be corrected in here.
Please hold off and I’ll send feedback this evening.

[fernape]

documentation/content/en/books/porters-handbook/special/_index.adoc

57

Yes, that's wrapping.

From https://sembr.org/

"A maximum line length of 80 characters is RECOMMENDED"

I always understood semantic breaking as "don't put two or more sentences in one line", not as "you should never break a single sentence in multiple lines" :-)

[ceri]

documentation/content/en/books/porters-handbook/special/_index.adoc

55

"Sometimes, port Makefiles can be really long"

56

"example", over instance

59

In cases like this, it can be convenient

64

s/in case/if/

70

typo of example

74

s/idiomatic/usual practice/

s/the port in several/the port into several/

74–75

"if" rather than "in case"

80–81

Not sure what this means - do you mean "the framework does not split the packaging list into multiple files automatically, as the logic involved may be complex"?

[fernape]

• Address ceri@ comments.

[fernape]

documentation/content/en/books/porters-handbook/special/_index.adoc

80–81

Yes, it wasn't clear.

Is it better now? It is just to mark the difference. The recognized Makefile.* files are included automagically. pkg-plist.* need to handled manually.
Something like

.if ${ARCH} == i386 
PLIST=pkg-plist.i386
...

[grahamperrin]

One sentence per line. Thanks.

[fernape]

• One sentence per line

[grahamperrin]

documentation/content/en/books/porters-handbook/special/_index.adoc

55

56

57

58

… alternatively,

In such cases, …

70

70

Selected where?

73

The preceding sentence described it as a file. No need to repeat the description for the same filename.

[fernape]

• Address feedback

[fernape]

In D41625#949381, @grahamperrin wrote:

One sentence per line. Thanks.

documentation/content/en/books/porters-handbook/special/_index.adoc

70

What do you mean?

[grahamperrin]

documentation/content/en/books/porters-handbook/special/_index.adoc

70

I mean, maybe /selected/ is not the ideal word.

[ceri]

documentation/content/en/books/porters-handbook/special/_index.adoc

80–81

Much clearer, thanks!

[fernape]

documentation/content/en/books/porters-handbook/special/_index.adoc

70

I don't know what other word to use, to be honest.
For flavored ports, you select a flavor. "Choose" might be an option, but I prefer the former.

[fernape]

Thank you all for the review.

@grahamperrin if you find a more suitable word to replace "select", please let me know.