Literal text for WWW variable

[makc]

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

[mat]

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.

[fuz]

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.

[adamw]

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]

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]

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]

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.