Callout style + error

[Karsten Wade]

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?

- Karsten
> 
> P.S.  I actually hadn't realized that docbook-style-dsssl provided stock
> callout images until I was about to launch this email:
> 
> $ ls /usr/share/sgml/docbook/dsssl-stylesheets-*/images/callouts/
> 1.gif  10.gif  2.gif  3.gif  4.gif  5.gif  6.gif  7.gif  8.gif  9.gif
> 
> Thanks,
> James Laska
> 
> On Mon, 2005-05-16 at 11:46 -0500, Thomas Jones wrote:
> > Thomas Jones wrote:
> > 
> > > I've attempted to determine some information about the callout images 
> > > used in fedora's documentation --- to no avail.
> > >
> > > So I bow to the mercy of the mailinglist and ask for help. What is the 
> > > standardized styling and location of the callout images? I have built 
> > > custom callouts for current development of my xml sources; but didn't 
> > > want to stray from standard practice.
> > >
> > > Also I came across a peculiar problem declaring the xsl parameter 
> > > using xmlto. For some reason due to the java implemented processor, I 
> > > am getting a ColumnWidth error. The only alteration performed was to 
> > > include an extension stylesheet for the declaration of a new image 
> > > path. :-(
> > >
> > > Admittedly, I have never used xmlto and prefer xsltproc. However it 
> > > might be a moot point if the standard path is acceptable.
> > >
> > > Thanks,
> > > Thomas
> > >
> > Bump.
> > 
> 
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
-------------- 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/20050516/6edd7752/attachment.bin