Page MenuHomeFreeBSD
Differential D53824

Literal text for WWW variable
Needs ReviewPublic
Actions

Authored by makc on Wed, Nov 19, 11:30 AM.
Tags
None
Referenced Files
F136998173: D53824.id166740.diff
Thu, Nov 20, 11:04 PM
F136997024: D53824.id166772.diff
Thu, Nov 20, 10:59 PM
F136996457: D53824.id.diff
Thu, Nov 20, 10:57 PM
F136994420: D53824.diff
Thu, Nov 20, 10:50 PM
Unknown Object (File)
Wed, Nov 19, 9:15 PM
Unknown Object (File)
Wed, Nov 19, 8:39 PM
Unknown Object (File)
Wed, Nov 19, 5:42 PM
Unknown Object (File)
Wed, Nov 19, 5:28 PM
View All 13 Files
Subscribers
adamw
danfe
fuz
mat
portmaster_BSDforge.com
Ports Committers

Details

Reviewers
salvadore
Summary

The WWW variable was a plain text URL before it has been moved to the Makefile. Suggest to use the literal text URL unless the WWW variable is provided by the ports framework.

Prompted by the discussion https://lists.freebsd.org/archives/dev-commits-ports-main/2025-November/170048.html

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

makc requested review of this revision.Wed, Nov 19, 11:30 AM
makc created this revision.
mat added a subscriber: mat.Wed, Nov 19, 12:16 PM

As the sentence says "should", it's an advice, which means, it's not enforcable, so, it's just more text that do not really add any no value.

documentation/content/en/books/porters-handbook/makefiles/_index.adoc
2615

While I disagree with this change, we document what should be done, not what should not be, so

Whenever the WWW variable is set in the [.filename]#Makefile# its value should be literal text.

vvd added a subscriber: vvd.Wed, Nov 19, 12:41 PM
vvd removed a subscriber: vvd.
fuz added a subscriber: fuz.Wed, Nov 19, 1:15 PM

I like this, removes a minor annoyance from working with some ports.

I am in general not a huge fan of using PORTNAME all over the place. It should only be used in places where the port would still work fine if PORTNAME is changed, not in every place where the string PORTNAME expands to appears. But that's another debate.

makc updated this revision to Diff 166772.Wed, Nov 19, 1:42 PM
makc marked an inline comment as done.
adamw added a subscriber: adamw.Wed, Nov 19, 2:34 PM
adamw added inline comments.
documentation/content/en/books/porters-handbook/makefiles/_index.adoc
2615

I'll be honest, if I came across this I would be unclear what "literal text" is trying to imply.

Perhaps "must be literal text and not include variables"?

portmaster_BSDforge.com added a subscriber: portmaster_BSDforge.com.Thu, Nov 20, 12:24 AM
portmaster_BSDforge.com added a comment.Thu, Nov 20, 12:33 AM

I was involved in the discussion on the mailing list and while I am a proponent of allowing the variable in the WWW.
In the end we're only ever talking about the difference of some half a dozen characters. So not a big deal either way.
If this should ever be documented as a MUST. I'd like to suggest the use of the terms:
"string literal" and "string variable" as opposed to "literal text". As both a variable AND a literal are still after all,
"literally text". :-)

adamw added a comment.Thu, Nov 20, 1:08 AM
In D53824#1229914, @portmaster_BSDforge.com wrote:

I'd like to suggest the use of the terms:
"string literal" and "string variable" as opposed to "literal text". As both a variable AND a literal are still after all,
"literally text". :-)

Thank you, that word choice is the correct answer!

danfe added a subscriber: danfe.Thu, Nov 20, 8:28 AM
danfe added inline comments.
documentation/content/en/books/porters-handbook/makefiles/_index.adoc
2615

Perhaps "must be literal text and not include variables"?

Something like that, yes. Maybe also mention that some popular terminal emulators or text editors allow to click and open embedded links directly which many people find handy.

Revision Contents
Changeset List

PathSize
documentation/
content/
en/
books/
porters-handbook/
makefiles/
3 lines

Diff 166772

View Options

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

Loading...