Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 16 Sep 2014 12:01:30 +0000 (UTC)
From:      Mathieu Arnold <mat@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r45616 - head/en_US.ISO8859-1/books/porters-handbook/special
Message-ID:  <201409161201.s8GC1UPW026876@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: mat (ports committer)
Date: Tue Sep 16 12:01:29 2014
New Revision: 45616
URL: http://svnweb.freebsd.org/changeset/doc/45616

Log:
  igor -Ry and some other rewording and fixes.
  
  Differential Revision:	https://reviews.freebsd.org/D653
  Reviewed by:	wblock
  Sponsored by:	Absolight

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Tue Sep 16 11:58:50 2014	(r45615)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Tue Sep 16 12:01:29 2014	(r45616)
@@ -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 @@ IGNORE=	may not be redistributed because
 	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 @@ IGNORE=	may not be redistributed because
 	  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 @@ IGNORE=	may not be redistributed because
     <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 @@ IGNORE=	may not be redistributed because
 	  --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 @@ IGNORE=	may not be redistributed because
       </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 @@ IGNORE=	may not be redistributed because
 	</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 @@ IGNORE=	may not be redistributed because
 	<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 @@ IGNORE=	may not be redistributed because
       <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 @@ CMAKE_SOURCE_PATH=	&dollar;{WRKSRC}/subp
     <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 @@ CMAKE_SOURCE_PATH=	&dollar;{WRKSRC}/subp
       <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 @@ CMAKE_SOURCE_PATH=	&dollar;{WRKSRC}/subp
 	<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 @@ CMAKE_SOURCE_PATH=	&dollar;{WRKSRC}/subp
 	<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 @@ CMAKE_SOURCE_PATH=	&dollar;{WRKSRC}/subp
     <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 @@ GNU_CONFIGURE=	yes</programlisting>
     <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 @@ PLIST_SUB+=		NLS="@comment "
 
 .include &lt;bsd.port.mk&gt;</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 @@ PLIST_SUB+=		NLS="@comment "
 	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 @@ PLIST_SUB+=		NLS="@comment "
       <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 @@ PLIST_SUB+=		NLS="@comment "
 	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 @@ PLIST_SUB+=		NLS="@comment "
     <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 @@ PLIST_SUB+=		NLS="@comment "
       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 @@ PLIST_SUB+=		NLS="@comment "
 	    <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 @@ PLIST_SUB+=		NLS="@comment "
 	  <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 @@ PLIST_SUB+=		NLS="@comment "
 
     <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 @@ PLIST_SUB+=		NLS="@comment "
       <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 @@ PLIST_SUB+=		NLS="@comment "
 	<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 @@ USE_XORG=	x11 xpm</programlisting>
     <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 @@ USE_XORG=	x11 xpm</programlisting>
 	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 @@ USE_XORG=	x11 xpm</programlisting>
 	  <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 @@ USE_XORG=	x11 xpm</programlisting>
     <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 @@ USE_XORG=	x11 xpm</programlisting>
 
       <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 @@ USE_XORG=	x11 xpm</programlisting>
 	  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 @@ USE_XORG=	x11 xpm</programlisting>
       </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 @@ USE_XORG=	x11 xpm</programlisting>
 	  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 @@ USE_XORG=	x11 xpm</programlisting>
       <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 @@ PLIST_SUB+=	QT_INCDIR=${QT_INCDIR_REL} \
 
       <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 @@ USE_QT5=	buildtools_build</programlistin
 	  <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 @@ USE_QT5=	buildtools_build</programlistin
 	<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 @@ USE_QT5=	buildtools_build</programlistin
 	  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 @@ USE_QT4=	moc_build qmake_build rcc_build
     <sect2 xml:id="java-variables">
       <title>Variable Definitions</title>
 
-      <para>If your port needs a Java&trade; Development Kit
-	(JDK&trade;) to either build, run or even extract the
-	distfile, then it should define
+      <para>If the port needs a Java&trade; Development Kit
+	(<acronym>JDK</acronym>&trade;) 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 @@ USE_QT4=	moc_build qmake_build rcc_build
 	  <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 	      <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 
 	    <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 	  <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 	    <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 
 	    <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 @@ USE_QT4=	moc_build qmake_build rcc_build
 	</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 @@ USE_QT4=	moc_build qmake_build rcc_build
 
 	    <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 @@ USE_QT4=	moc_build qmake_build rcc_build
       <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

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409161201.s8GC1UPW026876>