Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

#428 Chapter 3 example needs changes

AMBER
closed
Martin Holmes
5
2013-04-12
2013-01-28
Martin Holmes
No

This arises out of the long-running biblio work that Kevin, Laurent and I have been doing:

http://wiki.tei-c.org/index.php/Ad-hoc_committee_on_encoding_of_bibliographic_citations

The proposal (dating back to the Dublin meeting) is to add more dense markup to the example which is found here:

http://teijenkins.hcmc.uvic.ca/job/TEIP5/lastSuccessfulBuild/artifact/release/doc/tei-p5-doc/en/html/CO.html#index-egXML-d50e39299

The current listBibl is confusing, because:

1. It suggests that <bibl> is usually used when the content is less rigorously marked up; this is in contrast to what the Guidelines explicitly say above, where <bibl> is (as we argued) shown to be useful in situations such as born-digital documents where the order of elements is what is important, not the density of markup.

2. It suggests that a <listBibl> that combines fully-marked-up <biblStruct>s with loosely-marked-up <bibl>s would be somehow worthwhile. It would actually be bad practice, because only parts of the information in it could be recovered mechanically in any useful detail. If, as the Guidelines already claim, "the listBibl element is most appropriate for a more formal bibliography", then we should not be providing an example (the first example of it, in fact) which is relatively useless for formal work.

This is also an opportunity to demonstrate, and explain in the subsequent paragraph, how full tagging can be done within <bibl>.

In addition, the subsequent example in the text is identical to the original with the exception that it is wrapped in a <list> instead of a <listBibl>, with the claim that this might be done when such elements are “presented informally”. If we leave this subsequent example unchanged, it exemplifies the way that <bibl>s may have sparser markup, by contrast with this example.

So we would change this:

<bibl xml:id="NELSON88">Ted Nelson: <title>Literary Machines</title>
(privately published, 1987)</bibl>
<bibl xml:id="BAXTER88">
<author>Baxter, Glen</author>
<title>Glen Baxter His Life: the years of struggle</title>
London: Thames and Hudson, 1988.
</bibl>

to this:

<bibl xml:id="NELSON88">
<author>
<persName>
<forename>Ted</forename>
<surname>Nelson</surname>
</persName>
</author>: <title level="u">Literary Machines</title>
(privately published, <date when="1987">1987</date>)</bibl>

<bibl xml:id="BAXTER88">
<author>
<persName>
<surname>Baxter</surname>, <forename>Glen</forename>
</persName>
</author>
<title level="m">Glen Baxter His Life: the years of
struggle</title> <pubPlace>London</pubPlace>: <publisher>Thames and Hudson</publisher>, <date when="1988">1988</date>.
</bibl>

and add the following explanation after the example:

"This example also demonstrates the way that bibliographical markup of authors, titles, dates etc. can be handled differently in <biblStruct>s and <bibl>s. In the two <bibl> items, the key information is marked up, but it is presented in an order which makes it suitable for direct rendering, with interpolated punctuation."

Discussion

1 2 > >> (Page 1 of 2)
  • i think you need to check the McCaskey effect to those examples. are they are implying whitespace at the start and end of the entries? I suspect so.

    s/interpolated/interspersed/ ?

     
  • Martin Holmes
    Martin Holmes
    2013-01-28

    Good point on the whitespace, although it obviously also applies to the current state of the example. I agree "interpolated" is wrong -- should probably be: "...direct rendering, with the punctuation included>"

     
  • Martin Holmes
    Martin Holmes
    2013-03-17

    I propose to go ahead with this change, after eliminating spare whitespace as Sebastian suggests, unless anyone objects in the next couple of weeks. It's uncontroversial and helpful, I think.

     
  • Martin Holmes
    Martin Holmes
    2013-03-23

    Change made in revision 11747. Leaving the ticket open for a while in case anyone wants to comment on the change or object.

     
  • Martin Holmes
    Martin Holmes
    2013-03-23

    The rendering of the examples in the Guidelines output has reintroduced whitespace that I'd eliminated, unfortunately. I think if we're going to address John M's concerns about whitespace in contexts such as <bibl>, we'll need to start enumerating the contexts concerned and modify the rendering code for examples. I'm leaving this ticket open because of this; we should decide whether we need to spawn a new ticket for the whitespace issue at the next meeting.

     
    Last edit: Martin Holmes 2013-03-23
  • do you think the McCaskey effect has produced a wrong result?

     
  • Martin Holmes
    Martin Holmes
    2013-03-24

    @Sebastian: I'm not sure what that means, but I think the assumption was that we should eliminate non-significant whitespace from e.g. <bibl> to avoid having, for instance, leading whitespace unexpectedly output from rendering pipelines at the beginning of a bibliographical reference; I've done that in the source code, but the Guidelines XSL has effectively replaced it by pretty-printing and indenting the source tree when rendering the example.

    I'm really not sure how important this is. Most projects have their own XSL pipelines, and they know how to handle their own whitespace. My concern on this ticket was just to have some good examples of using <bibl> with fully-tagged reference information, which I now have.

     
  • Martin Holmes
    Martin Holmes
    2013-03-29

    I'm closing this ticket, since the original Guidelines change proposed has now been carried out. The issue of whitespace has been raised in a new bug ticket:

    https://sourceforge.net/p/tei/bugs/544/

     
  • Martin Holmes
    Martin Holmes
    2013-03-29

    • Description has changed:

    Diff:

    --- old
    +++ new
    @@ -1,4 +1,3 @@
    -
    
     This arises out of the long-running biblio work that Kevin, Laurent and I have been doing:
    
    • status: open --> closed
    • milestone: --> AMBER
     
  • The xsl has been changed to support @xml:space, so formatting is now correct

     
1 2 > >> (Page 1 of 2)