Document move of project website from port's pkg-descr to Makefile

[se]

Summary

The project website has been documented in the pkg-descr for a long time.
It has been suggested multiple times (see D2949 and D34979, with the latter review having been accepted).
This change moves the last parameter required to build the INDEX into the port Makefiles, allowing to speed-up generation of the INDEX.
Further advantages are that WWW becomes a field that can be searched for with portgrep, that defaults can be provided in infrastructure .mk files (as are, e.g., included via USES) and that the website URL is maintained in the port's Makefile together with the MASTER_SITE and other project information that might change over time.
In preparation of thmove of WWW to the ports' Makefiles an update has been committed to the main branch of the portfmt port, to add support of WWW to portedit, portfmt, and portclippy.
An update to portlint that checks for the existence and correct placement of WWW= in the Makefile is under development and will be submitted to the author of that tool.

The patch in this review documents the new WWW= macro that should be defined in each Makefile.
This text does not mention that defaults could be set in master Makefiles or .mk files in the ports system.

Suggestions for extensions or improvements of this patch are welcome.
Translations will be required - I could provide the German translation of the text when it is accepted.

Test Plan

Apply patch and create porter's handbook in all relevant formats.

[pauamma_gundo.com]

Also needs to be added to documentation/content/en/books/porters-handbook/order/_index.adoc

[salvadore]

Thanks @se for working on it.

Beside what @pauamma already noted, I think instructions in documentation/content/en/books/porters-handbook/quick-porting/ also need to be updated. There is also a reference about WWW being in pkg-descr in instructions for using Perl (documentation/content/en/books/porters-handbook/special).

[se]

The placement of the WWW line has been changed to immediately follow the COMMENT line.

The following files have been changed to document the new variable or to include it in examples:

• makefiles/_index.adoc
• order/_index.adoc
• plist/_index.adoc
• porting-samplem/_index.adoc
• quick-porting/_index.adoc
• special/_index.adoc

[carlavilla]

From the documentation side it’s ok.
Thanks for this addition :)

[salvadore]

Only a small thing about spaces you might want to double check. Looks good to me.

(I remind you that I am not a doc committer, so I cannot give any doc committer approval.)

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

822

Here and in the following lines you changed the spaces after = sign. Is it intended? Does it actually change the rendered text?

[pauamma_gundo.com]

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

2528

Tangent: when https works, as is the case for this port, should the porter's handbook encourage using it instead?

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

822

/usr/ports/benchmarks/hey/Makefile as of the last time I ran portsnap auto has \t there. I suspect pasting changed them to spaces.

841

While here

[se]

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

2528

Yes, I'll update the patch to suggest to use https URLs, where possible.

I have tested the ~6500 distinct http:// URLs currently present in pkg-descr files, some 3000 can be replaced by https URLs that return identical information.

I'm currently thinking about whether the URLs should be patched into the pkg-descr files before moving the WWW data into the Makefile, or whether that should be a follow-up commit.

Applying such a change to the pkg-descr files first, is a bit more effort (since not all are well-formed), but that would allow to merge them to 2022Q3, for example, if the port is touched for other reasons.

But I tend to keeping the URLs unchanged in the initial commit (i.e. move them unchanged, except for malformed URLs).
A second step could be a clean-up of URLs in the Makefiles:

• use https instead of http where possible
• detect stale URLs (there are quite a lot!) and try to replace them with valid ones

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

822

The Makefile examples used a mix of spaces and tabs before I touched them.

I suggest to separate content changes from white-space changes.

AFAICT, the examples that use tabs are not rendered nicely, while consistently using blank characters gives good results. But I plan to use the same type of indentation (blank vs. tab) as is used in the COMMENT line above the inserted WWW line.

841

I'd rather not mix changes to unrelated content with the changes that introduce WWW= in the Makefiles.

But I can apply this change in a separate commit.

[carlavilla]

Go ahead, we can improve this in further commits :)
Commit the changes marked as approved by me.

[se]

I had planned to just document the move of the URL from the pkg-descr file to the Makefile.
The new text requests use of HTTPS over HTTP and to add a slash "/" at the end of URLs that point at a host or directory.

After noticing the many URLs in examples and references that do not match these two points, I have decided to provide a patch for these URLs, too.

White space has been used inconsistently in the examples (blanks vs. tabs) and I have added the WWW= examples in the style used in the respective example section. A white space clean-up should be performed in a follow-up commit.

If requested, this patch-set could be split in 2 parts: text changes that describe the move of the URL vs. changes to existing URLs that did not follow the ruies.

Even when accepted, I do not plan to commit these changes immediately, since the pre-requisite changes of portlint and portfmt need to be committed by the respective maintainers, first.