git: 4c66431690 - main - phb porting-samplem: Use Asciidoc callouts instead of inline comments

The branch main has been updated by 0mp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=4c66431690160464837185f21e659942cd5fc3ff

commit 4c66431690160464837185f21e659942cd5fc3ff
Author:     Mateusz Piotrowski <[email protected]>
AuthorDate: 2025-07-23 17:21:30 +0000
Commit:     Mateusz Piotrowski <[email protected]>
CommitDate: 2025-07-23 17:22:45 +0000

    phb porting-samplem: Use Asciidoc callouts instead of inline comments
    
    While here, perform some basic clean-up and wordsmithing.
---
 .../porters-handbook/porting-samplem/_index.adoc   | 106 ++++++++++-----------
 1 file changed, 49 insertions(+), 57 deletions(-)

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 bc8d531397..d56cd68c99 100644
--- a/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
@@ -49,84 +49,54 @@ include::../../../../../shared/asciidoctor.adoc[]
 endif::[]
 
 Here is a sample [.filename]#Makefile# that can be used to create a new port.
-Make sure to remove all the extra comments (ones between brackets).
 
-The format shown is the recommended one for ordering variables, empty lines between sections, and so on.
+The format shown is the recommended one for crossref:order[, ordering] variables, empty lines between sections, and so on.
 This format is designed so that the most important information is easy to locate.
-We recommend using crossref:quick-porting[porting-portlint,portlint] to check the [.filename]#Makefile#.
+Refer to crossref:testing[, the chapter about testing] to learn more about tools for linting, formatting, and checking the [.filename]#Makefile#.
 
 [.programlisting]
 ....
-[section to describe the port itself and the master site - PORTNAME
- and PORTVERSION or the DISTVERSION* variables are always first,
- followed by CATEGORIES, and then MASTER_SITES, which can be followed
- by MASTER_SITE_SUBDIR.  PKGNAMEPREFIX and PKGNAMESUFFIX, if needed,
- will be after that.  Then comes DISTNAME, EXTRACT_SUFX and/or
- DISTFILES, and then EXTRACT_ONLY, as necessary.]
-PORTNAME=	xdvi
+PORTNAME=	xdvi <1>
 DISTVERSION=	18.2
 CATEGORIES=	print
-[do not forget the trailing slash ("/")!
- if not using MASTER_SITE_* macros]
-MASTER_SITES=	${MASTER_SITE_XCONTRIB}
+MASTER_SITES=	${MASTER_SITE_XCONTRIB} <2>
 MASTER_SITE_SUBDIR=	applications
 PKGNAMEPREFIX=	ja-
 DISTNAME=	xdvi-pl18
-[set this if the source is not in the standard ".tar.gz" form]
-EXTRACT_SUFX=	.tar.Z
+EXTRACT_SUFX=	.tar.Z <3>
 
-[section for distributed patches -- can be empty]
-PATCH_SITES=	ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCH_SITES=	ftp://ftp.sra.co.jp/pub/X11/japanese/ <4>
 PATCHFILES=	xdvi-18.patch1.gz xdvi-18.patch2.gz
-[If the distributed patches were not made relative to ${WRKSRC},
- this may need to be tweaked]
-PATCH_DIST_STRIP=	-p1
-
-[maintainer; *mandatory*!  This is the person who is volunteering to
- handle port updates, build breakages, and to whom a users can direct
- questions and bug reports.  To keep the quality of the Ports Collection
- as high as possible, we do not accept new ports that are assigned to
- "[email protected]".]
-MAINTAINER=	[email protected]
+PATCH_DIST_STRIP=	-p1 <5>
+
+MAINTAINER=	[email protected] <6>
 COMMENT=	DVI Previewer for the X Window System
 WWW=		http://xdvi.sourceforge.net/
 
-[license -- should not be empty]
-LICENSE=	BSD2CLAUSE
+LICENSE=	BSD2CLAUSE <7>
 LICENSE_FILE=	${WRKSRC}/LICENSE
 
-[dependencies -- can be empty]
-RUN_DEPENDS=	gs:print/ghostscript
-
-[If it requires GNU make, not /usr/bin/make, to build...]
-USES= gmake
-[If it is an X application and requires "xmkmf -a" to be run...]
-USES= imake
-
-[this section is for other standard bsd.port.mk variables that do not]
- belong to any of the above]
-[If it asks questions during configure, build, install...]
-IS_INTERACTIVE=	yes
-[If it extracts to a directory other than ${DISTNAME}...]
-WRKSRC=		${WRKDIR}/xdvi-new
-[If it requires a "configure" script generated by GNU autoconf to be run]
-GNU_CONFIGURE=	yes
-[et cetera.]
-
-[If it requires options, this section is for options]
+RUN_DEPENDS=	gs:print/ghostscript <8>
+
+USES=		gmake <9>
+
+<10>
+IS_INTERACTIVE=	yes <11>
+WRKSRC=		${WRKDIR}/xdvi-new <12>
+GNU_CONFIGURE=	yes <13>
+
+<14>
 OPTIONS_DEFINE=	DOCS EXAMPLES FOO
-OPTIONS_DEFAULT=	FOO
-[If options will change the files in plist]
-OPTIONS_SUB=yes
+OPTIONS_DEFAULT=FOO
+OPTIONS_SUB=	yes <15>
 
 FOO_DESC=		Enable foo support
-
 FOO_CONFIGURE_ENABLE=	foo
 
-[non-standard variables to be used in the rules below]
+<16>
 MY_FAVORITE_RESPONSE=	"yeah, right"
 
-[then the special rules, in the order they are called]
+<17>
 pre-fetch:
 	i go fetch something, yeah
 
@@ -136,7 +106,29 @@ post-patch:
 pre-install:
 	and then some more stuff before installing, wow
 
-[and then the epilogue]
-
-.include <bsd.port.mk>
+.include <bsd.port.mk> <18>
 ....
+
+<1> Section to describe the port itself and the master site -- `PORTNAME` and `PORTVERSION` or the `DISTVERSION*` variables are always first, followed by `CATEGORIES`, and then `MASTER_SITES`, which can be followed by `MASTER_SITE_SUBDIR`.
+`PKGNAMEPREFIX` and `PKGNAMESUFFIX`, if needed, will be after that.
+Then comes `DISTNAME`, `EXTRACT_SUFX` and/or `DISTFILES`, and then `EXTRACT_ONLY`, as necessary.
+<2> Do not forget the trailing slash (`/`) if not using `MASTER_SITE_*` macros.
+<3> Set this if the source is not in the standard ".tar.gz" form.
+<4> Section for distributed patches -- can be empty.
+<5> If the distributed patches were not made relative to `WRKSRC`, this may need to be tweaked.
+<6> Maintainer; *mandatory*!
+This is the person who is volunteering to handle port updates, build breakages, and to whom a users can direct questions and bug reports.
+To keep the quality of the Ports Collection as high as possible, we do not accept new ports that are assigned to "[email protected]".
+<7> License -- should not be empty.
+<8> Dependencies -- can be empty.
+<9> If the port requires GNU make instead of the default FreeBSD `make` (man:make[1]) to build.
+For example, some X applications require `xmkmf -a` to run, in which case the port would need `USES=imake`.
+<10> This section is for other standard [.filename]#bsd.port.mk# variables that do not belong to any of the above.
+<11> If the ports asks interactive questions during configure, build, install.
+<12> If it extracts to a directory other than `DISTNAME`.
+<13> If it requires a `configure` script generated by GNU autoconf to be run.
+<14> This section is for handling ports options.
+<15> Set `OPTIONS_SUB` if options will change the list of files in the crossref:plist[plist-sub, plist].
+<16> Non-standard variables to be used in the rules below.
+<17> Special rules, in the order they are called by the ports framework.
+<18> Finally, the epilogue.