From owner-freebsd-doc@FreeBSD.ORG  Tue Jul  1 13:13:18 2014
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: doc@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTPS id 16F5FD5E
 for <doc@freebsd.org>; Tue,  1 Jul 2014 13:13:18 +0000 (UTC)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
 (Client CN "wonkity.com", Issuer "wonkity.com" (not verified))
 by mx1.freebsd.org (Postfix) with ESMTPS id BA4372FC7
 for <doc@freebsd.org>; Tue,  1 Jul 2014 13:13:17 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.9/8.14.9) with ESMTP id s61DD8HZ077046
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO);
 Tue, 1 Jul 2014 07:13:08 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id s61DD8EO077041;
 Tue, 1 Jul 2014 07:13:08 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Date: Tue, 1 Jul 2014 07:13:08 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: Eitan Adler <lists@eitanadler.com>
Subject: Re: Bad Example Formatting?
In-Reply-To: <CAF6rxg=j+siA4cqo9gpof9d+BogwYr+ZUD6jMMhdMNnEF4XVxw@mail.gmail.com>
Message-ID: <alpine.BSF.2.11.1407010656160.76854@wonkity.com>
References: <CAF6rxg=j+siA4cqo9gpof9d+BogwYr+ZUD6jMMhdMNnEF4XVxw@mail.gmail.com>
User-Agent: Alpine 2.11 (BSF 23 2013-08-11)
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, 01 Jul 2014 07:13:08 -0600 (MDT)
Cc: doc@freebsd.org
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.18
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: Tue, 01 Jul 2014 13:13:18 -0000

On Tue, 1 Jul 2014, Eitan Adler wrote:

> Is there a way to signify good example code and bad example code?
>
> For example the latter has a light red background, and clearly says
> "don't do this" while the former has a light green background with a
> big checkmark?

I don't know if we have a way to do that short of putting it in a 
<caution> or <warning>, but I have learned that it's a mistake to show 
bad examples at all.  Way too many people only look at the examples and 
do not read the explanatory text.  Seemingly all of them.

Given that, my preference would be to have the text explain what to 
avoid (and why), the right way to do it, and then show the right way:

   <para>Do not set permissions to <literal>777</literal>!  Use only
     the minimum value necessary.  Only the read and execute permissions
     for the file owner are needed here:</para>

   <screen>&prompt.root; <userinput>chmod 600 example.sh</userinput></screen>

If an example of the wrong way is shown, explaining why it is wrong is 
usually needed.  But the explanation can make it even more of a 
distraction.