Rewrite the PREFIX and DESTDIR section for clarity.

Expand the DESKTOP_ENTRIES section, including clarifications and
instructions on installing predefined .desktop files.

Reviewed by:	eadler@, Benjamin Kaduk (earlier version of PREFIX)
Reviewed by:	eadler@ (earlier version of DESKTOP_ENTRIES)
Approved by:	gjb (mentor)

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -5824,15 +5824,48 @@ USE_XORG=	x11 xpm</programlisting>
       <sect2 id="desktop-entries">
 	<title>Desktop entries</title>
 
-	<para>Desktop Entries (<ulink
+	<para>Desktop entries (<ulink
-	    url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Freedesktop
+	    url="http://standards.freedesktop.org/desktop-entry-spec/latest/">a
-	    standard</ulink>) can be easily created in your port using
+	    Freedesktop standard</ulink>) provide a way to
-	  <makevar>DESKTOP_ENTRIES</makevar> variable.  These entries
+	  automatically adjust desktop features when a new program is
-	  do show up in application menus of compliant desktop
+	  installed, without requiring user intervention.  For
-	  environments like GNOME or KDE.  The
+	  example, newly-installed programs automatically appear in
-	  <filename>.desktop</filename> file will be created,
+	  the application menus of compatible desktop environments.
-	  installed, and added to the <filename>pkg-plist</filename>
+	  Desktop entries originated in the
-	  automatically.  Syntax is:</para>
+	  <application>GNOME</application> desktop environment, but
+	  are now a standard and also work with
+	  <application>KDE</application> and
+	  <application>Xfce</application>.  This bit of automation
+	  provides a real benefit to the user, and desktop entries are
+	  encouraged for applications which can be used in a desktop
+	  environment.</para>
+
+	<sect3>
+	  <title>Using Predefined <filename>.desktop</filename>
+	    Files</title>
+
+	  <para>Ports that include predefined
+	    <filename>*.desktop</filename> files should
+	    include those files in <filename>pkg-plist</filename>
+	    and install them in the
+	    <filename><makevar>&dollar;LOCALBASE</makevar>/share/applications</filename>
+	    directory.  The <link
+	      linkend="INSTALL-MACROS"><makevar>INSTALL_DATA</makevar>
+	      macro</link> is useful for installing these
+	    files.</para>
+	</sect3>
+
+	<sect3 id="desktop-entries-macro">
+	  <title>Creating Desktop Entries with the
+	    <makevar>DESKTOP_ENTRIES</makevar> Macro</title>
+
+	  <para>Desktop entries can be easily created for applications
+	  by using the <makevar>DESKTOP_ENTRIES</makevar> variable.
+	  A file named
+	  <filename><replaceable>name</replaceable>.desktop</filename>
+	  will be created, installed, and added to the
+	  <filename>pkg-plist</filename> automatically.  Syntax
+	  is:</para>
 
 	<programlisting>DESKTOP_ENTRIES=	"NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting>
 
@@ -5840,8 +5873,18 @@ USE_XORG=	x11 xpm</programlisting>
 	  <ulink
 	    url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop
 	    website</ulink>.  <makevar>StartupNotify</makevar>
-	  indicates whether the application will clear the status in
+	  indicates whether the application is compatible with
-	  a startup notification-aware environment.</para>
+	  <emphasis>startup notifications</emphasis>.  These are
+	  typically a graphic indicator like a clock that appear at
+	  the mouse pointer, menu, or panel to give the user an
+	  indication when a program is loading.  A program that is
+	  compatible with startup notifications clears the indicator
+	  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 <makevar>StartupNotify</makevar> set to
+	  <literal>false</literal> so the indicator is not shown at
+	  all.</para>
 
 	<para>Example:</para>
 
@@ -5849,6 +5892,8 @@ USE_XORG=	x11 xpm</programlisting>
 			"${DATADIR}/xtra/graf/tome-128.png" \
 			"tome -v -g" "Application;Game;RolePlaying;" \
 			false</programlisting>
+
+	</sect3>
       </sect2>
     </sect1>
 
@@ -9811,49 +9856,47 @@ as .putsy.conf and edit it.</programlisting>
       <title><makevar>PREFIX</makevar> and
 	<makevar>DESTDIR</makevar></title>
 
-      <para><makevar>PREFIX</makevar> determines the location where
+      <para><makevar>PREFIX</makevar> determines where the port will
-	the port will install.  It is usually
+	be installed.  It defaults to <filename>/usr/local</filename>,
-	<filename>/usr/local</filename> or <filename>/opt</filename>,
+	but can be set by the user to a custom path like
-	but can be set to a custom path.  Your port must respect this
+	<filename>/opt</filename>.  Your port must
-	variable.</para>
+	respect the value of this variable.</para>
 
-      <para><makevar>DESTDIR</makevar>, if set by user, determines the
+      <para><makevar>DESTDIR</makevar>, if set by the user, determines the
-	complete alternative environment, usually a jail, or an
+	complete alternative environment, usually a jail or an
-	installed system mounted elsewhere than
+	installed system mounted somewhere other than
 	<filename>/</filename>. A port will actually install into
