Improved citation support in DocBook ==================================== [This proposal is an updated version of the one discussed at the DocBook TC meeting in October. Ongoing discussions required some minor changes to our proposal. Customization layers for DocBook SGML and XML implementing the proposal and some example documents are part of this proposal. Changes to the first version: - leave out the proposed bibliospec element and use attributes instead - add the renderas and caption attributes to biblioref as well - the biblioref linkend attribute needs to be #REQUIRED instead of #IMPLIED] 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 ( 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. Addition of a new element -------------------------------------------------------- While it is possible to use the existing element in a to encode pointers to entries in a (please note the striking identity in the semantics of a pointer and ), the 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 as an extension of 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 contains more than one , 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 use of attributes is preferable to using #PCDATA in 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: Code required: Addition of elements with the following content models and attributes: Inclusion of into the content model of Level: essential 3. New attribute "renderas" for the and biblioref elements --------------------------------------------------------------------- Citations may be used in different ways by an author. This may influence the processing expectations of elements. The 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: 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 s. Therefore it should be added to the content model of this element as well. Code required: Addition of renderas to the ATTLIST of and of as NMTOKEN #IMPLIED Level: essential 4. Specification of navigational information in citations --------------------------------------------------------- Add free-text caption or instructional text to citations to direct the reader. Example: ... Again, complex citation may require to attach captions to individual elements, so this needs a caption attribute as well. Code required: add an attribute "caption CDATA #IMPLIED" to and to . Alternative: add caption element type to the content model Level: important. 5. Add to the content model of element types implying quotation -------------------------------------------------------------------------- Add to the content model of ,

and Example: A quote