From owner-freebsd-doc@FreeBSD.ORG Tue Jun 17 13:40:07 2003 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8571437B401 for ; Tue, 17 Jun 2003 13:40:07 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 378F943FBD for ; Tue, 17 Jun 2003 13:40:04 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h5HKe4Up003281 for ; Tue, 17 Jun 2003 13:40:04 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h5HKe4sn003280; Tue, 17 Jun 2003 13:40:04 -0700 (PDT) Resent-Date: Tue, 17 Jun 2003 13:40:04 -0700 (PDT) Resent-Message-Id: <200306172040.h5HKe4sn003280@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Mark Linimon Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id A22B337B401 for ; Tue, 17 Jun 2003 13:37:38 -0700 (PDT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id 459CF43FD7 for ; Tue, 17 Jun 2003 13:37:37 -0700 (PDT) (envelope-from linimon@lonesome.com) Received: from lonesome.lonesome.com (cs242746-11.austin.rr.com [24.27.46.11]) (using TLSv1 with cipher EDH-RSA-DES-CBC3-SHA (168/168 bits)) (No client certificate requested) by mail.soaustin.net (Postfix) with ESMTP id B320C140CD for ; Tue, 17 Jun 2003 15:37:34 -0500 (CDT) Received: from lonesome.lonesome.com (localhost.lonesome.com [127.0.0.1]) by lonesome.lonesome.com (8.12.9/8.12.3) with ESMTP id h5HKflNa027229 for ; Tue, 17 Jun 2003 15:41:47 -0500 (CDT) (envelope-from linimon@lonesome.lonesome.com) Received: (from linimon@localhost) by lonesome.lonesome.com (8.12.9/8.12.6/Submit) id h5HKfkPR027228; Tue, 17 Jun 2003 15:41:46 -0500 (CDT) (envelope-from linimon) Message-Id: <200306172041.h5HKfkPR027228@lonesome.lonesome.com> Date: Tue, 17 Jun 2003 15:41:46 -0500 (CDT) From: Mark Linimon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113.1 Subject: docs/53420: [patch] rework of parts of Porter's Handbook part 1 of 5: style fixes X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Jun 2003 20:40:07 -0000 >Number: 53420 >Category: docs >Synopsis: [patch] rework of parts of Porter's Handbook part 1 of 5: style fixes >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Tue Jun 17 13:40:03 PDT 2003 >Closed-Date: >Last-Modified: >Originator: Mark Linimon >Release: FreeBSD-4.7 >Organization: FreeBSD >Environment: System: FreeBSD lonesome.lonesome.com 4.7-STABLE FreeBSD 4.7-STABLE #0: Fri Nov 8 23:46:29 CST 2002 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386 >Description: The Porter's Handbook is insufficiently clear in some places, and needs expanding in others. As requested I have tried to break out the rework that I did into several pieces. This first piece fixes existing style bugs only. >How-To-Repeat: n/a >Fix: --- book.sgml.dist Sun May 11 18:41:11 2003 +++ book.sgml Mon May 12 20:51:50 2003 @@ -67,8 +67,8 @@ This file uses a non-standard tab setting. Emacs and Vim should recognize the setting on - loading the file. Both vi and - ex can be set to use the correct value by + loading the file. Both &man.vi.1; and + &man.ex.1; can be set to use the correct value by typing :set tabstop=4 once the file has been loaded. @@ -470,7 +470,7 @@ actions are done. For example, if you have a post-extract - target defined in your Makefile, and a file + target defined in your Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and the @@ -581,8 +581,8 @@ Patching In the preparation of the port, files that have been added or - changed can be picked up with a recursive diff for later feeding to - patch. Each set of patches you wish to apply should be collected + changed can be picked up with a recursive &man.diff.1; for later feeding to + &man.patch.1;. Each set of patches you wish to apply should be collected into a file named patch-* where * denotes the sequence in which the @@ -609,10 +609,10 @@ $RCS. Using the recurse () option to - diff to generate patches is fine, but please take + &man.diff.1; to generate patches is fine, but please take a look at the resulting patches to make sure you do not have any unnecessary junk in there. In particular, diffs between two backup - files, Makefiles when the port uses + files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should be deleted. If you had to edit configure.in and run @@ -643,7 +643,7 @@ Handling user input If your port requires user input to build, configure, or install, - then set IS_INTERACTIVE in your Makefile. This + then set IS_INTERACTIVE in your Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then @@ -661,7 +661,7 @@ Configuring the Makefile - Configuring the Makefile is pretty simple, and again we suggest + Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables @@ -669,7 +669,7 @@ read. Now, consider the following problems in sequence as you design - your new Makefile: + your new Makefile: The original source @@ -726,7 +726,7 @@ affects the content or structure of the derived package. - Examples of when PORTREVISION should be bumped: + Examples of when PORTREVISION should be bumped: @@ -736,7 +736,7 @@ - Changes to the port makefile to enable or disable + Changes to the port Makefile to enable or disable compile-time options in the package. @@ -808,7 +808,7 @@ enhancement, fix, or by virtue that the new package will actually work for them). If yes, the PORTREVISION should be bumped so that - automated tools (e.g. pkg_version) + automated tools (e.g. &man.pkg.version.1;) will highlight the fact that a new package is available. @@ -862,8 +862,8 @@ Example of <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> usage - The gtkmumble port, version 0.10, is committed to the - ports collection. + The gtkmumble port, version 0.10, is committed to the + ports collection: PORTNAME= gtkmumble PORTVERSION= 0.10 @@ -893,7 +893,7 @@ force the new package to be detected as newer. Since it is a new vendor release of the code, PORTREVISION is reset to 0 (or removed - from the makefile). + from the Makefile). PORTNAME= gtkmumble PORTVERSION= 0.2 @@ -916,8 +916,8 @@ If PORTEPOCH were reset to 0 with this upgrade, someone who had - installed the gtkmumble-0.10_1 package would not detect - the gtkmumble-0.3 package as newer, since + installed the gtkmumble-0.10_1 package would not detect + the gtkmumble-0.3 package as newer, since 3 is still numerically less than 10. @@ -939,7 +939,7 @@ hyphen (-) in PORTVERSION. Also, if the package name has the language- or the - compiled.specifics part, use + -compiled.specifics part, use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. @@ -985,7 +985,7 @@ should be lowercase. (The rest of the name can contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) - There is a tradition of naming Perl 5 modules by + There is a tradition of naming perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes @@ -1002,7 +1002,7 @@ the compiled-in defaults (the hyphen is optional). Examples are papersize and font units. - The compiled.specifics part + The -compiled.specifics part should be set in the PKGNAMESUFFIX variable. @@ -1180,7 +1180,7 @@ If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to - 1.0 (like the piewm example above). Otherwise, ask + 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (yyyy.mm.dd) as the version. @@ -1493,7 +1493,7 @@ perl5* - Ports that require perl version 5 to run. + Ports that require perl version 5 to run. @@ -1629,7 +1629,7 @@ windowmaker* Ports to support the WindowMaker window - manager + manager. @@ -2596,7 +2596,7 @@ This does not affect the MASTER_SITES you - define in your Makefile. + define in your Makefile. @@ -2665,7 +2665,7 @@ extract target and then from within the install target. Also, the name of the dependency is put into the package so that - pkg_add will automatically install it if it is + &man.pkg.add.1; will automatically install it if it is not on the user's system. @@ -2710,7 +2710,7 @@ The dependency is checked from within the install target. Also, the name of the dependency is put into the package so that - pkg_add will automatically install it if it is + &man.pkg.add.1; will automatically install it if it is not on the user's system. The target part can be omitted if it is the same as DEPENDS_TARGET. @@ -2814,9 +2814,9 @@ USE_PERL5 - The port requires Perl 5 to build and install. See + The port requires perl 5 to build and install. See for additional variables that - can be set relating to Perl. + can be set relating to perl. @@ -2888,8 +2888,8 @@ GNU autoconf to be run. Define USE_QT=yes if your port uses the latest qt toolkit. Use USE_PERL5=yes if your port requires version 5 - of the perl language. (The last is especially important since - some versions of FreeBSD have perl5 as part of the base system + of the perl language. (The last is especially important since + some versions of FreeBSD have perl5 as part of the base system while others do not.) @@ -2920,7 +2920,7 @@ BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract - will always descend to the JPEG port and extract it. + will always descend to the jpeg port and extract it. Do not use DEPENDS unless there is no other way the behavior you want can be accomplished. It will cause the @@ -3191,10 +3191,10 @@ - Using Perl + Using <literal>perl</literal> - Variables for ports that use Perl + Variables for ports that use <literal>perl</literal> @@ -3209,7 +3209,7 @@ USE_PERL5 - Says that the port uses Perl 5 to build and run. + Says that the port uses perl 5 to build and run. @@ -3219,28 +3219,28 @@ PERL_VERSION - The full version of Perl installed (e.g., + The full version of perl installed (e.g., 5.00503). PERL_VER - The short version of Perl installed (e.g., + The short version of perl installed (e.g., 5.005). PERL_LEVEL - The installed Perl version as an integer of the form MNNNPP + The installed perl version as an integer of the form MNNNPP (e.g., 500503). PERL_ARCH - Where Perl stores architecture dependent libraries. + Where perl stores architecture dependent libraries. Defaults to ${ARCH}-freebsd. @@ -3710,7 +3710,7 @@ <makevar>LIB_DEPENDS</makevar> - All port Makefiles are edited to remove minor numbers from + All port Makefiles are edited to remove minor numbers from LIB_DEPENDS, and also to have the regexp support removed. (E.g., foo\\.1\\.\\(33|40\\) becomes foo.2.) They will be matched using grep @@ -3741,7 +3741,7 @@ <literal>ldconfig</literal> - The ldconfig line in Makefiles should + The ldconfig line in Makefiles should read: ${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m .... @@ -3768,7 +3768,7 @@ make it easier for users to see what to do, but try to share as many files as possible between ports. Typically you only need a very short Makefile in all but one of the directories if you - use variables cleverly. In the sole Makefiles, + use variables cleverly. In the sole Makefile, you can use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX so @@ -3891,7 +3891,7 @@ If your port anchors its man tree somewhere other than PREFIX, you can use the MANPREFIX to set it. Also, if only manpages in - certain sections go in a non-standard place, such as some Perl modules + certain sections go in a non-standard place, such as some perl modules ports, you can set individual man paths using MANsectPREFIX (where sect is one of 1-9, @@ -3945,7 +3945,7 @@ <makevar>USE_MOTIF</makevar> If your port requires Motif, define this variable in the - Makefile. This will prevent people who do not own a copy of Motif + Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. @@ -4217,7 +4217,7 @@ Edit pkg-plist and add equivalent @exec statements and also @unexec for - pkg_delete. + &man.pkg.delete.1;. Index: pkg-plist =================================================================== @@ -4274,7 +4274,7 @@ If you need to display a message to the installer, you may place the message in pkg-message. This capability is often useful to display additional installation steps to be taken - after a pkg_add or to display licensing + after a &man.pkg.add.1; or to display licensing information. @@ -4290,10 +4290,10 @@ <filename>pkg-install</filename> If your port needs to execute commands when the binary package - is installed with pkg_add you can do this via the + is installed with &man.pkg.add.1; you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by - pkg_add. The first time as + &man.pkg.add.1;. The first time as ${SH} pkg-install ${PKGNAME} PRE-INSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-INSTALL. @@ -4321,10 +4321,10 @@ installation/deinstallation should proceed. The script will be run at installation time by - pkg_add as + &man.pkg.add.1; as pkg-req ${PKGNAME} INSTALL. At deinstallation time it will be run by - pkg_delete as + &man.pkg.delete.1; as pkg-req ${PKGNAME} DEINSTALL. @@ -4332,17 +4332,17 @@ Changing <filename>pkg-plist</filename> based on make variables - Some ports, particularly the p5- ports, need to change their + Some ports, particularly the p5- ports, need to change their pkg-plist depending on what options they are - configured with (or version of perl, in the case of p5- ports). To + configured with (or version of perl, in the case of p5- ports). To make this easy, any instances in the pkg-plist of %%OSREL%%, %%PERL_VER%%, and %%PERL_VERSION%% will be substituted for appropriately. The value of %%OSREL%% is the numeric revision of the operating system (e.g., 2.2.7). %%PERL_VERSION%% is - the full version number of perl (e.g., 5.00502) - and %%PERL_VER%% is the perl version number minus + the full version number of perl (e.g., 5.00502) + and %%PERL_VER%% is the perl version number minus the patchlevel (e.g., 5.005). If you need to make other substitutions, you can set the @@ -4477,7 +4477,7 @@ automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not use imake) - in the various scripts/Makefiles in the port to read + in the various scripts/Makefiles in the port to read PREFIX, as this variable is automatically passed down to every stage of the build and install processes. @@ -4505,7 +4505,7 @@ The variable PREFIX can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this - variable explicitly in the Makefiles. + variable explicitly in the Makefiles. Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if @@ -4521,7 +4521,7 @@ if this is an X port, instead of -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has - moved the whole `/usr/local' tree somewhere else. + moved the whole /usr/local tree somewhere else. @@ -4534,11 +4534,11 @@ testing of your commits. If you wish to use this service, all you need is a FreshPorts - account. If your registered email address is @FreeBSD.org, + account. If your registered email address is @FreeBSD.org, you'll see the opt-in link on the right hand side of the webpages. For those of you who already have a FreshPorts account, but are not - using your @FreeBSD.org email address, just change your email to - @FreeBSD.org, subscribe, then change it back again. + using your @FreeBSD.org email address, just change your email to + @FreeBSD.org, subscribe, then change it back again. @@ -5699,8 +5699,8 @@ You need to include either the - pre.mk/post.mk pair or - bsd.port.mk only; do not mix these two. + bsd.port.pre.mk/bsd.port.post.mk pair or + bsd.port.mk only; do not mix these two usages. bsd.port.pre.mk only defines a few @@ -5867,7 +5867,7 @@ (executables started internally), sbin (executables for superusers/managers), info (documentation for info browser) or share - (architecture independent files). See man &man.hier.7; for details, + (architecture independent files). See &man.hier.7; for details; the rules governing /usr pretty much apply to /usr/local too. The exception are ports @@ -5901,7 +5901,7 @@ @unexec rmdir %D/share/doc/gimp 2>/dev/null || true This will neither print any error messages nor cause - pkg_delete to exit abnormally even if + &man.pkg.delete.1; to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. @@ -6037,7 +6037,7 @@ PREFIX/etc, do not just install them and list them in pkg-plist. That will cause - pkg_delete to delete files carefully edited by + &man.pkg.delete.1; to delete files carefully edited by the user and a new installation to wipe them out. Instead, install sample files with a suffix @@ -6082,7 +6082,7 @@ Please use the correct make variable as each make variable conveys radically different meanings to both users, and to automated systems that parse - Makefiles. + Makefiles. >Release-Note: >Audit-Trail: >Unformatted: