[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-tc] info on citation item
-----BEGIN PGP SIGNED MESSAGE-----
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
point.
> 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:
<citation>
<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
reasons.
> 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,
norm
[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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>
iD8DBQE/4MyzOyltUcwYWjsRAgMaAKCbz4IS0aZKEk9OxF8tCYOmY5yUbwCcCad9
2jj40UCsTwRTmpGNZRaGZAk=
=tMw0
-----END PGP SIGNATURE-----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]