docs/186466: [PATCH] book.xml Stripping Binaries and Shared Libraries

[Warren Block]

On Tue, 4 Feb 2014, nemysis wrote:

> Index: en_US.ISO8859-1/books/porters-handbook/book.xml
> ===================================================================
> --- en_US.ISO8859-1/books/porters-handbook/book.xml	(revision 43779)
> +++ en_US.ISO8859-1/books/porters-handbook/book.xml	(working copy)
> @@ -5096,8 +5096,16 @@
> 	  example:</para>
>
> 	<programlisting>post-install:
> -	  ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting>
> +	  ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/${PORTNAME}</programlisting>
>
> +	<para>If you need to strip more files, here shared libraries.
> +	 For example:</para>

Please try to avoid the informal "you".
(http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-be-clear)

Suggestion:

   <para>When more than one file needs to be stripped, like several
     shared libraries, loop through them:</para>

> +
> +	<programlisting>post-install:
> +	 .for l in geometry media body track world
> +	 ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0
> +	 .endfor</programlisting>
> +
> 	<para>Use the &man.file.1; command on the installed executable
> 	  to check whether the binary is stripped or not.  If it does

It's a bit redundant.  Suggestion:

   <para>Use &man.file.1; on the installed executable
     to check whether it has been stripped.

> 	  not say <literal>not stripped</literal>, it is stripped.

That last sentence has a double negative that makes it confusing. 
Assuming it is there to tell the port programmer what string to expect:

   Binaries that have not been stripped will be reported by &man.file.1;
   as <literal>not stripped</literal>.