This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: ambiguity in <xref> regarding cross-reference text


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

/ "Robert P. J. Day" <rpjday@mindspring.com> was heard to say:
|   again, nitpicky, but in the online TDG 2.0.7, in the explanation
| of <xref>, we read:
|
|   "... If the Endterm attribute is specified, the content of the
|   element pointed by by Endterm must be used as the text of the
|   cross-reference ... If the object pointed to has a specified
|   XRefLabel, that should be used as the cross-reference text."
|
|   and if both happen to be true?  it's not clear from the <xref>
| page which takes precedence.

This section now reads:

<refsect2 id="dbreproc.xref"><title>Processing expectations</title>

<para>Under ordinary circumstances, the <sgmltag>xref</sgmltag>
points to the some element with its
<sgmltag class="attribute">linkend</sgmltag> attribute and the processing system
generates appropriate cross reference text. There are three
ways for the author to influence the generated text:</para>

<orderedlist>
<listitem>
<para>If the <sgmltag class='attribute'>endterm</sgmltag> attribute is specified
on <sgmltag>xref</sgmltag>, the
content of the element pointed to by <sgmltag class='attribute'>endterm</sgmltag>
will be used as the text of the cross-reference.
</para>
</listitem>

<listitem>
<para>Otherwise, if the object <emphasis>pointed to</emphasis> has a
specified <sgmltag class='attribute'>XRefLabel</sgmltag>, the content of
that attribute will be used as the cross-reference text.
</para>
</listitem>

<listitem>
<para>Finally, the author may specify a keyword (or other information) in the
<sgmltag class="attribute">xrefstyle</sgmltag> attribute. Unlike
<sgmltag class="attribute">endterm</sgmltag> and
<sgmltag class="attribute">xreflabel</sgmltag> which have rigid semantics,
the content of the <sgmltag class="attribute">xrefstyle</sgmltag> attribute is simply
additional information for the processing system. What effect it has, if any,
is dependent on the processing system.</para>
</listitem>
</orderedlist>

</refsect2>

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | Taste ripens at the expense of
http://www.oasis-open.org/docbook/ | happiness.--Jules Renard
Chair, DocBook Technical Committee |
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+DhhMOyltUcwYWjsRApZmAJ4hmZ6lNiWRDzR/AXnRLO1o4im2ZQCeJ57i
RlfasZD4u0J1v9tWU6F138U=
=7v8Q
-----END PGP SIGNATURE-----


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]