- add some notes about ECHO_CMD and ECHO_MSG

Submitted by: gabor@#bsddocs
Requested by: netchild
Inspired by: ports/100556
Approved by: trhodes (mentor), keramida (mentor)

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

@@ -3514,8 +3514,8 @@ PKGNAMESUFFIX=  ${RESOLUTION}
 RESOLUTION?=   300
 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
        ${RESOLUTION} != 300 && ${RESOLUTION} != 400
-       @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
-       @${ECHO} "Possible values are: 118, 240, 300 (default) and 400."
+       @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
+       @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."
        @${FALSE}
 .endif</programlisting>
 
@@ -7188,6 +7188,25 @@ etc/orbit.conf.sample
 	  after a &man.pkg.add.1; or to display licensing
 	  information.</para>
 
+	<para>When some lines about the build-time knobs or warnings
+	  have to be displayed, use <makevar>ECHO_MSG</makevar>.  The
+	  <filename>pkg-message</filename> file is only for
+	  post-installation steps.  Likewise, the distinction between
+	  <makevar>ECHO_MSG</makevar> and <makevar>ECHO_CMD</makevar>
+	  should be kept in mind.  The former is for printing
+	  informational text to the screen, while the latter is for
+	  command pipelining.</para>
+
+	<para>A good example for both can be found in
+	  <filename>shells/bash2/Makefile</filename>:</para>
+
+	<programlisting>update-etc-shells:
+	@${ECHO_MSG} "updating /etc/shells"
+	@${CP} /etc/shells /etc/shells.bak
+	@( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \
+		${ECHO_CMD} ${PREFIX}/bin/bash) &gt;/etc/shells
+	@${RM} /etc/shells.bak</programlisting>
+
 	<note>
 	  <para>The <filename>pkg-message</filename> file does not need to be
 	    added to <filename>pkg-plist</filename>.  Also, it will not get