From nobody Wed Jul 23 17:38:52 2025 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bnLwD6PPzz62ptx for ; Wed, 23 Jul 2025 17:38:52 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bnLwD2pffz3KLp; Wed, 23 Jul 2025 17:38:52 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753292332; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=n71LcNTQuKMVBF8f95MzIfRRRuZ3/a32U3SifvoHrHk=; b=jpCI0+eLgbApUeHx/+99pwAbrJP9Lzyw8LHudrRHyAjzlKRK4Pb5avoCxMQEztioKElQy5 bC4i1i8GLoxbHzFYKokqwXILikq0Up9bKf3ccz5fjvbMAXdHKE5g4f8Fp3Uy0Tn25b9yA7 H8qhAGP3jWkrRouxvNrCihvYddbCZ/2z7XpuWc3KhdvPHWCfja37jmTYkMG/hoFi0OskQe rHuN7Ih2qfi4Kptp62mW/itrBhskhNeJvAp5eaeEwGdMyS0xl8nkvzQMTo5roOq3o6epyR qE5DxGuEk+UXcvuZkcPpqqq0I9cca+3zju8z0j3E8vZosIqkFpZLaKpiSEC53A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753292332; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=n71LcNTQuKMVBF8f95MzIfRRRuZ3/a32U3SifvoHrHk=; b=I/rUFzLycKV/ZiMOeg6t5BJmh2R25IABGjP9QL89GheHix/KBSTpmbJ4uUS2xh35Th6yX8 +Av6Q7IwwNWjKrfrSLxUkZ7b1OR6JDcNtX6vfUsbWW6OWkx5F1bNkL6krlgSwaedWKiq5/ pmWSf5wTjDVmqRrN4+Pvf67Oh24H0KkH9II5D8HruRywyZ+gtT310OsT2rF815uobL0E4a 8ORXvlKcBMrIrnT3ZT3zJi8A14sSPXeLPYs//uZPJQIW8V53Zx4QBWZ6LCd796z4NMzZ8B 4T+a7p6lEaARi0QMhIMHrReOiX7aRh4ACKTpsIyHw+387mU0Vl6YxYQod363uA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1753292332; a=rsa-sha256; cv=none; b=XZOEtsT8sZwpSUyi1+qOtO9wYTiLzZleTpqfAAMw4aIPnNzlS+aesVoPtSfEngKrrSIH0l 9J9Wy2YwF0ybUqyuvotwC6ims4UPMZnMlP3LXPsM7uHwdZSa5rOrg/g9POLmNzeCFyi6pk CpUPw3uXZP1egkkaCgnksj2H9/xNPAecZKqx+gczuKCXNZHSOvJkmlUF1FlqpshqnA815x YQ51U3zayZm57fT3J8Ga7gB2SfjcpbDK7jtPgd+/wPSxStr9MEJEaFQakL5JdcVGrMh1fA 58AMkOMCVEQHTsbnH76W9QZIM3GRkZnX1/f/5RsgItUjOZ3DJxB4iqlrEDa8VQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bnLwD24BZz7Dw; Wed, 23 Jul 2025 17:38:52 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56NHcqFQ091917; Wed, 23 Jul 2025 17:38:52 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56NHcq9K091914; Wed, 23 Jul 2025 17:38:52 GMT (envelope-from git) Date: Wed, 23 Jul 2025 17:38:52 GMT Message-Id: <202507231738.56NHcq9K091914@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: 4c66431690 - main - phb porting-samplem: Use Asciidoc callouts instead of inline comments List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 4c66431690160464837185f21e659942cd5fc3ff Auto-Submitted: auto-generated 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 +.include <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.