D653.id1638.diff
No OneTemporary
Actions

Size

72 KB

Referenced Files

None

Subscribers

None

D653.id1638.diff
View Options

	Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
	===================================================================
	--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
	+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
	@@ -10,16 +10,15 @@

	<title>Special Considerations</title>

	- <para>There are some more things you have to take into account
	- when you create a port. This section explains the most common
	- of those.</para>
	+ <para>This section explains the most common things to consider when
	+ creating a port.</para>

	<sect1 xml:id="staging">
	<title>Staging</title>

	<para><filename>bsd.port.mk</filename> expects ports to work
	with a <quote>stage directory</quote>. This means that a port
	- should not install files directly to the regular destination
	+ must not install files directly to the regular destination
	directories (that is, under <varname>PREFIX</varname>, for
	example) but instead into a separate directory from which the
	package is then built. In many cases, this does not require
	@@ -42,7 +41,7 @@

	<note>
	<para>The vast majority of ports do not <emphasis>really
	- need</emphasis> to be root. You can mostly avoid it by
	+ need</emphasis> to be root. It can mostly be avoided by
	using <link
	linkend="uses-uidfix"><literal>USES=uidfix</literal></link>,
	and from time to time by slightly patching the port's
	@@ -50,7 +49,7 @@
	</note>

	<para>Meta ports, or ports that do not install files themselves
	- but only depend on other ports, should avoid needlessly
	+ but only depend on other ports, must avoid needlessly
	extracting the &man.mtree.8; to the stage directory. This is
	the basic directory layout of the package, and these empty
	directories will be seen as orphans. To prevent
	@@ -58,8 +57,8 @@

	<programlisting>NO_MTREE= yes</programlisting>

	- <para>Staging is enabled by prepending the
	- <varname>STAGEDIR</varname> variable to paths used in the
	+ <para>Staging is enabled by prepending
	+ <varname>STAGEDIR</varname> to paths used in the
	<buildtarget>pre-install</buildtarget>,
	<buildtarget>do-install</buildtarget>, and
	<buildtarget>post-install</buildtarget> targets (see the
	@@ -72,21 +71,21 @@
	absolute paths whenever possible.</para>

	<para>When creating a symlink, <varname>STAGEDIR</varname>
	- should be prepended to the target path only. For
	+ is prepended to the target path only. For
	example:</para>

	- <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting>
	+ <programlisting>${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>

	<para>The source path
	- <filename>${PREFIX}/lib/libfoo.so.42</filename> looks fine but
	+ <filename>${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable></filename> looks fine but
	could, in fact, be incorrect. Absolute paths can point to a
	wrong location, like when a remote file system has been
	mounted with <acronym>NFS</acronym> under a non-root mount
	point. Relative paths are less fragile, and often much
	shorter.</para>

	- <para>Ports that install kernel modules must prepend the
	- <varname>STAGEDIR</varname> variable to
	+ <para>Ports that install kernel modules must prepend
	+ <varname>STAGEDIR</varname> to
	their destination, by default
	<filename>/boot/modules</filename>.</para>
	</sect1>
	@@ -106,7 +105,7 @@
	distribution file. The second approach seems easier at
	first, but there are some serious drawbacks:</para>

	- <para>The following list is loosely based on the <link
	+ <para>This list is loosely based on the <link
	xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link>
	and <link
	xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>
	@@ -220,7 +219,7 @@
	port. If such a port does not exist yet, consider creating
	it.</para>

	- <para>Bundled libraries should only be used if upstream has a
	+ <para>Only use bundled libraries if the upstream has a
	good track record on security and using unbundled versions
	leads to overly complex patches.</para>
	</sect2>
	@@ -229,7 +228,7 @@
	<sect1 xml:id="porting-shlibs">
	<title>Shared Libraries</title>

	- <para>If your port installs one or more shared libraries, define
	+ <para>If the port installs one or more shared libraries, define
	a <varname>USE_LDCONFIG</varname> make variable, which will
	instruct a <filename>bsd.port.mk</filename> to run
	<literal>&dollar;{LDCONFIG} -m</literal> on the directory
	@@ -239,21 +238,21 @@
	into the shared library cache. This variable, when defined,
	will also facilitate addition of an appropriate
	<literal>@exec /sbin/ldconfig -m</literal> and
	- <literal>@unexec /sbin/ldconfig -R</literal> pair into your
	- <filename>pkg-plist</filename> file, so that a user who
	+ <literal>@unexec /sbin/ldconfig -R</literal> pair into
	+ <filename>pkg-plist</filename>, so that a user who
	installed the package can start using the shared library
	immediately and de-installation will not cause the system to
	still believe the library is there.</para>

	<programlisting>USE_LDCONFIG= yes</programlisting>

	- <para>If you need, you can override the default directory by
	- setting the <varname>USE_LDCONFIG</varname> value to a list of
	+ <para>The default directory can be overridden by
	+ setting <varname>USE_LDCONFIG</varname> to a list of
	directories into which shared libraries are to be installed.
	- For example if your port installs shared libraries into
	+ For example, if the port installs shared libraries into
	<filename>PREFIX/lib/foo</filename> and
	<filename>PREFIX/lib/bar</filename>
	- directories you could use the following in your
	+ use this in
	<filename>Makefile</filename>:</para>

	<programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
	@@ -270,14 +269,14 @@
	<para>When installing 32-bit libraries on 64-bit system, use
	<varname>USE_LDCONFIG32</varname> instead.</para>

	- <para>If the software you are porting uses <link
	+ <para>If the software uses <link
	linkend="using-autotools">autotools</link>, and specifically
	- <command>libtool</command>, you should add <link
	+ <command>libtool</command>, add <link
	linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para>

	<para>When the major library version number increments in the
	update to the new port version, all other ports that link to
	- the affected library should have their
	+ the affected library must have their
	<varname>PORTREVISION</varname> incremented, to force
	recompilation with the new library version.</para>
	</sect1>
	@@ -291,7 +290,7 @@
	profit, and so on.</para>

	<important>
	- <para>It is your responsibility as a porter to read the
	+ <para>It is the responsibility of a porter to read the
	licensing terms of the software and make sure that the
	&os; project will not be held accountable for violating
	them by redistributing the source or compiled binaries
	@@ -300,7 +299,7 @@
	</important>

	<para>In situations like this, the variables described in the
	- following sections can be set.</para>
	+ next sections can be set.</para>

	<sect2 xml:id="porting-restrictions-no_package">
	<title><varname>NO_PACKAGE</varname></title>
	@@ -316,15 +315,16 @@
	on a CD-ROM (or similar media) unless
	<varname>NO_CDROM</varname> is set as well.</para>

	- <para><varname>NO_PACKAGE</varname> should also be used if the
	+ <para>If the
	binary package is not generally useful, and the application
	- should always be compiled from the source code. For
	+ must always be compiled from the source code, use
	+ <varname>NO_PACKAGE</varname>. For
	example, if the application has configuration information
	- that is site specific hard coded in to it at compile time,
	+ that is site specific hard coded into it at compile time,
	set <varname>NO_PACKAGE</varname>.</para>

	- <para><varname>NO_PACKAGE</varname> should be set to a string
	- describing the reason why the package should not be
	+ <para>Set <varname>NO_PACKAGE</varname> to a string
	+ describing the reason why the package cannot be
	generated.</para>
	</sect2>

	@@ -343,9 +343,9 @@
	<varname>DISTFILES</varname> will be available, and only via
	FTP/HTTP.</para>

	- <para><varname>NO_CDROM</varname> should be set to a string
	+ <para>Set <varname>NO_CDROM</varname> to a string
	describing the reason why the port cannot be redistributed
	- on CD-ROM. For instance, this should be used if the port's
	+ on CD-ROM. For instance, use this if the port's
	license is for <quote>non-commercial</quote> use
	only.</para>
	</sect2>
	@@ -353,13 +353,13 @@
	<sect2 xml:id="porting-restrictions-nofetchfiles">
	<title><varname>NOFETCHFILES</varname></title>

	- <para>Files defined in the <varname>NOFETCHFILES</varname>
	- variable are not fetchable from any of the
	+ <para>Files defined in <varname>NOFETCHFILES</varname>
	+ are not fetchable from any of
	<varname>MASTER_SITES</varname>. An example of such a file
	is when the file is supplied on CD-ROM by the vendor.</para>

	<para>Tools which check for the availability of these files
	- on the <varname>MASTER_SITES</varname> should ignore these
	+ on <varname>MASTER_SITES</varname> have to ignore these
	files and not report about them.</para>
	</sect2>

	@@ -371,12 +371,12 @@
	<varname>DISTFILES</varname> nor distributing the binary
	package in any way.</para>

	- <para><varname>NO_CDROM</varname> or
	- <varname>NO_PACKAGE</varname> should not be set along with
	- <varname>RESTRICTED</varname> since the latter variable
	+ <para>Do not set <varname>NO_CDROM</varname> or
	+ <varname>NO_PACKAGE</varname> along with
	+ <varname>RESTRICTED</varname>, since the latter variable
	implies the former ones.</para>

	- <para><varname>RESTRICTED</varname> should be set to a string
	+ <para>Set <varname>RESTRICTED</varname> to a string
	describing the reason why the port cannot be redistributed.
	Typically, this indicates that the port contains proprietary
	software and that the user will need to manually download
	@@ -400,10 +400,10 @@
	<title><varname>LEGAL_TEXT</varname></title>

	<para>If the port has legal concerns not addressed by the
	- above variables, the variable <varname>LEGAL_TEXT</varname>
	- should be set to a string explaining the concern. For
	+ above variables, set <varname>LEGAL_TEXT</varname>
	+ to a string explaining the concern. For
	example, if special permission was obtained for &os; to
	- redistribute the binary, this variable should indicate
	+ redistribute the binary, this variable must indicate
	so.</para>
	</sect2>

	@@ -482,8 +482,8 @@
	implementation is listed in <literal>USES</literal>, the
	variables <varname>GMAKE</varname> (for the
	<acronym>GNU</acronym> version) or <varname>FMAKE</varname>
	- (for the legacy &os; version) are available. Most ports
	- should only use <varname>MAKE_CMD</varname> within the
	+ (for the legacy &os; version) are available.
	+ Only use <varname>MAKE_CMD</varname> within the
	application <filename>Makefile</filename>s in
	<varname>WRKSRC</varname> to call the
	<command>make</command> implementation expected by the
	@@ -497,10 +497,10 @@
	linkend="uses-imake"><literal>USES=imake</literal></link>
	section of <xref linkend="uses"/> for more details.</para>

	- <para>If your port's source <filename>Makefile</filename> has
	- something else than <buildtarget>all</buildtarget> as the
	+ <para>If the port's source <filename>Makefile</filename> has
	+ something other than <buildtarget>all</buildtarget> as the
	main build target, set <varname>ALL_TARGET</varname>
	- accordingly. Same goes for
	+ accordingly. The same goes for
	<buildtarget>install</buildtarget> and
	<varname>INSTALL_TARGET</varname>.</para>
	</sect2>
	@@ -508,10 +508,10 @@
	<sect2 xml:id="using-configure">
	<title><command>configure</command> Script</title>

	- <para>If your port uses the <command>configure</command>
	- script to generate <filename>Makefile</filename> files from
	- <filename>Makefile.in</filename> files, set
	- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
	+ <para>If the port uses the <command>configure</command>
	+ script to generate <filename>Makefile</filename> from
	+ <filename>Makefile.in</filename>, set
	+ <literal>GNU_CONFIGURE=yes</literal>. To give
	extra arguments to the <command>configure</command> script
	(the default argument is <literal>--prefix=&dollar;{PREFIX}
	--infodir=&dollar;{PREFIX}/&dollar;{INFO_PATH}
	@@ -519,7 +519,7 @@
	--build=&dollar;{CONFIGURE_TARGET}</literal>), set those
	extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
	environment variables can be passed using
	- <varname>CONFIGURE_ENV</varname> variable.</para>
	+ <varname>CONFIGURE_ENV</varname>.</para>

	<table frame="none" xml:id="using-configure-variables">
	<title>Variables for Ports That Use
	@@ -624,8 +624,8 @@
	</table>

	<table frame="none" xml:id="using-cmake-user-variables">
	- <title>Variables the Users can define for
	- <command>cmake</command> builds</title>
	+ <title>Variables the Users Can Define for
	+ <command>cmake</command> Builds</title>

	<tgroup cols="2">
	<thead>
	@@ -653,7 +653,7 @@
	</tgroup>
	</table>

	- <para><application>CMake</application> supports the following
	+ <para><application>CMake</application> supports these
	build profiles: <literal>Debug</literal>,
	<literal>Release</literal>,
	<literal>RelWithDebInfo</literal> and
	@@ -664,14 +664,14 @@
	<varname>CFLAGS</varname> to <literal>-O2 -g</literal> and
	<literal>-Os -DNDEBUG</literal> correspondingly. The
	lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is
	- exported to the <varname>PLIST_SUB</varname> and should be
	- used if port installs <literal>*.cmake</literal> files
	+ exported to <varname>PLIST_SUB</varname> and must be
	+ used if the port installs <filename><replaceable>*</replaceable>.cmake</filename>
	depending on the build type (see
	<package role="port">deskutils/strigi</package> for an
	example). Please note that some projects may define their
	own build profiles and/or force particular build type by
	setting <literal>CMAKE_BUILD_TYPE</literal> in
	- <filename>CMakeLists.txt </filename> files. In order to
	+ <filename>CMakeLists.txt</filename>. To
	make a port for such a project respect
	<varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>,
	the <literal>CMAKE_BUILD_TYPE</literal> definitions must be
	@@ -692,7 +692,7 @@
	<example xml:id="using-cmake-example">
	<title><literal>USES= cmake</literal> Example</title>

	- <para>The following snippet demonstrates the use of
	+ <para>This snippet demonstrates the use of
	<application>CMake</application> for a port.
	<varname>CMAKE_SOURCE_PATH</varname> is not usually
	required, but can be set when the sources are not located
	@@ -707,7 +707,7 @@
	<sect2 xml:id="using-scons">
	<title>Using <command>scons</command></title>

	- <para>If your port uses <application>SCons</application>,
	+ <para>If the port uses <application>SCons</application>,
	define <literal>USE_SCONS=yes</literal>.</para>

	<table frame="none" xml:id="using-scons-variables">
	@@ -753,7 +753,7 @@
	<para>To make third party <filename>SConstruct</filename>
	respect everything that is passed to SCons in
	<varname>SCONS_ENV</varname> (that is, most importantly,
	- <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the
	+ <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch
	<filename>SConstruct</filename> so build
	<literal>Environment</literal> is constructed like
	this:</para>
	@@ -842,9 +842,9 @@
	<command>autoheader</command></title>

	<para>Some ports do not contain a configure script, but do
	- contain an autoconf template in the
	- <filename>configure.ac</filename> file. You can use the
	- following assignments to let <command>autoconf</command>
	+ contain an autoconf template in
	+ <filename>configure.ac</filename>. Use these
	+ assignments to let <command>autoconf</command>
	create the configure script, and also have
	<command>autoheader</command> create template headers for
	use by the configure script.</para>
	@@ -872,14 +872,14 @@
	<command>aclocal</command></title>

	<para>Some packages only contain
	- <filename>Makefile.am</filename> files. These have to be
	- converted into <filename>Makefile.in</filename> files using
	+ <filename>Makefile.am</filename>. These have to be
	+ converted into <filename>Makefile.in</filename> using
	<command>automake</command>, and the further processed by
	<command>configure</command> to generate an actual
	<filename>Makefile</filename>.</para>

	<para>Similarly, packages occasionally do not ship with
	- included <filename>aclocal.m4</filename> files, again
	+ an included <filename>aclocal.m4</filename>, again
	required to build the software. This can be achieved with
	<command>aclocal</command>, which scans
	<filename>configure.ac</filename> or
	@@ -914,8 +914,8 @@
	<sect2 xml:id="using-gettext-basic">
	<title>Basic Usage</title>

	- <para>If your port requires <literal>gettext</literal>, set
	- <literal>USES= gettext</literal>, and your port will inherit
	+ <para>If the port requires <literal>gettext</literal>, set
	+ <literal>USES= gettext</literal>, and the port will inherit
	a dependency on <filename>libintl.so</filename> from
	<package role="port">devel/gettext</package>. Other
	values for <literal>gettext</literal> usage are listed in
	@@ -945,13 +945,13 @@
	<sect2 xml:id="using-gettext-optional">
	<title>Optional Usage</title>

	- <para>Some software products allow for disabling NLS, e.g.,
	+ <para>Some software products allow for disabling <acronym>NLS</acronym>. For example,
	through passing <option>--disable-nls</option> to
	- <command>configure</command>. In that case, your port
	- should use <literal>gettext</literal> conditionally,
	- depending on the status of the <varname>NLS</varname>
	- option. For ports of low to medium complexity, you can rely
	- on the following idiom:</para>
	+ <command>configure</command>. In that case, the port
	+ must use <literal>gettext</literal> conditionally,
	+ depending on the status of the <literal>NLS</literal>
	+ option. For ports of low to medium complexity, use
	+ this idiom:</para>

	<programlisting>GNU_CONFIGURE= yes

	@@ -981,7 +981,7 @@

	.include <bsd.port.mk></programlisting>

	- <para>The next item on your to-do list is to arrange so that
	+ <para>The next item on the to-do list is to arrange so that
	the message catalog files are included in the packing list
	conditionally. The <filename>Makefile</filename> part of
	this task is already provided by the idiom. It is explained
	@@ -994,7 +994,7 @@
	Consequently, the lines prefixed by
	<literal>%%NLS%%</literal> will become mere comments in the
	final packing list if NLS is off; otherwise the prefix will
	- be just left out. All you need to do now is insert
	+ be just left out. Then insert
	<literal>%%NLS%%</literal> before each path to a message
	catalog file in <filename>pkg-plist</filename>. For
	example:</para>
	@@ -1002,8 +1002,8 @@
	<programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
	%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>

	- <para>In high complexity cases, you may need to use more
	- advanced techniques than the recipe given here, such as
	+ <para>In high complexity cases, more advanced techniques
	+ may be needed, such as
	<link linkend="plist-dynamic">dynamic packing list
	generation</link>.</para>
	</sect2>
	@@ -1015,7 +1015,7 @@
	catalog files. The target directories for them, which
	reside under
	<filename>LOCALBASE/share/locale</filename>,
	- should rarely be created and removed by a port. The most
	+ must not be created and removed by a port. The most
	popular languages have their respective directories listed
	in
	<filename>PORTSDIR/Templates/BSD.local.dist</filename>.
	@@ -1031,7 +1031,7 @@
	<title>Using <application>Perl</application></title>

	<para>If <varname>MASTER_SITES</varname> is set to
	- <literal>CPAN</literal>, the correct subdirectory should be
	+ <literal>CPAN</literal>, the correct subdirectory is usually
	selected automatically. If the default subdirectory is wrong,
	<literal>CPAN/Module</literal> can be used to change it.
	<varname>MASTER_SITES</varname> can also be set to the old
	@@ -1050,13 +1050,13 @@
	directory. In such case, using author's id as
	<varname>MASTER_SITE_SUBDIR</varname> is allowed.
	The <literal>CPAN:AUTHOR</literal> macro can be used, which will
	- be translated to the hashed author directory. (e.g.,
	+ be translated to the hashed author directory. For example,
	<literal>CPAN:AUTHOR</literal> will be converted to
	- <literal>authors/id/A/AU/AUTHOR</literal>.)</para>
	+ <literal>authors/id/A/AU/AUTHOR</literal>.</para>

	<para>When a port needs <application>Perl</application> support,
	- it should use <literal>USES=perl5</literal> with the optional
	- <varname>USE_PERL5</varname> like described in <link
	+ it must set <literal>USES=perl5</literal> with the optional
	+ <varname>USE_PERL5</varname> described in <link
	linkend="uses-perl5">the perl5 USES description</link>.</para>

	<table frame="none" xml:id="using-perl-variables">
	@@ -1076,22 +1076,25 @@
	<entry><varname>PERL</varname></entry>
	<entry>The full path of the Perl 5 interpreter,
	either in the system or installed from a port, but
	- without the version number. Use this if you need to
	- replace <quote><literal>#!</literal></quote>lines in
	- scripts.</entry>
	+ without the version number. Use this when the software
	+ needs the path to the <application>Perl</application>
	+ interpreter. To replace
	+ <quote><literal>#!</literal></quote>lines in scripts,
	+ use <link
	+ linkend="uses-shebangfix">USES=shebangfix</link>.</entry>
	</row>

	<row>
	<entry><varname>PERL_VERSION</varname></entry>
	<entry>The full version of Perl
	- installed (e.g., <literal>5.8.9</literal>).</entry>
	+ installed (for example, <literal>5.8.9</literal>).</entry>
	</row>

	<row>
	<entry><varname>PERL_LEVEL</varname></entry>
	<entry>The installed Perl version as
	an integer of the form <literal>MNNNPP</literal>
	- (e.g., <literal>500809</literal>).</entry>
	+ (for example, <literal>500809</literal>).</entry>
	</row>

	<row>
	@@ -1104,7 +1107,7 @@
	<row>
	<entry><varname>PERL_PORT</varname></entry>
	<entry>Name of the Perl port that is
	- installed (e.g., <literal>perl5</literal>).</entry>
	+ installed (for example, <literal>perl5</literal>).</entry>
	</row>

	<row>
	@@ -1119,7 +1122,7 @@

	<note>
	<para>Ports of Perl modules which do not have an official
	- website should link to <systemitem>cpan.org</systemitem> in
	+ website must link to <systemitem>cpan.org</systemitem> in
	the WWW line of <filename>pkg-descr</filename>. The
	preferred URL form is
	<literal>http://search.cpan.org/dist/Module-Name/</literal>
	@@ -1168,7 +1171,7 @@
	<title>X.Org Components</title>

	<para>The X11 implementation available in The Ports Collection
	- is X.Org. If your application depends on X components, set
	+ is X.Org. If the application depends on X components, set
	<varname>USE_XORG</varname> to the list of required
	components. Available components, at the time of writing,
	are:</para>
	@@ -1192,9 +1195,9 @@
	<filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>

	<para>The Mesa Project is an effort to provide free OpenGL
	- implementation. You can specify a dependency on various
	- components of this project with <varname>USE_GL</varname>
	- variable. Valid options are:
	+ implementation. To specify a dependency on various
	+ components of this project, use <varname>USE_GL</varname>.
	+ Valid options are:
	<literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and
	<literal>linux</literal>. For backwards compatibility, the
	value of <literal>yes</literal> maps to
	@@ -1238,7 +1241,7 @@
	<sect2 xml:id="x11-motif">
	<title>Ports That Require Motif</title>

	- <para>If your port requires a Motif library, define
	+ <para>If the port requires a Motif library, define
	<varname>USES= motif</varname> in the
	<filename>Makefile</filename>. Default Motif implementation
	is
	@@ -1246,11 +1249,11 @@
	Users can choose
	<package role="port">x11-toolkits/lesstif</package>
	instead by setting <varname>WANT_LESSTIF</varname>
	- variable in their <filename>make.conf</filename>.</para>
	+ in their <filename>make.conf</filename>.</para>

	- <para>The <varname>MOTIFLIB</varname> variable will be set by
	+ <para><varname>MOTIFLIB</varname> will be set by
	<filename>motif.mk</filename> to reference the
	- appropriate Motif library. Please patch the source of your
	+ appropriate Motif library. Please patch the source of the
	port to use <literal>&dollar;{MOTIFLIB}</literal> wherever
	the Motif library is referenced in the original
	<filename>Makefile</filename> or
	@@ -1263,7 +1266,7 @@
	<para>If the port refers to the Motif library as
	<literal>-lXm</literal> in its
	<filename>Makefile</filename> or
	- <filename>Imakefile</filename>, simply substitute
	+ <filename>Imakefile</filename>, substitute
	<literal>&dollar;{MOTIFLIB}</literal> for it.</para>
	</listitem>

	@@ -1285,7 +1288,7 @@
	<sect2 xml:id="x11-fonts">
	<title>X11 Fonts</title>

	- <para>If your port installs fonts for the X Window System, put
	+ <para>If the port installs fonts for the X Window System, put
	them in
	<filename>LOCALBASE/lib/X11/fonts/local</filename>.</para>
	</sect2>
	@@ -1295,7 +1298,7 @@

	<para>Some applications require a working X11 display for
	compilation to succeed. This pose a problem for machines
	- that operate headless. When the following variable is used,
	+ that operate headless. When this variable is used,
	the build infrastructure will start the virtual framebuffer
	X server. The working <envar>DISPLAY</envar> is then passed
	to the build. See <link
	@@ -1329,7 +1332,7 @@
	Files</title>

	<para>Ports that include predefined
	- <filename>*.desktop</filename> files should
	+ <filename><replaceable>*</replaceable>.desktop</filename> must
	include those files in <filename>pkg-plist</filename>
	and install them in the
	<filename>&dollar;LOCALBASE/share/applications</filename>
	@@ -1350,14 +1353,14 @@
	</sect3>

	<sect3 xml:id="desktop-entries-macro">
	- <title>Creating Desktop Entries with the
	- <varname>DESKTOP_ENTRIES</varname> Macro</title>
	+ <title>Creating Desktop Entries with
	+ <varname>DESKTOP_ENTRIES</varname></title>

	<para>Desktop entries can be easily created for applications
	- by using the <varname>DESKTOP_ENTRIES</varname> variable. A
	+ by using <varname>DESKTOP_ENTRIES</varname>. A
	file named
	<filename><replaceable>name</replaceable>.desktop</filename>
	- will be created, installed, and added to the
	+ will be created, installed, and added to
	<filename>pkg-plist</filename> automatically. Syntax
	is:</para>

	@@ -1376,7 +1379,7 @@
	after it has started. Programs that are not compatible
	with startup notifications would never clear the indicator
	(potentially confusing and infuriating the user), and
	- should have <varname>StartupNotify</varname> set to
	+ must have <varname>StartupNotify</varname> set to
	<literal>false</literal> so the indicator is not shown at
	all.</para>

	@@ -1407,12 +1410,12 @@
	<title>Ports That Require Qt</title>

	<para>The Ports Collection provides support for Qt 4 and Qt 5
	- frameworks with the
	- <varname>USE_QT<replaceable>x</replaceable></varname>
	- variable, where <replaceable>x</replaceable> is
	+ frameworks with
	+ <varname>USE_QT<replaceable>x</replaceable></varname>,
	+ where <replaceable>x</replaceable> is
	<literal>4</literal> or <literal>5</literal>.
	- <varname>USE_QT<replaceable>x</replaceable></varname> should
	- be set to the list of required Qt components (libraries,
	+ Set <varname>USE_QT<replaceable>x</replaceable></varname>
	+ to the list of required Qt components (libraries,
	tools, plugins). The Qt 4 and Qt 5 frameworks are quite
	similar. The main difference is the set of supported
	components.</para>
	@@ -1494,29 +1497,29 @@

	<para>Some configure scripts do not support the arguments above.
	To suppress modification of<varname>CONFIGURE_ENV</varname>
	- and <varname>CONFIGURE_ARGS</varname>, set the
	- <varname>QT_NONSTANDARD</varname> variable.</para>
	+ and <varname>CONFIGURE_ARGS</varname>, set
	+ <varname>QT_NONSTANDARD</varname>.</para>
	</sect2>

	<sect2 xml:id="qt-components">
	<title>Component Selection</title>

	<para>Individual Qt tool and library dependencies must be
	- specified in the
	- <varname>USE_QT<replaceable>x</replaceable></varname>
	- variable. Every component can be suffixed with
	+ specified in
	+ <varname>USE_QT<replaceable>x</replaceable></varname>.
	+ Every component can be suffixed with
	<literal>_build</literal> or <literal>_run</literal>, the
	- suffix indicating whether the component should be depended on
	+ suffix indicating whether the dependency on the component is
	at buildtime or runtime. If unsuffixed, the component will be
	depended on at both build- and runtime. Usually, library
	- components should be specified unsuffixed, tool components
	- should be specified with the <literal>_build</literal> suffix
	- and plugin components should be specified with the
	+ components are specified unsuffixed, tool components
	+ are mostly specified with the <literal>_build</literal> suffix
	+ and plugin components are specified with the
	<literal>_run</literal> suffix. The most commonly used
	components are listed below (all available components are
	listed in <varname>_USE_QT_ALL</varname>,
	<varname>_USE_QT4_ONLY</varname>, and
	- <varname>_USE_QT5_ONLY</varname> variables in
	+ <varname>_USE_QT5_ONLY</varname> in
	<filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>

	<table frame="none" xml:id="using-qt-library-list">
	@@ -1784,10 +1787,10 @@
	<para><emphasis>Missing additional include
	paths.</emphasis> Many applications come with
	system tray icon support, but neglect to look for
	- includes and/or libraries in the X11 directories. You
	- can tell <command>qmake</command> to add directories to
	- the include and library search paths via the command
	- line, for example:</para>
	+ includes and/or libraries in the X11 directories. To add
	+ directories to <command>qmake</command>'s
	+ include and library search paths via the command
	+ line, use:</para>

	<programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
	LIBS+=-L${LOCALBASE}/lib</programlisting>
	@@ -1819,11 +1822,11 @@
	<varname>USE_KDE4</varname> to the list of required
	components. <literal>_build</literal> and
	<literal>_run</literal> suffixes can be used to force
	- components dependency type (e.g.,
	+ components dependency type (for example,
	<literal>baseapps_run</literal>). If no suffix is set, a
	- default dependency type will be used. If you want to force
	+ default dependency type will be used. To force
	both types, add the component twice with both suffixes
	- (e.g., <literal>automoc4_build automoc4_run</literal>). The
	+ (for example, <literal>automoc4_build automoc4_run</literal>). The
	most commonly used components are listed below (up-to-date
	components are documented at the top of
	<filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para>
	@@ -1995,7 +1998,7 @@
	determined through configure log.
	<varname>USE_KDE4</varname> does not imply
	<varname>USE_QT4</varname>. If a port requires some
	- Qt 4 components, they should be specified in
	+ Qt 4 components, specify them in
	<varname>USE_QT4</varname>.</para>

	<programlisting>USES= cmake:outsource
	@@ -2011,14 +2014,14 @@
	<sect2 xml:id="java-variables">
	<title>Variable Definitions</title>

	- <para>If your port needs a Java™ Development Kit
	- (JDK™) to either build, run or even extract the
	- distfile, then it should define
	+ <para>If the port needs a Java™ Development Kit
	+ (<acronym>JDK</acronym>™) to either build, run or even extract the
	+ distfile, then define
	<varname>USE_JAVA</varname>.</para>

	- <para>There are several JDKs in the ports collection, from
	- various vendors, and in several versions. If your port must
	- use one of these versions, you can define which one. The
	+ <para>There are several <acronym>JDK</acronym>s in the ports collection, from
	+ various vendors, and in several versions. If the port must
	+ use one of these versions, define which one. The
	most current version, and &os; default is
	<package role="port">java/openjdk6</package>.</para>

	@@ -2037,7 +2040,7 @@
	<tbody>
	<row>
	<entry><varname>USE_JAVA</varname></entry>
	- <entry>Should be defined for the remaining variables
	+ <entry>Define for the remaining variables
	to have any effect.</entry>
	</row>

	@@ -2045,21 +2048,21 @@
	<entry><varname>JAVA_VERSION</varname></entry>
	<entry>List of space-separated suitable Java versions
	for the port. An optional <literal>"+"</literal>
	- allows you to specify a range of versions (allowed
	+ allows specifying a range of versions (allowed
	values:
	<literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_OS</varname></entry>
	- <entry>List of space-separated suitable JDK port
	+ <entry>List of space-separated suitable <acronym>JDK</acronym> port
	operating systems for the port (allowed values:
	<literal>native linux</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_VENDOR</varname></entry>
	- <entry>List of space-separated suitable JDK port
	+ <entry>List of space-separated suitable <acronym>JDK</acronym> port
	vendors for the port (allowed values:
	<literal>freebsd bsdjava sun
	openjdk</literal>).</entry>
	@@ -2067,23 +2070,20 @@

	<row>
	<entry><varname>JAVA_BUILD</varname></entry>
	- <entry>When set, it means that the selected JDK port
	- should be added to the build dependencies of the
	- port.</entry>
	+ <entry>When set, add the selected <acronym>JDK</acronym> port to the build
	+ dependencies.</entry>
	</row>

	<row>
	<entry><varname>JAVA_RUN</varname></entry>
	- <entry>When set, it means that the selected JDK port
	- should be added to the run dependencies of the
	- port.</entry>
	+ <entry>When set, add the selected <acronym>JDK</acronym> port to the run
	+ dependencies.</entry>
	</row>

	<row>
	<entry><varname>JAVA_EXTRACT</varname></entry>
	- <entry>When set, it means that the selected JDK port
	- should be added to the extract dependencies of the
	- port.</entry>
	+ <entry>When set, add the selected <acronym>JDK</acronym> port to the
	+ extract dependencies.</entry>
	</row>
	</tbody>
	</tgroup>
	@@ -2106,61 +2106,61 @@
	<tbody>
	<row>
	<entry><varname>JAVA_PORT</varname></entry>
	- <entry>The name of the JDK port (e.g.,
	- <literal>'java/openjdk6'</literal>).</entry>
	+ <entry>The name of the <acronym>JDK</acronym> port (for example,
	+ <literal>java/openjdk6</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_PORT_VERSION</varname></entry>
	- <entry>The full version of the JDK port (e.g.,
	- <literal>'1.6.0'</literal>). If you only need the
	- first two digits of this version number, use
	+ <entry>The full version of the <acronym>JDK</acronym> port (for example,
	+ <literal>1.6.0</literal>). Only the first two
	+ digits of this version number are needed, use
	<varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry>
	</row>

	<row>
	<entry><varname>JAVA_PORT_OS</varname></entry>
	- <entry>The operating system used by the JDK port
	- (e.g., <literal>'native'</literal>).</entry>
	+ <entry>The operating system used by the <acronym>JDK</acronym> port
	+ (for example, <literal>'native'</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_PORT_VENDOR</varname></entry>
	- <entry>The vendor of the JDK port (e.g.,
	+ <entry>The vendor of the <acronym>JDK</acronym> port (for example,
	<literal>'openjdk'</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry>
	<entry>Description of the operating system used by the
	- JDK port (e.g.,
	+ <acronym>JDK</acronym> port (for example,
	<literal>'Native'</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry>
	- <entry>Description of the vendor of the JDK port
	- (e.g., <literal>'OpenJDK BSD Porting
	+ <entry>Description of the vendor of the <acronym>JDK</acronym> port
	+ (for example, <literal>'OpenJDK BSD Porting
	Team'</literal>).</entry>
	</row>

	<row>
	<entry><varname>JAVA_HOME</varname></entry>
	- <entry>Path to the installation directory of the JDK
	- (e.g.,
	+ <entry>Path to the installation directory of the <acronym>JDK</acronym>
	+ (for example,
	<filename>'/usr/local/openjdk6'</filename>).</entry>
	</row>

	<row>
	<entry><varname>JAVAC</varname></entry>
	- <entry>Path to the Java compiler to use (e.g.,
	+ <entry>Path to the Java compiler to use (for example,
	<filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry>
	</row>

	<row>
	<entry><varname>JAR</varname></entry>
	<entry>Path to the <command>jar</command> tool to use
	- (e.g.,
	+ (for example,
	<filename>'/usr/local/openjdk6/bin/jar'</filename>
	or
	<filename>'/usr/local/bin/fastjar'</filename>).</entry>
	@@ -2169,14 +2169,14 @@
	<row>
	<entry><varname>APPLETVIEWER</varname></entry>
	<entry>Path to the <command>appletviewer</command>
	- utility (e.g.,
	+ utility (for example,
	<filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry>
	</row>

	<row>
	<entry><varname>JAVA</varname></entry>
	<entry>Path to the <command>java</command> executable.
	- Use this for executing Java programs (e.g.,
	+ Use this for executing Java programs (for example,
	<filename>'/usr/local/openjdk6/bin/java'</filename>).</entry>
	</row>

	@@ -2242,7 +2242,7 @@

	<row>
	<entry><varname>JAVA_CLASSES</varname></entry>
	- <entry>Path to the archive that contains the JDK class
	+ <entry>Path to the archive that contains the <acronym>JDK</acronym> class
	files,
	<filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry>
	</row>
	@@ -2250,11 +2250,11 @@
	</tgroup>
	</table>

	- <para>You may use the <literal>java-debug</literal> make
	- target to get information for debugging your port. It will
	- display the value of many of the forecited variables.</para>
	+ <para>Use the <buildtarget>java-debug</buildtarget> make
	+ target to get information for debugging the port. It will
	+ display the value of many of the previously listed variables.</para>

	- <para>Additionally, the following constants are defined so all
	+ <para>Additionally, these constants are defined so all
	Java ports may be installed in a consistent way:</para>

	<table frame="none" xml:id="using-java-constants">
	@@ -2278,7 +2278,7 @@

	<row>
	<entry><varname>JAVAJARDIR</varname></entry>
	- <entry>The directory where JAR files should be
	+ <entry>The directory where JAR files is
	installed. Default:
	<filename>${JAVASHAREDIR}/classes</filename>.</entry>
	</row>
	@@ -2305,37 +2305,37 @@
	<para>When the port is to be built using Apache Ant, it has to
	define <varname>USE_ANT</varname>. Ant is thus considered
	to be the sub-make command. When no
	- <literal>do-build</literal> target is defined by the port, a
	- default one will be set that simply runs Ant according to
	+ <buildtarget>do-build</buildtarget> target is defined by the port, a
	+ default one will be set that runs Ant according to
	<varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname>
	and <varname>ALL_TARGET</varname>. This is similar to the
	- <varname>USES= gmake</varname> mechanism, which is
	+ <literal>USES= gmake</literal> mechanism, which is
	documented in <xref linkend="building"/>.</para>
	</sect2>

	<sect2 xml:id="java-best-practices">
	<title>Best Practices</title>

	- <para>When porting a Java library, your port should install
	+ <para>When porting a Java library, the port has to install
	the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and
	everything else under
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for
	- the documentation, see below). In order to reduce the
	- packing file size, you may reference the JAR file(s)
	- directly in the <filename>Makefile</filename>. Just use the
	- following statement (where <filename>myport.jar</filename>
	+ the documentation, see below). To reduce the
	+ packing file size, reference the JAR file(s)
	+ directly in the <filename>Makefile</filename>. Use this
	+ statement (where <filename><replaceable>myport</replaceable>.jar</filename>
	is the name of the JAR file installed as part of the
	port):</para>

	- <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
	+ <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/<replaceable>myport</replaceable>.jar</programlisting>

	<para>When porting a Java application, the port usually
	installs everything under a single directory (including its
	JAR dependencies). The use of
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly
	encouraged in this regard. It is up the porter to decide
	- whether the port should install the additional JAR
	- dependencies under this directory or directly use the
	+ whether the port installs the additional JAR
	+ dependencies under this directory or uses the
	already installed ones (from
	<filename>${JAVAJARDIR}</filename>).</para>

	@@ -2343,13 +2343,13 @@
	application server such as
	<package role="port">www/tomcat7</package> to run the
	service, it is quite common for a vendor to distribute a
	- <filename>.war</filename> file. A <filename>.war</filename>
	- file is a Web application ARchive and is extracted when
	+ <filename>.war</filename>. A <filename>.war</filename>
	+ is a Web application ARchive and is extracted when
	called by the application. Avoid adding a
	<filename>.war</filename>
	- file to the <filename>pkg-plist</filename>.
	+ to <filename>pkg-plist</filename>.
	It is not considered best practice. An application server
	- will expand the <filename>war</filename> archive, but not
	+ will expand <application>war</application> archive, but not
	clean it up properly if the port is removed. A more
	desirable way of working with this file is to extract the
	archive, then install the files, and lastly add these files
	@@ -2367,19 +2367,19 @@
	${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME}
	@cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting>

	- <para>Regardless of the type of your port (library or
	- application), the additional documentation should be
	+ <para>Regardless of the type of port (library or
	+ application), the additional documentation is
	installed in the
	<link linkend="install-documentation">same location</link>
	as for any other port. The JavaDoc tool is known to produce
	- a different set of files depending on the version of the JDK
	+ a different set of files depending on the version of the <acronym>JDK</acronym>
	that is used. For ports that do not enforce the use of a
	- particular JDK, it is therefore a complex task to specify
	+ particular <acronym>JDK</acronym>, it is therefore a complex task to specify
	the packing list (<filename>pkg-plist</filename>). This is
	- one reason why porters are strongly encouraged to use the
	- <varname>PORTDOCS</varname> macro. Moreover, even if you
	- can predict the set of files that will be generated by
	- <command>javadoc</command>, the size of the resulting
	+ one reason why porters are strongly encouraged to use
	+ <varname>PORTDOCS</varname>. Moreover, even if the
	+ set of files that will be generated by
	+ <command>javadoc</command> can be predicted, the size of the resulting
	<filename>pkg-plist</filename> advocates for the use of
	<varname>PORTDOCS</varname>.</para>

	@@ -2389,7 +2389,7 @@
	<filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java
	ports. Indeed, <varname>DATADIR</varname> is automatically
	added to <varname>PLIST_SUB</varname> (documented in
	- <xref linkend="plist-sub"/>) so you may use
	+ <xref linkend="plist-sub"/>) so use
	<literal>%%DATADIR%%</literal> directly in
	<filename>pkg-plist</filename>.</para>

	@@ -2403,21 +2403,21 @@

	<para>All the features that have been presented in this
	section are implemented in <filename>bsd.java.mk</filename>.
	- If you ever think that your port needs more sophisticated
	+ If the port needs more sophisticated
	Java support, please first have a look at the <link
	- xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk
	+ xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log">bsd.java.mk
	<application>Subversion</application> log</link> as it
	usually takes some time to document the latest features.
	- Then, if you think the support you are lacking would be
	+ Then, if the needed support that is lacking would be
	beneficial to many other Java ports, feel free to discuss it
	on the &a.java;.</para>

	<para>Although there is a <literal>java</literal> category for
	- PRs, it refers to the JDK porting effort from the &os; Java
	- project. Therefore, you should submit your Java port in the
	+ PRs, it refers to the <acronym>JDK</acronym> porting effort from the &os; Java
	+ project. Therefore, submit the Java port in the
	<literal>ports</literal> category as for any other port,
	- unless the issue you are trying to resolve is related to
	- either a JDK implementation or
	+ unless the issue is related to
	+ either a <acronym>JDK</acronym> implementation or
	<filename>bsd.java.mk</filename>.</para>

	<para>Similarly, there is a defined policy regarding the
	@@ -2454,13 +2454,13 @@
	<row>
	<entry><varname>APXS</varname></entry>
	<entry>Full path to the <command>apxs</command>
	- binary. Can be overridden in your port.</entry>
	+ binary. Can be overridden in the port.</entry>
	</row>

	<row>
	<entry><varname>HTTPD</varname></entry>
	<entry>Full path to the <command>httpd</command>
	- binary. Can be overridden in your port.</entry>
	+ binary. Can be overridden in the port.</entry>
	</row>

	<row>
	@@ -2555,9 +2555,9 @@
	<sect2 xml:id="web-apps">
	<title>Web Applications</title>

	- <para>Web applications should be installed into
	+ <para>Web applications must be installed into
	<filename>PREFIX/www/<replaceable>appname</replaceable></filename>.
	- For your convenience, this path is available both in
	+ This path is available both in
	<filename>Makefile</filename> and in
	<filename>pkg-plist</filename> as <varname>WWWDIR</varname>,
	and the path relative to <varname>PREFIX</varname> is
	@@ -2566,14 +2566,14 @@

	<para>The user and group of web server process are available
	as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>,
	- in case you need to change the ownership of some files. The
	- default values of both are <literal>www</literal>. If you
	- want different values for your port, use
	- <literal>WWWOWN?= myuser</literal> notation, to allow user
	- to override it easily.</para>
	+ in case the ownership of some files needs to be changed. The
	+ default values of both are <literal>www</literal>. Use
	+ <literal>WWWOWN?= myuser</literal> and <literal>WWWGRP?=
	+ mygroup</literal> if the port needs different values. This
	+ allows the user to override them easily.</para>

	<para>Do not depend on Apache unless the web app explicitly
	- needs Apache. Respect that users may wish to run your web
	+ needs Apache. Respect that users may wish to run a web
	app on different web server than Apache.</para>
	</sect2>

	@@ -2668,7 +2668,7 @@
	<varname>TESTS</varname>, <varname>DATA</varname>,
	<varname>SQLS</varname>, <varname>SCRIPTFILES</varname>,
	<varname>DOCS</varname> and <varname>EXAMPLES</varname> to
	- list the files you want to install. All listed files will
	+ list the files to install. All listed files will
	be automatically installed into the appropriate locations
	and added to <filename>pkg-plist</filename>.</para>

	@@ -2712,15 +2712,15 @@
	<title>Using Python</title>

	<para>The Ports Collection supports parallel installation of
	- multiple Python versions. Ports should make sure to use a
	+ multiple Python versions. Ports must use a
	correct <command>python</command> interpreter, according to
	- the user-settable <varname>PYTHON_VERSION</varname> variable.
	+ the user-settable <varname>PYTHON_VERSION</varname>.
	Most prominently, this means replacing the path to
	<command>python</command> executable in scripts with the value
	- of <varname>PYTHON_CMD</varname> variable.</para>
	+ of <varname>PYTHON_CMD</varname>.</para>

	<para>Ports that install files under
	- <varname>PYTHON_SITELIBDIR</varname> should use the
	+ <varname>PYTHON_SITELIBDIR</varname> must use the
	<literal>pyXY-</literal> package name prefix, so their package
	name embeds the version of Python they are installed
	into.</para>
	@@ -2738,7 +2738,7 @@
	can be specified with values such as
	<literal>2.6+</literal>. Version ranges can also be
	specified, by separating two version numbers with a
	- dash, e.g.: <literal>2.6-2.7</literal></entry>
	+ dash, for example, <literal>2.6-2.7</literal></entry>
	</row>

	<row>
	@@ -2764,8 +2764,8 @@
	<entry><varname>PYTHON_SITELIBDIR</varname></entry>
	<entry>Location of the site-packages tree, that contains
	installation path of Python (usually
	- <varname>LOCALBASE</varname>). The
	- <varname>PYTHON_SITELIBDIR</varname> variable can be
	+ <varname>LOCALBASE</varname>).
	+ <varname>PYTHON_SITELIBDIR</varname> can be
	very useful when installing Python modules.</entry>
	</row>

	@@ -2830,8 +2830,8 @@
	byte-compiled output file by <literal>-d</literal>.
	<literal>-f</literal> is required to force recompilation, and
	the <literal>:S;${PREFIX}/;;</literal> strips prefixes from
	- the value of the <varname>PYTHONPREFIX_SITELIBDIR</varname>
	- variable to make it relative to
	+ the value of <varname>PYTHONPREFIX_SITELIBDIR</varname>
	+ to make it relative to
	<varname>PREFIX</varname>.</para>
	</sect1>

	@@ -2844,7 +2844,7 @@
	<application>Tcl/Tk</application> version and higher with
	<literal>USES=tcl</literal>. It is possible to specify the
	desired version of <command>tcl</command> by appending
	- <literal>:<replaceable>xx</replaceable></literal>, e.g.:
	+ <literal>:<replaceable>xx</replaceable></literal>, for example,
	<literal>USES=tcl:85</literal>.</para>

	<table frame="none" xml:id="using-tcl-variables">
	@@ -2959,12 +2959,11 @@
	</tgroup>
	</table>

	- <para>The following table shows the selected variables available
	+ <para>This table shows the selected variables available
	to port authors via the ports infrastructure. These variables
	- should be used to install files into their proper locations.
	+ are used to install files into their proper locations.
	Use them in <filename>pkg-plist</filename> as much as
	- possible. These variables should not be redefined in the
	- port.</para>
	+ possible. Do not redefine these variables in the port.</para>

	<table frame="none" xml:id="using-ruby-variables-ro">
	<title>Selected Read-Only Variables for Ports That Use
	@@ -3031,13 +3030,12 @@
	<sect1 xml:id="using-sdl">
	<title>Using SDL</title>

	- <para>The <varname>USE_SDL</varname> variable is used to
	+ <para><varname>USE_SDL</varname> is used to
	autoconfigure the dependencies for ports which use an SDL
	based library like <package role="port">devel/sdl12</package>
	and <package role="port">graphics/sdl_image</package>.</para>

	- <para>The following SDL libraries for version 1.2 are recognized
	- at the moment:</para>
	+ <para>These SDL libraries for version 1.2 are recognized:</para>

	<itemizedlist>
	<listitem>
	@@ -3088,8 +3086,7 @@
	</listitem>
	</itemizedlist>

	- <para>The following SDL libraries for version 2.0 are recognized
	- at the moment:</para>
	+ <para>These SDL libraries for version 2.0 are recognized:</para>

	<itemizedlist>
	<listitem>
	@@ -3135,7 +3132,7 @@
	and <package role="port">audio/sdl_mixer</package>, is
	automatically added as well.</para>

	- <para>If you use <varname>USE_SDL</varname> with entries using
	+ <para>Using <varname>USE_SDL</varname> with entries for
	SDL 1.2, it will automatically:</para>

	<itemizedlist>
	@@ -3151,12 +3148,12 @@
	</listitem>

	<listitem>
	- <para>Add the dependencies of the selected libraries to the
	+ <para>Add the dependencies of the selected libraries to
	<varname>LIB_DEPENDS</varname></para>
	</listitem>
	</itemizedlist>

	- <para>If you use <varname>USE_SDL</varname> with entries using
	+ <para>Using <varname>USE_SDL</varname> with entries for
	SDL 2.0, it will automatically:</para>

	<itemizedlist>
	@@ -3172,13 +3169,13 @@
	</listitem>

	<listitem>
	- <para>Add the dependencies of the selected libraries to the
	+ <para>Add the dependencies of the selected libraries to
	<varname>LIB_DEPENDS</varname></para>
	</listitem>
	</itemizedlist>

	- <para>To check whether an SDL library is available, you can do
	- it with the <varname>WANT_SDL</varname> variable:</para>
	+ <para>To check whether an SDL library is available, use
	+ <varname>WANT_SDL</varname>:</para>

	<programlisting>WANT_SDL= yes

	@@ -3223,7 +3220,7 @@
	<sect2 xml:id="wx-version">
	<title>Version Selection</title>

	- <para>To make your port use a specific version of
	+ <para>To make the port use a specific version of
	<application>wxWidgets</application> there are two variables
	available for defining (if only one is defined the other
	will be set to a default value):</para>
	@@ -3250,16 +3247,16 @@

	<row>
	<entry><varname>USE_WX_NOT</varname></entry>
	- <entry>List of versions the port can not use</entry>
	+ <entry>List of versions the port cannot use</entry>
	<entry>None</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	- <para>The following is a list of available
	+ <para>The available
	<application>wxWidgets</application> versions and the
	- corresponding ports in the tree:</para>
	+ corresponding ports in the tree are:</para>

	<table frame="none" xml:id="wx-widgets-versions-table">
	<title>Available <application>wxWidgets</application>
	@@ -3305,7 +3302,7 @@
	</note>

	<para>The variables in <xref linkend="wx-ver-sel-table"/> can
	- be set to one or more of the following combinations
	+ be set to one or more of these combinations
	separated by spaces:</para>

	<table frame="none" xml:id="wx-widgets-versions-specification">
	@@ -3381,8 +3378,8 @@

	<para>There are other applications that, while not being
	<application>wxWidgets</application> libraries, are related
	- to them. These applications can be specified in the
	- <varname>WX_COMPS</varname> variable. The following
	+ to them. These applications can be specified in
	+ <varname>WX_COMPS</varname>. These
	components are available:</para>

	<table frame="none" xml:id="wx-widgets-components-table">
	@@ -3436,7 +3433,7 @@
	<para>The dependency type can be selected for each component
	by adding a suffix separated by a semicolon. If not present
	then a default type will be used (see
	- <xref linkend="wx-def-dep-types"/>). The following types
	+ <xref linkend="wx-def-dep-types"/>). These types
	are available:</para>

	<table frame="none" xml:id="wx-widgets-dependency-table">
	@@ -3474,7 +3471,7 @@
	</table>

	<para>The default values for the components are detailed in
	- the following table:</para>
	+ this table:</para>

	<table xml:id="wx-def-dep-types" frame="none">
	<title>Default <application>wxWidgets</application>
	@@ -3521,7 +3518,7 @@
	<title>Selecting <application>wxWidgets</application>
	Components</title>

	- <para>The following fragment corresponds to a port which
	+ <para>This fragment corresponds to a port which
	uses <application>wxWidgets</application> version
	<literal>2.4</literal> and its contributed
	libraries.</para>
	@@ -3537,7 +3534,7 @@
	<para>The <application>wxWidgets</application> library
	supports Unicode since version <literal>2.5</literal>. In
	the ports tree both versions are available and can be
	- selected with the following variables:</para>
	+ selected with these variables:</para>

	<table xml:id="wx-unicode-var-table" frame="none">
	<title>Variables to Select Unicode in
	@@ -3587,8 +3584,8 @@

	<warning>
	<para>Do not use <varname>WX_UNICODE</varname> for ports
	- that can use both Unicode and normal versions. If you
	- want the port to use Unicode by default define
	+ that can use both Unicode and normal versions. If
	+ the port needs to use Unicode by default, define
	<varname>WANT_UNICODE</varname> instead.</para>
	</warning>
	</sect2>
	@@ -3596,10 +3593,10 @@
	<sect2 xml:id="wx-version-detection">
	<title>Detecting Installed Versions</title>

	- <para>To detect an installed version you have to define
	- <varname>WANT_WX</varname>. If you do not set it to a
	+ <para>To detect an installed version, define
	+ <varname>WANT_WX</varname>. If it is not set to a
	specific version then the components will have a version
	- suffix. The <varname>HAVE_WX</varname> variable will be
	+ suffix. <varname>HAVE_WX</varname> will be
	filled after detection.</para>

	<example xml:id="wx-ver-det-example">
	@@ -3607,7 +3604,7 @@
	<application>wxWidgets</application> Versions and
	Components</title>

	- <para>The following fragment can be used in a port that uses
	+ <para>This fragment can be used in a port that uses
	<application>wxWidgets</application> if it is installed,
	or an option is selected.</para>

	@@ -3620,7 +3617,7 @@
	CONFIGURE_ARGS+= --enable-wx
	.endif</programlisting>

	- <para>The following fragment can be used in a port that
	+ <para>This fragment can be used in a port that
	enables <application>wxPython</application> support if it
	is installed or if an option is selected, in addition to
	<application>wxWidgets</application>, both version
	@@ -3642,7 +3639,7 @@
	<sect2 xml:id="wx-defined-variables">
	<title>Defined Variables</title>

	- <para>The following variables are available in the port (after
	+ <para>These variables are available in the port (after
	defining one from
	<xref linkend="wx-ver-sel-table"/>).</para>

	@@ -3678,7 +3675,7 @@
	<row>
	<entry><varname>WX_VERSION</varname></entry>
	<entry>The <application>wxWidgets</application>
	- version that is going to be used (e.g.,
	+ version that is going to be used (for example,
	<literal>2.6</literal>)</entry>
	</row>

	@@ -3696,14 +3693,14 @@
	<title>Processing in
	<filename>bsd.port.pre.mk</filename></title>

	- <para>If you need to use the variables for running commands
	- right after including <filename>bsd.port.pre.mk</filename>
	- you need to define <varname>WX_PREMK</varname>.</para>
	+ <para>Define <varname>WX_PREMK</varname> to be able to use the
	+ variables right after including
	+ <filename>bsd.port.pre.mk</filename>.</para>

	<important>
	- <para>If you define <varname>WX_PREMK</varname>, then the
	+ <para>When defining <varname>WX_PREMK</varname>, then the
	version, dependencies, components and defined variables
	- will not change if you modify the
	+ will not change if modifying the
	<application>wxWidgets</application> port variables
	<emphasis>after</emphasis> including
	<filename>bsd.port.pre.mk</filename>.</para>
	@@ -3713,7 +3710,7 @@
	<title>Using <application>wxWidgets</application> Variables
	in Commands</title>

	- <para>The following fragment illustrates the use of
	+ <para>This fragment illustrates the use of
	<varname>WX_PREMK</varname> by running the
	<command>wx-config</command> script to obtain the full
	version string, assign it to a variable and pass it to the
	@@ -3742,11 +3739,11 @@
	<title>Additional <command>configure</command>
	Arguments</title>

	- <para>Some GNU <command>configure</command> scripts can not
	+ <para>Some GNU <command>configure</command> scripts cannot
	find <application>wxWidgets</application> with just the
	<literal>WX_CONFIG</literal> environment variable set,
	- requiring additional arguments. The
	- <varname>WX_CONF_ARGS</varname> variable can be used for
	+ requiring additional arguments.
	+ <varname>WX_CONF_ARGS</varname> can be used for
	provide them.</para>

	<table frame="none" xml:id="wx-conf-args-values">
	@@ -3805,7 +3802,7 @@
	<title>Version Selection</title>

	<para>A port using <application>Lua</application> only needs to
	- have the following line:</para>
	+ have this line:</para>

	<programlisting>USES= lua</programlisting>

	@@ -3818,7 +3815,7 @@
	<sect2 xml:id="lua-defined-variables">
	<title>Defined Variables</title>

	- <para>The following variables are available in the port.</para>
	+ <para>These variables are available in the port.</para>

	<table frame="none" xml:id="using-lua-variables-ports">
	<title>Variables Defined for Ports That Use
	@@ -3836,14 +3833,14 @@
	<row>
	<entry><varname>LUA_VER</varname></entry>
	<entry>The <application>Lua</application> version that
	- is going to be used (e.g.,
	+ is going to be used (for example,
	<literal>5.1</literal>)</entry>
	</row>

	<row>
	<entry><varname>LUA_VER_STR</varname></entry>
	<entry>The <application>Lua</application> version
	- without the dots (e.g.,
	+ without the dots (for example,
	<literal>51</literal>)</entry>
	</row>

	@@ -4059,14 +4056,14 @@
	<sect1 xml:id="using-xfce">
	<title>Using Xfce</title>

	- <para>The <varname>USE_XFCE</varname> variable is used to
	+ <para><varname>USE_XFCE</varname> is used to
	autoconfigure the dependencies for ports which use an Xfce
	based library or application like
	<package role="port">x11-toolkits/libxfce4gui</package>
	and <package role="port">x11-wm/xfce4-panel</package>.</para>

	- <para>The following Xfce libraries and applications are
	- recognized at the moment:</para>
	+ <para>These Xfce libraries and applications are
	+ recognized:</para>

	<itemizedlist>
	<listitem>
	@@ -4115,11 +4112,11 @@
	</listitem>
	</itemizedlist>

	- <para>The following additional parameters are recognized:</para>
	+ <para>These additional parameters are recognized:</para>

	<itemizedlist>
	<listitem>
	- <para>configenv: Use this if your port requires a special
	+ <para>configenv: Use this if the port requires a special
	modified <varname>CONFIGURE_ENV</varname> to find its
	required libraries.</para>

	@@ -4154,7 +4151,7 @@
	(<filename>libxul.so</filename>),
	<literal>seamonkey</literal>
	(<filename>libgtkembedmoz.so</filename>, deprecated,
	- should not be used any more).</entry>
	+ must not be used any more).</entry>
	</row>

	<row>
	@@ -4180,7 +4177,7 @@
	<entry>The port requires SeaMonkey as a runtime
	dependency. Possible values: <literal>yes</literal>
	(get default version), <literal>20</literal>,
	- <literal>11</literal> (deprecated, should not be used
	+ <literal>11</literal> (deprecated, must not be used
	any more). Default dependency is on version
	<literal>20</literal>.</entry>
	</row>
	@@ -4198,7 +4195,7 @@
	<entry>The port requires Thunderbird as a runtime
	dependency. Possible values: <literal>yes</literal>
	(get default version), <literal>31</literal>,
	- <literal>30</literal> (deprecated, should not be used
	+ <literal>30</literal> (deprecated, must not be used
	any more). Default dependency is on version
	<literal>31</literal>.</entry>
	</row>
	@@ -4239,7 +4236,7 @@
	add dependency on
	<package role="port">databases/db41</package>
	port. The variable may also be set to values: 40, 41,
	- 42, 43, 44, 46, 47, 48, or 51. You can declare a
	+ 42, 43, 44, 46, 47, 48, or 51. It is possible to declare a
	range of acceptable values,
	<varname>USE_BDB</varname>=42+ will find the highest
	installed version, and fall back to 42 if nothing else
	@@ -4264,7 +4261,7 @@
	role="port">databases/postgresql90-client</package>
	port. An associated variable,
	<varname>WANT_PGSQL_VER</varname>, may be set to
	- values such as 83, 84, 90, 91 or 92. You can declare
	+ values such as 83, 84, 90, 91 or 92. It is possible to declare
	a minimum or maximum value;
	<varname>WANT_PGSQL_VER</varname>= <literal>
	90+</literal> will cause the port to depend on a
	@@ -4334,7 +4331,7 @@
	# REQUIRE: LOGIN
	# KEYWORD: shutdown
	#
	-# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
	+# Add these lines to /etc/rc.conf.local or /etc/rc.conf
	# to enable this service:
	#
	# doormand_enable (bool): Set to NO by default.
	@@ -4360,7 +4357,7 @@
	run_rc_command "$1"</programlisting>

	<para>Unless there is a good reason to start the service
	- earlier all ports scripts should use</para>
	+ earlier, all ports scripts should use</para>

	<programlisting>REQUIRE: LOGIN</programlisting>

	@@ -4370,7 +4367,7 @@
	<programlisting>KEYWORD: shutdown</programlisting>

	<para>is included in the script above because the mythical port
	- we are using as an example starts a service, and should be
	+ we are using as an example starts a service, and it must be
	shut down cleanly when the system shuts down. If the script
	is not starting a persistent service this is not
	necessary.</para>
	@@ -4384,18 +4381,18 @@

	<programlisting>doormand_flags=""</programlisting>

	- <para>in their <filename>rc.conf.local</filename> file, and a
	+ <para>in their <filename>rc.conf.local</filename>, and a
	variable substitution using ":=" would
	inappropriately override the user's intention. The
	<literal>_enable</literal> variable is not optional,
	- and should use the ":" for the default.</para>
	+ and must use the ":" for the default.</para>

	<sect2 xml:id="rc-scripts-checklist">
	<title>Pre-Commit Checklist</title>

	<para>Before contributing a port with an
	<filename>rc.d</filename> script, and more importantly,
	- before committing one, please consult the following
	+ before committing one, please consult this
	checklist to be sure that it is ready.</para>

	<para>The <package role="port">devel/rclint</package>
	@@ -4404,9 +4401,9 @@

	<procedure>
	<step>
	- <para>If this is a new file, does it have
	- <filename>.sh</filename> in the file name? If so that
	- should be changed to just <filename>file.in</filename>
	+ <para>If this is a new file, does it have a
	+ <filename>.sh</filename> extension? If so, that
	+ must be changed to just <filename><replaceable>file</replaceable>.in</filename>
	since <filename>rc.d</filename> files may not end
	with that extension.</para>
	</step>
	@@ -4427,8 +4424,8 @@
	file name and
	<literal>&dollar;</literal><replaceable>name</replaceable>
	makes it easier to figure out which variables are
	- relevant in <filename>rc.conf[.local]</filename>. The
	- latter is also what you might call “policy”
	+ relevant in <filename>rc.conf[.local]</filename>. It is
	+ also a policy
	for all new scripts, including those in the base
	system.</para>
	</step>
	@@ -4438,15 +4435,15 @@
	<literal>LOGIN</literal>? This is mandatory for scripts
	that run as a non-root user. If it runs as root, is
	there a good reason for it to run prior to
	- <literal>LOGIN</literal>? If not, it should run there
	- so that we can loosely group local scripts to a point in
	+ <literal>LOGIN</literal>? If not, it must run after
	+ so that local scrips can be loosely grouped to a point in
	&man.rcorder.8; after most everything in the base is
	already running.</para>
	</step>

	<step>
	<para>Does the script start a persistent service? If so,
	- it should have <literal>KEYWORD:
	+ it must have <literal>KEYWORD:
	shutdown</literal>.</para>
	</step>

	@@ -4455,7 +4452,7 @@
	<literal>KEYWORD: &os;</literal> present. This has
	not been necessary or desirable for years. It is also
	an indication that the new script was copy/pasted from
	- an old script, so extra caution should be given to the
	+ an old script, so extra caution must be given to the
	review.</para>
	</step>

	@@ -4464,7 +4461,7 @@
	<command>perl</command>, <command>python</command>, or
	<command>ruby</command>, make certain that
	<varname>command_interpreter</varname> is set
	- appropriately, e.g., for <application>Perl</application>,
	+ appropriately, for example, for <application>Perl</application>,
	by adding <literal>PERL=${PERL}</literal> to
	<varname>SUB_LIST</varname> and using
	<literal>%%PERL%%</literal>. Otherwise,</para>
	@@ -4501,7 +4498,7 @@
	<step>
	<para>Are options listed in the default
	<replaceable>name</replaceable><varname>_flags</varname>
	- things that are actually mandatory? If so, they should
	+ things that are actually mandatory? If so, they must
	be in <varname>command_args</varname>. The
	<option>-d</option> option is a red flag (pardon the
	pun) here, since it is usually the option to
	@@ -4510,22 +4507,21 @@
	</step>

	<step>
	- <para>The
	- <replaceable>name</replaceable><varname>_flags</varname>
	- variable should never be included in
	+ <para><varname><replaceable>name</replaceable>_flags</varname>
	+ must never be included in
	<varname>command_args</varname> (and vice versa,
	although that error is less common).</para>
	</step>

	<step>
	<para>Does the script execute any code unconditionally?
	- This is frowned on. Usually these things can/should be
	+ This is frowned on. Usually these things must be
	dealt with through a
	<function>start_precmd</function>.</para>
	</step>

	<step>
	- <para>All boolean tests should utilize the
	+ <para>All boolean tests must use the
	<function>checkyesno</function> function. No
	hand-rolled tests for <literal>[Yy][Ee][Ss]</literal>,
	etc.</para>
	@@ -4541,7 +4537,7 @@
	<step>
	<para>Does the script create files or directories that
	need specific permissions, for example, a
	- <filename>pid</filename> file that needs to be owned by
	+ <filename>pid</filename> that needs to be owned by
	the user that runs the process? Rather than the
	traditional &man.touch.1;/&man.chown.8;/&man.chmod.1;
	routine, consider using &man.install.1; with the proper
	@@ -4558,16 +4554,16 @@
	<para>Some ports require a certain user to be on the installed
	system. Choose a free UID from 50 to 999 and register it
	either in <filename>ports/UIDs</filename> (for users) or in
	- <filename>ports/GIDs</filename> (for groups). Make sure you
	- do not use a UID already used by the system or other
	+ <filename>ports/GIDs</filename> (for groups). Make sure
	+ not to use a UID already used by the system or other
	ports.</para>

	- <para>Please include a patch against these two files when you
	- require a new user or group to be created for your
	+ <para>Please include a patch against these two files when
	+ requiring a new user or group to be created for the
	port.</para>

	- <para>Then you can use <varname>USERS</varname> and
	- <varname>GROUPS</varname> variables in your
	+ <para>Then use <varname>USERS</varname> and
	+ <varname>GROUPS</varname> in
	<filename>Makefile</filename>, and the user will be
	automatically created when installing the port.</para>

File Metadata

Mime Type: text/plain
Expires: Sun, Feb 15, 3:05 AM (19 h, 26 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 28692717
Default Alt Text: D653.id1638.diff (72 KB)

D653.id1638.diffNo OneTemporaryActions

D653.id1638.diffView Options

File Metadata

Event Timeline

D653.id1638.diff
No OneTemporary
Actions

D653.id1638.diff
View Options