Citation proposal RFE #810932

[Michael Smith <smith@xml-doc.org>]

Forwarding another reply that didn't make it to the TC list.

  Date:         Wed, 17 Dec 2003 23:40:38 +0100
  Reply-To:     Development of an XML core vocabulary for bibliographic
                references <BIBLIOFILE@LISTS.UCC.IE>
  Sender:       Development of an XML core vocabulary for bibliographic
                references <BIBLIOFILE@LISTS.UCC.IE>
  From:         Markus Hoenicka <markus.hoenicka@MHOENICKA.DE>
  Subject:      Re: [docbook-tc] info on citation item
  Comments: To: Norman Walsh <ndw@nwalsh.com>
  Comments: cc: docbook-tc@lists.oasis-open.org
  In-Reply-To:  <877k0vqg5o.fsf@nwalsh.com>
  Content-Type: text/plain; charset=us-ascii

Hi Norm,

Norman Walsh writes: 

> Are you suggesting that the other proposed changes are no longer needed?

I wouldn't say so, but my impression from the last TC meeting was that
you were reluctant to overload DocBook with too many things that
essentially only scholars will use. The biblioref element allowed
wherever xref is allowed covers 80% of our needs, that's why we cut down
the proposal to just that. If we can get more, we'll be delighted.

> > Improved citation support in DocBook > >
> > ==================================== > [...] > > Mainframe computers
> > have gained widespread acceptance as a replacement > > for slide
> > rules (Miller 1999; Doe 2000). > > ^---------^ > > pointer to
> > reference 1 > > ^------^ > > pointer to reference 2 > > > >
> > ^---------------------^ > > citation > > What exactly is your
> > proposed markup for this example? >

<para>Mainframe computers have gained widespread acceptance as a
replacement for slide rules <citation><biblioref linkend="Miller1999"
/><biblioref linkend="Doe2000" /></citation>.<para>

> > While it is possible to use the existing <xref> element in a > >
> > <citation> to encode pointers to entries in a <bibliography> (please
> > > > note the striking identity in the semantics of a pointer and
> > > > <xref>), > > the <xref> element is not suitable to carry
> > > > additional bibliographic > > information that applies only to
> > > > the current citation. For example, if > > the bibliographic
> > > > reference describes a book, a citation may > > specifically
> > > > refer to a chapter or to a range of pages in that book. > > I'm
> > > > reluctant to start adding "typed" cross references, but I see
> > > > your > point. >

I appreciate that you see my point. This is the core part of our
proposal. It would hurt to lose this one.

> > Think of the proposed <biblioref> as an extension of <xref> that
> > uses > > attributes to specify additional bibliographic > >
> > information. Applications are expected to process this element in a
> > > > way that uses both the information provided in the bibliographic
> > > > > > reference pointed to (e.g. a citation key, the number of the
> > > > > > entry in > > the bibliography, or an author/year
> > > > > > representation of the reference) > > and the additional
> > > > > > information provided in the attributes. If a > > <citation>
> > > > > > contains more than one <biblioref>, processing applications
> > > > > > > > are expected to render them as a unit. For example,
> > > > > > > > pointers to > > consecutive entries in a numbered
> > > > > > > > bibliography may be rendered as > > "[1-3]". > > Can you
> > > > > > > > show me an example where this would be the case,
> > > > > > > > including the > citation markup actually used that
> > > > > > > > generates [1-3]? > <para>Mainframe computers have gained
> > > > > > > > widespread acceptance as a replacement for slide rules
> > > > > > > > <citation><biblioref linkend="Miller1999" /><biblioref
> > > > > > > > linkend="Doe2000" /><biblioref linkend="Foo2001"
> > > > > > > > /></citation>.<para>

Scientific journals use two different types of citations: author/name
based or numeric. The latter is formatted either as numbers in brackets
or as superscripts. The numbers of course refer to the number of the
reference in the bibliography. Most journals fold consecutive numbers
into a range, i.e. [1-3] instead of [1,2,3]. The example above can be
formatted like this:

Mainframe computers have gained widespread acceptance as a replacement
for slide rules [1-3].

The corresponding author/name representation of the same markup looks
like this:

Mainframe computers have gained widespread acceptance as a replacement
for slide rules (Miller 1999; Doe 2000; Foo 2001).

> I would have thought, actually, that the biblioref implied the > citation if no other text was required inside the citation. But maybe > that's just laziness on my part. >

You mean:

<biblioref linkend="Miller1999" unit="chapter" start="2" />

but

<citation><biblioref linkend="Miller1999" unit="chapter" start="2"
/><biblioref linkend="Doe2000" /></citation>

?

This feels inconsistent to me, but maybe that's just me.

> What does "full" do? What does "author" do? What does "year" do?

Ok, now we're getting to the dustier corners of this issue. The basic
idea is to insert a formatted string based on the information in the
bibliography into the flow of the text. One way to code this is:

<para><citation><biblioref linkend="Miller1999"
renderas="author"></citation> <citation><biblioref linkend="Miller1999"
renderas="year"></citation> analyzed 250 common computer models and
concluded that all of them required an operating system.</para>

However, this code essentially creates two citations although logically
it is only one. This could be solved by using a standalone <biblioref>
for one part as this does not imply a citation:

<para><biblioref linkend="Miller1999" renderas="author">
<citation><biblioref linkend="Miller1999" renderas="year"></citation>
analyzed 250 common computer models and concluded that all of them
required an operating system.</para>

BTW wrapping both parts into one citation might not work in some cases
as e.g. the author may be required at the beginning of the sentence
whereas the year or the numeric representation should go to the end.

The attribute values "full", "author", and "year" cause the stylesheet
to extract the appropriate string representation from the bibliographic
data. That is, if you want to see the author(s) of a reference in the
text, you don't hard-code it (as the exact representation depends on the
citation style of the journal), but use a link and leave the
representation to the stylesheet. Full should be the default and create
a regular citation representation with all required data, i.e. either
numeric or author/year.

> > More complex citations, like the nested one written by Miller (1999,
> > > > see also Doe 1985, Myers 1990), may require the use of the
> > > > renderas > > attribute on individual <biblioref>s. Therefore it
> > > > should be added to > > the content model of this element as
> > > > well. > > Can you show me how you'd like to markup that more
> > > > complex citation? > <biblioref linkend="Miller1999"
> > > > renderas="author"> <citation><biblioref linkend="Miller1999"
> > > > renderas="year">, see also <biblioref linkend="Doe1985"
> > > > /><biblioref linkend="Myers1990" /></citation>

The stylesheet should assume that no renderas attribute implies "full".

> Why does "left figure" have to be in an attribute. Why not simply >
> <citation><biblioref linkend="Smiths99"/> (left figure)</citation> >

We've figured this too late. This is indeed better.

> > Bibliospec has crept back in, didn't you remove that? >

Sorry about that. It's gone.

Hope this helps

Markus

-- Markus Hoenicka markus.hoenicka@cats.de (Spam-protected email:
replace the quadrupeds with "mhoenicka") http://www.mhoenicka.de