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/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