-	<makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar>, and
+	<filename><makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar></filename>, and
 	register with the package database in
-	<makevar>DESTDIR</makevar>/var/db/pkg.  As
+	<filename><makevar>DESTDIR</makevar>/var/db/pkg</filename>.  As
 	<makevar>DESTDIR</makevar> is handled automatically by the
-	ports infrastructure via calling &man.chroot.8;, you do not
+	ports infrastructure with &man.chroot.8;, you do not
 	need any modifications or any extra care to write
 	<makevar>DESTDIR</makevar>-compliant ports.</para>
 
       <para>The value of <makevar>PREFIX</makevar> will be set
-	to <makevar>LOCALBASE</makevar> (default
+	to <makevar>LOCALBASE</makevar> (defaulting to
 	<filename>/usr/local</filename>).  If
 	<makevar>USE_LINUX_PREFIX</makevar> is set,
 	<makevar>PREFIX</makevar> will be <makevar>LINUXBASE</makevar>
-	(default <filename>/compat/linux</filename>).</para>
+	(defaulting to <filename>/compat/linux</filename>).</para>
 
-      <para>Avoiding the hard-coding of
+      <para>Avoiding hard-coded <filename>/usr/local</filename>
-	<filename>/usr/local</filename> or
+	paths in the source
-	<filename>/usr/X11R6</filename> anywhere in the source will
+	makes the port much more flexible and able to cater to the
-	make the port much more flexible and able to cater to the
+	needs of other sites.
-	needs of other sites.  For X ports that use
+	Often, this can be accomplished
-	<command>imake</command>, this is automatic; otherwise, this
+	by simply replacing occurrences of
-	can often be done by simply replacing the occurrences of
+	<filename>/usr/local</filename>
-	<filename>/usr/local</filename> (or
+	in the port's various <filename>Makefile</filename>s
-	<filename>/usr/X11R6</filename> for X ports that do not use
+	with <literal>&dollar;{PREFIX}</literal>.  This variable is
-	imake) in the various <filename>Makefile</filename>s in the
-	port to read <makevar>${PREFIX}</makevar>, as this variable is
 	automatically passed down to every stage of the build and
 	install processes.</para>
 
       <para>Make sure your application is not installing things in
 	<filename>/usr/local</filename> instead of
-	<makevar>PREFIX</makevar>. A quick test for this is to do this
+	<makevar>PREFIX</makevar>.  A quick test for such hard-coded
-	is:</para>
+	paths is:</para>
 
       <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>
 
@@ -9861,31 +9904,31 @@ as .putsy.conf and edit it.</programlisting>
 	<makevar>PREFIX</makevar>, the package creation process will
 	complain that it cannot find the files.</para>
 
-      <!-- XXX This paragraph is confusing. -->
+      <para>This test will not find hard-coded paths inside the
-      <para>This does not test for the existence of internal
+	port's files, nor will it verify that
-	references, or correct use of <makevar>LOCALBASE</makevar> for
+	<makevar>LOCALBASE</makevar> is being used to correctly refer
-	references to files from other ports.  Testing the
+	to files from other ports.  The temporarily-installed port in
-	installation in <filename>/var/tmp/`make -V
+	<filename>/var/tmp/`make -V PORTNAME`</filename> should be
-	  PORTNAME`</filename> to do that while you have it installed
+	tested for proper operation to make sure there
-	would do that.</para>
+	are no problems with paths.</para>
 
-      <para>The variable <makevar>PREFIX</makevar> can be reassigned
+      <para><makevar>PREFIX</makevar> should not be set explicitly
-	in your <filename>Makefile</filename> or in the user's
+	in a port's <filename>Makefile</filename>.  Users installing
-	environment. However, it is strongly discouraged for
+	the port may have set <makevar>PREFIX</makevar> to a custom
-	individual ports to set this variable explicitly in the
+	location, and the port should respect that setting.</para>
-	<filename>Makefile</filename>s.</para>
 
-      <para>Also, refer to programs/files from other ports with the
+      <para>Refer to programs and files from other ports with the
 	variables mentioned above, not explicit pathnames.  For
 	instance, if your port requires a macro
-	<literal>PAGER</literal> to be the full pathname of
+	<literal>PAGER</literal> to have the full pathname of
-	<command>less</command>, use the compiler flag:</para>
+	<command>less</command>, do not use a literal path of
+	<filename>/usr/local/bin/less</filename>.  Instead, use
+	<literal>&dollar;{LOCALBASE}</literal>:</para>
 
       <programlisting>-DPAGER=\"&dollar;{LOCALBASE}/bin/less\"</programlisting>
 
-      <para>instead of
+      <para>The path
-	<literal>-DPAGER=\"/usr/local/bin/less\"</literal>.  This way
+	with <makevar>LOCALBASE</makevar> is more likely to still work if the system
-	it will have a better chance of working if the system
 	administrator has moved the whole
 	<filename>/usr/local</filename> tree somewhere else.</para>
     </sect1>