[docbook] improved citation support proposal (RFE 810932)

[Bruce D'Arcus <bdarcus at fastmail dot fm>]

Hi,

I'd like to solicit comment on the below proposal to improve citation 
support in DocBook: RFE 810932.

The proposal is the work of Peter Flynn, and Markus Hoenicka, and I, 
and aims to improve citation support in DocBook to a level adequate to 
the social sciences and the humanities.  In essence, we'd like to see 
support analogous to what BibTeX provides for LaTeX users; structural 
encoding of citations that could yield output like (Smith, 1999; Doe, 
2000) or (Smith, 1999:22-34; see also Doe, 2000).

We have been discussing improved bibliographic and citation support in 
XML for about the past year, though much of that has been focused on 
metadata models and xslt-based formatting [1].  Still, these basic DTD 
changes are essential to making DocBook suitable for scholarly work, 
which I once read Terry Allen had considered as a goal.

With the proposal to make DocBook v.next more flexible and thus 
suitable for a wider range of potential users, I hope everyone agrees 
this would be a valuable improvement.

Bruce

[1]  The idea here is to provide optional ability to use a 
DTD/Schema-independent xslt-based equivalent to BibTeX, using MODS as 
an optional bibliographic metadata schema.  More at:

http://silmaril.ie/bibliofile/
http://www.loc.gov/standards/mods/

************************************************************

Improved citation support in DocBook
====================================

Citation support in DocBook is weak. In order to improve it,
some small code changes are needed.

1. Terminology
--------------

A citation describes the intellectual origin of a stretch of text,
regardless of whether this is a literal quote, an edited excerpt, or a
statement based on the content of sources other than the author's
personal work. It can also be used to refer the reader to additional
information that goes beyond the scope of the document. A citation can
contain bibliographic references, although it is more common to use
pointers to bibliographic references. As the knowledge compiled in a
statement may be drawn from several sources, it is sometimes necessary
to use two or more references or pointers to references in a
citation. In addition, a citation may contain other explanatory text.

A bibliographic reference is a "self-sufficient description of a
bibliographic item" (as the TEI guidelines define it), and as such
usually sufficient to locate a printed or electronic copy of the
referenced work. It is common to collect bibliographic references in a
list at the end of a document or of a chapter.

A pointer to a bibliographic reference is a cross-reference that links
citations to bibliographic references, thus eliminating the need to
provide the bulk of the bibliographic information in the text
flow. The pointer is usually rendered using a citation key, the number
of the bibliographic reference in the reference list, or an
author/year representation of that reference.

The following graph outlines the relationship of these three items
(use a fixed font for display if it doesn't seem to make sense):

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

Miller,A: A survey of the applications of mainframe   < reference 1
           computers. Adv.Sci.Comp. 13:497, 1999.      <

Doe, B: Mainframes and numeric mathematics. Am.J.Eng. < reference 2
         54:87, 2000.                                  <

DocBook contains sufficient support to encode bibliographic references
(<bibliography> and related elements). However, the support for
pointers to bibliographic references should be extended to make
DocBook more versatile. The changes are proposed 1) to
make the formatting of citations and bibliographic references
according to a publisher-supplied style specification feasible and 2)
to allow DocBook to be used for documents that have more demanding
requirements for citations.

2. New attribute "renderas" for the <citation> element
-------------------------------------------------------

Citations may be used in different ways by an author. This may
influence the processing expectations of <citation> elements. The
<citation> element should be extended with an attribute that allows an
author to select a specific processing expectation.

1) Citation outside of the text flow
This is the most common case. The citation is to be rendered outside
the text flow, for example in brackets or as a superscript (this is at
the discretion of the stylesheet or of a processing application):

Computers require an operating system (Miller et al., 1999).
Computers require an operating system [1].

2) Citation in the text flow
Sometimes it is required to integrate parts of the bibliographic
reference into the text flow. These parts must still retain their
function as a pointer to a bibliographic reference:

Miller et al. (1999) analyzed 250 common computer models and concluded
that
all of them required an operating system.
Miller et al. [1] analyzed 250 common computer models and concluded that
all of them required an operating system.

In this case, both "Miller et al." and "(1999)" or "[1]",
respectively, are citations with one pointer to a bibliographic
reference each. However, their integration into the text flow requires
that each is rendered differently and in a different way compared to 1).

Examples:

<citation renderas="full"><biblioref linkend="Miller1999"
/></citation>
<citation renderas="author"><biblioref linkend="Miller1999"
/></citation>
<citation renderas="year"><biblioref linkend="Miller1999"
/></citation>

Code required:
Addition of renderas to the ATTLIST of <citation> as NMTOKEN #IMPLIED

Level: essential


3. Addition of new <biblioref> and <bibliospec> elements
--------------------------------------------------------

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.

Think of the proposed <biblioref> as an extension of <xref> that
allows children, namely <bibliospec>, 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 children. 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]".

The <bibliospec> element is preferable to allowing #PCDATA in
<biblioref> because the formatting of the provided information should
be left to stylesheets. For example, a range of pages may be
rendered as "pages 12 through 15", "pp 12-15", or maybe as "pp 12 sq".

Example:

<citation><biblioref linkend="Miller1999"><bibliospec unit="stanza"
start="2" /><bibliospec unit="line" start="3" stop="4"
/></biblioref></citation>

Code required:
Addition of elements with the following content models and attributes:
<!ELEMENT biblioref (bibliospec*)>
<!ATTLIST biblioref linkend IDREF #IMPLIED
                     endterm IDREF #IMPLIED>

<!ELEMENT bibliospec EMPTY>
<!ATTLIST bibliospec unit NMTOKEN #REQUIRED
                      start NMTOKEN #REQUIRED
                      stop NMTOKEN #IMPLIED>

Inclusion of <biblioref> into the content model of <citation>

Alternative:
If the inclusion of two elements seems excessive, we may consider to
use a simplified <biblioref> element:

<!ELEMENT biblioref (bibliospec*)>
<!ATTLIST biblioref linkend IDREF #IMPLIED
                     endterm IDREF #IMPLIED
                     unit NMTOKEN #REQUIRED
                     start NMTOKEN #REQUIRED
                     stop NMTOKEN #IMPLIED>

This restrics the author to using a single level of bibliographic
information, like a page range or a chapter range, but not both at a
time. This may still be sufficient for most purposes.

Level: essential


4. Specification of navigational information in citations
---------------------------------------------------------

Add free-text caption or instructional text to citations to
direct the reader.

Example: <citation refs="Smith99" caption="left figure">...

Code required: add an attribute "caption CDATA #IMPLIED"
                     to citation.

Alternative: add caption element type to the content model
                  <!ELEMENT citation %ho; (%para.char.mix;|caption)*>

Level: important.


5. Add <biblioref> to the content model of element types implying
quotation
------------------------------------------------------------------------
--

Add <biblioref> to the content model of <quote>, <blockquote> and
<epigraph>

Example:

<quote>A quote <biblioref linkend="Smith1999"><bibliospec
unit="page" start="22" stop="23 /></biblioref></quote>

Code required:
Extend the content models of <blockquote> and <epigraph> to allow
<biblioref> elements.

Level: important



To unsubscribe from this list, send a post to docbook-unsubscribe@lists.oasis-open.org, or visit http://www.oasis-open.org/mlmanage/.