porters-handbook: document move of WWW from pkg-descr to Makefile

Review D36434 will add support for a WWW macro in the ports' Makefiles
instead of at the end of the pkg-descr files to the ports framework.

This will make the WWW entries accessible to more tools (e.g. portgrep)
and will make it easier to maintain them (e.g. to find stale URLs).

Adding WWW: lines at the end of pkg-descr files is deprecated and will
be warned about by a forthcoming commit to portlint.

Follow-up commits will update all ports to conform with this new
style.

Approved by:		rene, carlavilla (earlier version)
Differential Revision:	https://reviews.freebsd.org/D36369

5 files changed, 45 insertions, 17 deletions

diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index 10a76f01da..005eb99dfb 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -1145,6 +1145,7 @@ DISTNAME=	${PORTNAME}-${ISCVERSION}
 
 MAINTAINER=	mat@FreeBSD.org
 COMMENT=	BIND DNS suite with updated DNSSEC and DNS64
+WWW=		https://www.isc.org/bind/
 
 LICENSE=	ISCL
 
@@ -2515,6 +2516,34 @@ COMMENT=	Cat chasing a mouse all over the screen
 
 The COMMENT variable immediately follows the MAINTAINER variable in the [.filename]#Makefile#.
 
+[[makefile-www]]
+== Project website
+
+Each port should point to a website that provides more information about the software.
+
+Whenever possible, this should be the official project website maintained by the developers of the software.
+
+[.programlisting]
+....
+WWW=		https://ffmpeg.org/
+....
+
+But it can also be a directory or resource in the source code repository:
+
+[.programlisting]
+....
+WWW=		https://sourceforge.net/projects/mpd/
+....
+
+The WWW variable immediately follows the COMMENT variable in the [.filename]#Makefile#.
+
+If the same content can be accessed via HTTP and HTTPS, the URL starting with `https://` shall be used.
+If the URI is the root of the website or directory, it must be terminated with a slash.
+
+This information used to be placed into the last line of the [.filename]#pkg-descr# file.
+It has been moved into the Makefile for easier maintenance and processing.
+Having a `WWW:` line at the end of the [.filename]#pkg-descr# file is deprecated.
+
 [[licenses]]
 == Licenses
 
diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
index aa027f16c7..08f90bea8c 100644
--- a/documentation/content/en/books/porters-handbook/plist/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
@@ -248,6 +248,7 @@ PKGNAMEPREFIX=	p5-
 
 MAINTAINER=	perl@FreeBSD.org
 COMMENT=	Building machine
+WWW=		https://search.cpan.org/dist/Machine-Build
 
 USES=		perl5
 USE_PERL5=	configure
diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
index 2a247922c2..8a67e9be99 100644
--- a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
@@ -88,6 +88,7 @@ PATCH_DIST_STRIP=	-p1
  "ports@FreeBSD.org".]
 MAINTAINER=	asami@FreeBSD.org
 COMMENT=	DVI Previewer for the X Window System
+WWW=		http://xdvi.sourceforge.net/
 
 [license -- should not be empty]
 LICENSE=	BSD2CLAUSE
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
index 18cd48110c..b296b2bdcd 100644
--- a/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
@@ -85,6 +85,7 @@ MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
 
 MAINTAINER=	youremail@example.com
 COMMENT=	Cat chasing a mouse all over the screen
+WWW=		http://www.daidouji.com/oneko/
 
 .include <bsd.port.mk>
 ....
@@ -118,27 +119,11 @@ On the other hand, the content of [.filename]#pkg-descr# must be longer than the
 A well-written [.filename]#pkg-descr# describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has.
 Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.
 
-Include a URL to the official WWW homepage.
-Prepend _one_ of the websites (pick the most common one) with `WWW:` (followed by single space) so that automated tools will work correctly.
-If the URI is the root of the website or directory, it must be terminated with a slash.
-
 [NOTE]
 ====
