Callout style + error

[Paul W. Frields]

On Mon, 2005-05-16 at 10:53 -0700, Karsten Wade wrote:
> On Mon, 2005-05-16 at 13:32 -0400, James Laska wrote:
> > I was playing with the look and feel of callout sections a few weeks
> > back.  Not only don't we have the fedora-style images, but I noticed
> > that if you are showing command blocks that have cut'n'paste style code,
> > the callout numbers interfere with your cut'n'paste. 
> > 
> > I had a large enough code block that I wanted to use callout's to break
> > it down and explain various parts ... it just killed the
> > cut'n'pastability once added.
> > 
> > Thoughts?
> 
> There's probably a rule of thumb in there somewhere, something like
> this:
> 
> 1. If the block of code is big, try to break it down to smaller pieces
> 2. If that doesn't work, use callouts
> 3. If you are pasting the code often enough that callouts don't work,
> try going back to 1.
> 4. If all else fails, try documenting inside the actual code using
> comment marks.
> 5. If you still need callouts, try working them into the commented
> sections, which are less subject to change.
> 
> With 4., you can have the code the same in the source and in the docs.
> 
> Would something like that work?

This is what I had in mind when I opined that callouts should probably
be a last resort.  For all the wonderful features that DocBook has, some
of them are more useful as shorthand for specialized usage.  There's
*almost* always a better way to achieve the same end -- and better
readability -- with elegant $LANG instead of cool code.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050517/e7660eb5/attachment.bin