Bad Example Formatting?

[Warren Block]

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.