-If the listed webpage for a port is not available, try to search the Internet first to see if the official site moved, was renamed, or is hosted elsewhere.
+The URL that used to be included as the last line of the [.filename]#pkg-descr# file has been moved to the [.filename]#Makefile#.
 ====
 
-This example shows how [.filename]#pkg-descr# looks:
-
-[.programlisting]
-....
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-WWW: http://www.oneko.org/
-....
-
 [[porting-pkg-plist]]
 === [.filename]#pkg-plist#
 
diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index 369632c78b..3a76c90467 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -607,6 +607,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	tobik@FreeBSD.org
 COMMENT=	Display statistics about your code
+WWW=		https://github.com/XAMPPRocky/tokei/
 
 USES=		cargo
 USE_GITHUB=	yes
@@ -651,6 +652,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	tobik@FreeBSD.org
 COMMENT=	Display statistics about your code
+WWW=		https://github.com/XAMPPRocky/tokei/
 
 USES=		cargo
 USE_GITHUB=	yes
@@ -821,6 +823,7 @@ CATEGORIES=     benchmarks
 
 MAINTAINER=     dmgk@FreeBSD.org
 COMMENT=        Tiny program that sends some load to a web application
+WWW=            https://github.com/rakyll/hey/
 
 LICENSE=        APACHE20
 LICENSE_FILE=   ${WRKSRC}/LICENSE
@@ -847,6 +850,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	tobik@FreeBSD.org
 COMMENT=	Remote repository management made easy
+WWW=		https://github.com/x-motemen/ghq/
 
 USES=		go:modules
 USE_GITHUB=	yes
@@ -896,6 +900,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	tobik@FreeBSD.org
 COMMENT=	Remote repository management made easy
+WWW=		https://github.com/x-motemen/ghq/
 
 USES=		go:modules
 USE_GITHUB=	yes
@@ -976,6 +981,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	haskell@FreeBSD.org
 COMMENT=	Shell script analysis tool
+WWW=		https://www.shellcheck.net/
 
 USES=		cabal
 
@@ -1597,6 +1603,7 @@ MASTER_SITES=	GNOME
 
 MAINTAINER=	kwm@FreeBSD.org
 COMMENT=	Interactive tool for performing search and replace operations
+WWW=		http://regexxer.sourceforge.net/
 
 USES=		gettext gmake localbase:ldflags pathfix pkgconfig tar:xz
 GNU_CONFIGURE=	yes
@@ -3399,6 +3406,7 @@ CATEGORIES=	devel www pear
 
 MAINTAINER=	example@domain.com
 COMMENT=	PEAR Date and Time Zone Classes
+WWW=		https://pear.php.net/package/Date/
 
 USES=	pear
 
@@ -3446,6 +3454,7 @@ CATEGORIES=	devel www pear
 
 MAINTAINER=	horde@FreeBSD.org
 COMMENT=	Horde Core Framework libraries
+WWW=		https://pear.horde.org/
 
 OPTIONS_DEFINE=	KOLAB SOCKETS
 KOLAB_DESC=	Enable Kolab server support
@@ -3570,6 +3579,7 @@ CATEGORIES=	devel
 
 MAINTAINER=	john@doe.tld
 COMMENT=	Python sample module
+WWW=		https://pypi.org/project/sample/
 
 RUN_DEPENDS=	${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR}
 
@@ -4228,6 +4238,7 @@ CATEGORIES=	whatever
 
 MAINTAINER=	john@doe.tld
 COMMENT=	Sample
+WWW=		https://github.com/lua_sample/sample/
 
 RUN_DEPENDS=	${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR}
 
@@ -4251,6 +4262,7 @@ PKGNAMEPREFIX=	${LUA_PKGNAMEPREFIX}
 
 MAINTAINER=	john@doe.tld
 COMMENT=	Sample
+WWW=		https://github.com/lua_sample/sample/
 
 USES=		lua:module