Lana Brindley wrote:
On 10/01/2010 08:03 AM, Andrew Ross wrote:
----- "Ruediger Landmann"<r.landm...@redhat.com> wrote:
On 09/30/2010 03:16 PM, Misty Stanley-Jones wrote:
5. Programlistings inside of notes, warnings, or infos look
terrible.
Screenshot attached.
<devils_advocate>
Do we want to have programlistings inside note/warning tags? Perhaps
the horrid colour scheme was devised by mother nature as a natural
defence mechanism...
</devils_advocate>
I'll rise to the bait. Sometimes you need to. I've come across it
several times where you have an admonition something like this:
<warning>
<para>Be careful when doing <command>X</command>, as it can cause
wide-spread death and destruction. To prevent the mutiliation of friends
and loved ones, add the following line to the configuration:
</para>
<programlisting>
TortureFriends = 0
</programlisting>
</warning>
The point being, that sometimes the admonition is directly relevant to a
program listing (or <screen>) that just wouldn't fit in the main body of
text. I agree that it's not ideal, but there are definitely situations
where you can't write around it. In those cases, it would be nice if the
brand wasn't working against us.
The problem when you make up examples are that they almost never carry
your point well. It's quite easy for anyone to reply "your argument is
flawed, such an important point should be part of your main text" or
"admonitions are for unexpected behavior, a setting like this should be
part of the main documentation and if the warning is still required it
should contain a link parameter in the main text." etc, etc.
A real example where you couldn't write around it would carry much more
weight and prevent such responses.
Cheers, Jeff.
--
Jeff Fearn <jfe...@redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY
_______________________________________________
publican-list mailing list
publican-list@redhat.com
https://www.redhat.com/mailman/listinfo/publican-list
Wiki: https://fedorahosted.org/publican
