[tei-council] bibliog doc

[Martin Holmes]

Hi all,
>> 2. I revised the additional material proposed for the end of section
>> 3.? as follows:
>>
>>
>> <p>The most commonly used elements in the model.biblLike class are
>> <gi>biblStruct</gi>  and<gi>bibl</gi>.<gi>biblStruct</gi>  will
>> usually be easier to process mechanically than<gi>bibl</gi>  because
>> its structure is more constrained and predictable. It is suited to
>> situations in which the objective is to represent bibliographic
>> information for machine processing directly by other
>> systems or after conversion to some other bibliographic markup formats
>> such as BibTeXML or MODS. Punctuation delimiting the components of a
>> print citation is not permitted directly within a<gi>biblStruct</gi>
>> element; instead, the presence and order of child elements must be used to
>> reconstruct the punctuation required by a particular style.
>> <!--While<gi>biblStruct</gi>  offers enough
>> flexibility for encoding bibliographic references to simple print
>> works, for many documents, especially electronic ones, it proves
>> problematic.-->  <!-- no problems presented -->
>> </p>
>>
>> <p>By contrast,<gi>bibl</gi>  allows for considerable flexibility in
>> that it can include both delimiting punctuation and unmarked-up text;
>> and its constituents can also be ordered in any way. This makes it
>> suitable for marking up bibliographies in existing documents, where it
>> is considered important to preserve the form of references in the
>> original document, while also distinguishing important pieces of
>> information such as authors, dates, publishers, and so
>> on.<gi>bibl</gi>  may also be useful when encoding<soCalled>born
>> digital</soCalled>  documents which require use of a specific style
>> guide when rendering the content<!-- why is this true of born digital
>> dox in particular? -->; its flexibility makes it easier to provide all
>> the information for a reference in the exact sequence required by the
>> target rendering, including any necessary punctuation and linking
>> words, rather than using an XSLT stylesheet or similar to reorder and
>> punctuate the data.<!-- tough if you later want it in a different
>> form for another rendering engine of course -->  </p>
>
> Lou wants a clearer rationale here.
>
> Martin's done a good job of explaining his rationale, but let me try
> stating this in different terms just in case it alleviates confusion over
> Martin's use of "electronic" documents and "born-digital" ones.
>
> I believe Martin envisions two approaches to encoding bibliographic
> citations given in a source document:
>
> a) You want to represent the source document as it is, even if it has
> inconsistencies in it.
>
> b) You want to impose structure on the citations to catch errors and allow
> you to format the citations according to various style guides (MLA,
> Chicago, APA, etc.) automatically by displaying the content of various
> bibl/biblStruct/biblFull child elements in different orders.  This is the
> born-digital case in the second paragraph: you're creating a new TEI
> document for which there's no print source to be represented.
>
> If you're doing (a), you basically have to use<bibl>.
>
> If you're doing (b), people are generally inclined to use biblStruct, but
> Martin argues in this document (and at the symposium in Dublin) that it's
> more practical to use bibl.  As described in the first paragraph, he has
> found that citations to electronic works are often quite complicated in
> structure and that if you try to use biblStruct, it will be quite
> difficult to format according to the rules of MLA, Chicago, APA, etc.
>
> Martin, chime in if I got this wrong.

That's exactly my point, expressed more clearly than I've managed to 
express it so far myself. My worry is that we push people into using 
<biblStruct> when <bibl> would actually be more suitable, simply because 
of the weight of examples of <biblStruct> and the absence of any 
encouragement to think about <bibl> as a more practical alternative.

>> 3. Use of persName inside biblStruct
>>
>> <!-- Name markup is essential for proper
>> indexing and other forms of processing. It
>> seems advisable that all biblStruct examples
>> use it, since the purpose of biblStruct is to
>> provide a highly-structured reference. -->
>>
>> While this may be true, it presents us with quite a problem in terms
>> of house style. Usually we try not to use elements from one module in
>> examples appearing in a chapter which describes another. In the few
>> rare exceptions, we make quite a song and dance about the need to
>> include the other module etc. But biblStruct and friends are
>> described in the core module, whereas the<persName>  etc. elements
>> are described in names and dates. (That incidentally is why the<name>
>> element was originally used in some of these examples -- name is
>> available in the core). So, while I am perfectly to change some of the
>> examples to indicate what you propose as appropriate use of the
>> naming elements, I don't think it should be done uniformly. I fear
>> this needs more mulling over.
>
> Yes indeed.  In the summary of our proposal to Council, Martin, Laurent,
> and I asserted in principle 1 that if you use biblStruct, you really
> should use the Names and Dates module.  Council agreed to this.  If we
> don't change all of the examples to reflect this, it needs to be as clear
> as possible to readers why this is the case.

This issue is similar to the one above: if we assume (and my experience 
suggests this is true) that most users, at least in the early stages of 
using TEI, will tend to copy-paste examples from the Guidelines and 
adapt them, then we ought to avoid providing examples which will not 
work very well for them in real projects. A <biblStruct> whose name 
components are not marked up is not very useful for its intended purpose 
-- automated processing and interchange.

I'd suggest that we add a section on "Name encoding in bibliographical 
references", fairly early in the chapter, to clarify this. Does that 
make sense?

Cheers,
Martin

-- 
Martin Holmes
University of Victoria Humanities Computing and Media Centre
(mholmes at uvic.ca)
Half-Baked Software, Inc.
(mholmes at halfbakedsoftware.com)
martin at mholmes.com