OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-tc] info on citation item

Hash: SHA1

/ "Bob Stayton" <bobs@sagehill.net> was heard to say:
| Improved citation support in DocBook
| ====================================
| [This proposal is an updated version of the one discussed at the
| DocBook TC meeting in November. The proposal was condensed
| considerably based on the suggestions during the meeting.]
| Changes to the previous version:
| - boiled down to the bare bones: addition of <biblioref>

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

In any event, I've had a chance to look more closely at the other proposal[1]:

> 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?

> 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. Addition of a new <biblioref> element
> --------------------------------------------------------
> 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

> 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]?

> The use of attributes is preferable to using #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" unit="chapter"
> start="2" /></citation>

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.

> Code required:
> Addition of elements with the following content models and attributes:
> <!ELEMENT biblioref EMPTY >
> <!ATTLIST biblioref linkend IDREF #REQUIRED
>                     endterm IDREF #IMPLIED
> 		    unit NMTOKEN #REQUIRED
>                     start NMTOKEN #REQUIRED
>                     stop NMTOKEN #IMPLIED>
> Inclusion of <biblioref> into the content model of <citation>
> Level: essential
> 3. New attribute "renderas" for the <citation> and biblioref elements
> ---------------------------------------------------------------------
> 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>

Which one of these samples generates the examples above. I would have thought
it was something like this:

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

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

> 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?

> Code required: Addition of renderas to the ATTLIST of <citation> and
> of <biblioref> 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: <citation refs="Smith99" caption="left figure">...
> Again, complex citation may require to attach captions to individual
> <biblioref> elements, so this needs a caption attribute as well.
> Code required: add an attribute "caption CDATA #IMPLIED"
>                     to <citation> and to <biblioref>.
> Alternative: add caption element type to the content model
>                  <!ELEMENT citation %ho; (%para.char.mix;|caption)*>
> Level: important.

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

I have a hard time imagining a set of stylesheets smart enough to do
the right thing with arbitrary caption text. And if we do need the
caption text to be identified separately so that a stylesheet can
process it, it still has to be in an element, I think, for I18N

> 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>

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

We already have "attribution" for blockquote and epigraph. I don't think
we need anything specific for quote. You can simply put the citation in
as you normally would, I think.

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

True, the quote and the citation don't have a wrapper, but is that
really a problem? They're presumably in the same para.

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

                                        Be seeing you,

[1] http://www.sagehill.net/dbtc/proposal.txt
- --
Norman Walsh <ndw@nwalsh.com>      | Absolute faith corrupts as
http://www.oasis-open.org/docbook/ | absolutely as absolute
Chair, DocBook Technical Committee | power.--Eric Hoffer
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]