git: 4c66431690 - main - phb porting-samplem: Use Asciidoc callouts instead of inline comments
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Wed, 23 Jul 2025 17:38:52 UTC
The branch main has been updated by 0mp:
URL: https://cgit.FreeBSD.org/doc/commit/?id=4c66431690160464837185f21e659942cd5fc3ff
commit 4c66431690160464837185f21e659942cd5fc3ff
Author: Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2025-07-23 17:21:30 +0000
Commit: Mateusz Piotrowski <0mp@FreeBSD.org>
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
- "ports@FreeBSD.org".]
-MAINTAINER= asami@FreeBSD.org
+PATCH_DIST_STRIP= -p1 <5>
+
+MAINTAINER= asami@FreeBSD.org <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 "ports@FreeBSD.org".
+<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.