DOCBOOK: Re: confused about callouts

[Norman Walsh <ndw@nwalsh.com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

[ Follow-ups to docbook-apps, please. ]

/ "Robert P. J. Day" <rpjday@mindspring.com> was heard to say:
|   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"/>

You can't use "/" characters in ID values. (I'm concerned that you may
not be using a validating parser. If you aren't, there are a whole
range of errors that may be going undetected. It's quite possible that
some stylesheet anomalies that you're experiencing are related to bad
markup.)

| the HTML for this section can be viewed at
| www.linux-migration.org/ch02s03.html, for which i have a

Hmm. It seems to have moved in the intervening weeks. Sorry I've been delayed.

| 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.

Browser bug?

| 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?

Callouts are typically labelled "1", "2", "3", etc. in the order that
they appear. If you want them labelled "Fred", "Barney" and "Wilma"
instead, use the label attribute.

| 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?

Now that's an interesting question. The documentation for the callout element
has probably fallen behind the times. I think it predates the existence of
the "co" element. I think it makes sense for the callout element to point to
a co. Alas, it makes "arearefs" a slightly confusing attribute name.

In fact, I seem to have already updated the documentation for the next
release:

<varlistentry><term>arearefs</term>
<listitem>
<para>
<sgmltag class="attribute">AreaRefs</sgmltag> must point to one or more
callouts. Callouts can be identified with
<sgmltag>Area</sgmltag> or <sgmltag>AreaSet</sgmltag> elements in a
<sgmltag>GraphicCO</sgmltag>,
<sgmltag>MediaObjectCO</sgmltag>,
<sgmltag>ProgramListingCO</sgmltag>, or
<sgmltag>ScreenCO</sgmltag> element or with a simple
<sgmltag>CO</sgmltag> element in a number of other environments.
These callouts identify the
portions of the object described by this <sgmltag>Callout</sgmltag>.
</para>
</listitem>
</varlistentry>

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | The greatest of all secrets is
http://www.oasis-open.org/docbook/ | knowing how to reduce the force of
Chair, DocBook Technical Committee | envy.--Cardinal De Retz
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+DhnUOyltUcwYWjsRAvc2AJ0U2/sd4oz+U6X0mY0BVLDJYtSIzgCgkyxT
tO3BwaDGRQ8vgHGNF82oIaU=
=5mtG
-----END PGP SIGNATURE-----