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/