DOCBOOK: Proposal: coref

[Norman Walsh <ndw at nwalsh dot com>]

The <co/> element allows one to insert callouts into a document:

<programlisting>
  Some text<co id="foo"/> here
  And more here<co id="bar"/>
</programlisting>

This creates numbered (or otherwise identified) marks in the listing
for later cross referencing.

The areaspec version offers a feature that cannot be achived with the
<co/> element, namely the ability to duplicate a given mark in several
locations:

<programlistingco>
<areaspec>
<area coords="11 12" id="use"/>
<areaset coords="" id="xreq">
<area coords="9" id="require1"/>
<area coords="10" id="require2"/>
</areaset>
</areaspec>
<programlisting>...</programlisting>
</programlistingco>

In this example, the "require1" and "require2" marks will have the
same number (or identifier).

Since processing arespec is considerably more difficult than processing
<co/> elements, I propose that DocBook add a <coref> element:

<!ENTITY % coref.module "INCLUDE">
<![%coref.module;[
<!ENTITY % local.coref.attrib "">
<!-- COREF is a cross reference to another CO. -->
<!ENTITY % coref.role.attrib "%role.attrib;">

<!ENTITY % coref.element "INCLUDE">
<![%coref.element;[
<!ELEMENT coref EMPTY>
<!--end of coref.element-->]]>

<!ENTITY % coref.attlist "INCLUDE">
<![%coref.attlist;[
<!ATTLIST coref
		%linkendreq.attrib;
		%label.attrib;
		%common.attrib;
		%coref.role.attrib;
		%local.coref.attrib;
>
<!--end of coref.attlist-->]]>
<!--end of coref.module-->]]>

The semantics of coref are analogous to the semantics of footnoteref.
It creates a callout with the same mark as the <co/> that it points to.
It is an error for the linkend attribute of coref to point to anything
except a co.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Sites disappear; others are
http://www.oasis-open.org/docbook/ | created. That nasty little railway
Chair, DocBook Technical Committee | station, devoid of taste and
                                   | style, becomes an element of
                                   | beauty in the landscape which
                                   | first made it ugly.--R\'emy De
                                   | Gourmont

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org