Re: DOCBOOK-APPS: how to comment programlisting or source code

[Bob Stayton <bobs at caldera dot com>]

On Thu, Aug 22, 2002 at 01:54:26PM -0400, Robert P. J. Day wrote:
> On Thu, 22 Aug 2002, Bob Stayton wrote:
> 
> > On Thu, Aug 22, 2002 at 07:35:44AM -0400, Robert P. J. Day wrote:
> > > 
> > >   i asked this question before and remember getting a response, and
> > > managed to lose it somewhere.
> > > 
> > >   for the time being, i'm just generating HTML from my docbook source,
> > > writing courseware manuals.  i'd like to comment the lines of source
> > > code that i include (most likely in a <programlisting>) so that the
> > > comments are nicely lined up (left-justified) and in italics.
> > > 
> > >   i know -- i can't actually say italics, so i'd probably tag the
> > > comments as, what, lineannotation?  but it's the lining up that i don't 
> > > know how to do.
> > > 
> > >   any helpful hints?  i'm still looking for that previous response ...
> > > argh.
> > 
> > Since programlisting is a verbatim block, can't you
> > just line  up your annotations manually as you write them? 
> > Maybe I'm not understanding what you are trying to do.
> > If you are doing long comments that wrap, perhaps you could
> > use callouts?
> 
> it seems like there's two ways to look at this, and one of them may
> actually be pretty easy.
> 
> given that a programlisting is generated for HTML using a fixed-width 
> font,  i can at least left-justify the lineannotations, regardless of
> what font they use, right?  i'm planning on having them printed in 
> italics (currently, the default seems to be the same fixed-width font
> used for the rest of the programlisting).
> 
> however, what if i wanted to tighten up a programlisting by changing 
> to a variable-width font?  then the above won't work.  i'm not saying
> i'm all keen on doing this, just considering the potential.

Then I'd use callouts and not try to do any alignment.
 
> as it stands, if i'm happy with the fixed-width font, as long as i
> left justify the annotations themselves, the font i use for them
> shouldn't matter, right?
 
Right.
-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com