From owner-freebsd-doc@FreeBSD.ORG  Wed Feb  5 03:15:55 2014
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: freebsd-doc@FreeBSD.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTPS id CC2ADC19;
 Wed,  5 Feb 2014 03:15:55 +0000 (UTC)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by mx1.freebsd.org (Postfix) with ESMTPS id 801F115E9;
 Wed,  5 Feb 2014 03:15:55 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.7/8.14.7) with ESMTP id s153FsYZ042624;
 Tue, 4 Feb 2014 20:15:54 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id s153FsUV042621;
 Tue, 4 Feb 2014 20:15:54 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Date: Tue, 4 Feb 2014 20:15:54 -0700 (MST)
From: Warren Block <wblock@wonkity.com>
To: nemysis <nemysis@FreeBSD.org>
Subject: Re: docs/186466: [PATCH] book.xml Stripping Binaries and Shared
 Libraries
In-Reply-To: <201402042250.s14MoTPI080268@oldred.freebsd.org>
Message-ID: <alpine.BSF.2.00.1402042005420.42444@wonkity.com>
References: <201402042250.s14MoTPI080268@oldred.freebsd.org>
User-Agent: Alpine 2.00 (BSF 1167 2008-08-23)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3
 (wonkity.com [127.0.0.1]); Tue, 04 Feb 2014 20:15:54 -0700 (MST)
Cc: freebsd-doc@FreeBSD.org, freebsd-gnats-submit@FreeBSD.org
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc/>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Wed, 05 Feb 2014 03:15:55 -0000

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>.