Re: DOCBOOK: confused about callouts

[Bob Stayton <bobs@caldera.com>]

On Mon, Nov 25, 2002 at 06:21:28PM -0500, Robert P. J. Day wrote:
> 
>   i have a section of a much larger docbook document, with the following
> <screen> element and <co> callout marks:
> 
>     <screen>
> <filename>/etc/passwd</filename>                     <co id="/etc/passwd"/>
> <filename>/etc/shadow</filename>                     <co id="/etc/shadow"/>
> <filename>/etc/group</filename>                      <co id="/etc/group"/>
> 
> <filename>/etc/profile</filename>                    <co id="/etc/profile"/>
>   <filename>/etc/profile.d/*.sh</filename>           <co id="/etc/profile.d"/>
> 
> <filename>~/.bash_profile</filename>                 <co id="bash_profile"/>
> <filename>~/.bashrc</filename>                       <co id="bashrc"/>
>   <filename>/etc/bashrc</filename>                   <co id="/etc/bashrc"/>
>     </screen>
>     <calloutlist>
> 
>      <callout arearefs="/etc/passwd">
>      <para><filename>/etc/passwd</filename> defines, among other
>       things, the username, numeric UID and GID of the user, the
>       home directory and the login shell.   For security reasons,
>       the encrypted password is no longer stored in this file.</para>
>      </callout>
> 
>      <callout arearefs="/etc/shadow">
>      <para><filename>/etc/shadow</filename> represents a more secure
>       place to store things like the encrypted password, password aging
>       information and more.  (This is the only file in this list of files
>       that requires root privilege to display.)</para>
>      </callout>
> 
>      ... etc etc ...
>     </calloutlist>
> 
> the HTML for this section can be viewed at
> www.linux-migration.org/ch02s03.html, for which i have a
> few questions.
> 
> 1) trivial issue, but viewing with mozilla and galeon, there is
>    an apparent line feed between the numbers and the assoc. text
>    in the callout list itself.  using IE, however, it looks
>    correct -- no mysterious line feed.

Sounds like a browser bug.  By default, the calloutlist
is formatted as a two-column table.  If a table entry
starts with <p>, do such table entries always get space
above in those browsers?  You might try setting the
stylesheet parameter 'callout.list.table' to 0 so the
callout list is formatted as a <DL> list, but that
might have the same problem in the <DD> part.
 
> 2) a <co> element has both an id= and a label= attribute.
>    clearly, i use the id attribute for the linking -- i'm not
>    sure what the label attribute is for.  the online TDG states
>    that it "specifies an identifying number or string that may
>    be used in presentation."  
> 
>    any hints as to what the label attribute is used for?

I think the key phrase is "may be used".  
It doesn't appear to be used at all in Norm's stylesheets.

> 3) the online TDG also documents that a <callout> has the
>    arearefs attribute, which is exactly what i use above to 
>    refer back to the appropriate <co>.
> 
>    however, the documentation for the <callout> element states
>    that the "arearefs" attribute "must point to one or more Areas
>    or AreaSets".  but mine don't -- they refer to simple
>    <co> elements.  
> 
>    am i misreading something here?

No, that statement is out of date.  The arearefs value can
also point to a <co> element.

You can also link in the other direction by putting an id
on your callout elements and a matching linkend in the co element.
 

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com