#632 sloppy language in specs for att.datable.w3c and att.datable.iso

AMBER
closed
Syd Bauman
None
5(default)
2014-07-27
2014-01-06
Kevin Hawkins
No

I see that http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-att.datable.w3c.html makes multiple references to "the W3C XML Schema Part 2: Datatypes Second Edition". We should also add a link to this document: it appears to be at http://www.w3.org/TR/xmlschema-2/ .

At times the reference to this document is accompanied by one of the following:

a) "temporal expression"
b) "W3C date, time, and date & time formats"
c) "using the Gregorian calendar"

We should be a bit more consistent in our language. Specifically:

a) The W3C recommendation doesn't use the term "temporal expression", so perhaps we should replace this with "the primitive datatypes defined in Appendix D".

b) I suspect "date & time" is supposed to refer to what the W3C recommendation calls "dateTime".

b) "using the Gregorian calendar" seems redundant since as far as I can tell the W3C recommendation refers only to the Gregorian calendar.

Furthermore, I suggest that at http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-att.datable.iso.html we drop the phrase "Any string representing a valid date, time, or one of a variety of combinations." since it's misleading given that it's followed by a note: "The value of the when-iso attribute should be the normalized representation of the date, time, or combined date & time intended, in any of the standard formats specified by ISO 8601, using the Gregorian calendar."

Discussion

  • James Cummings
    James Cummings
    2014-05-19

    Assigning to Syd Bauman to triage and review.

     
  • James Cummings
    James Cummings
    2014-05-19

    • assigned_to: Syd Bauman
     
  • Martin Holmes
    Martin Holmes
    2014-06-30

    Not Appendix D, surely; Appendix E (datatypes and macros).

     
  • Martin Holmes
    Martin Holmes
    2014-06-30

    Council discussion group believes that the reference to the Gregorian calendar should be retained for clarity; many people do not realize that by using these datatypes they are also choosing the Gregorian calendar.

     
  • Syd Bauman
    Syd Bauman
    2014-07-27

    1. title should refer to document

    Yes, agreed. There were 25 occurrences of the title of XML Schema
    Part 2 in the Guidelines, some of which had "Second Edition" and
    some of which did not. All now have "Second Edition" and point to
    the bibliography.

    I also found 13 direct links to the general URL of that document,
    as follows.
    * ST-Infrastructure.xml: refers generally -- fixed to point to
    bibliography.
    * metDecl.xml: refers specifically to appendix F ("#regexs")
    * SA-LinkingSegmentationAlignment.xml: refers to "an appendix",
    which, not surprisingly, is also F ("#regexs")
    * CO-CoreElements.xml: refers to the 8 specific datatypes directly:
    #date
    #gYear
    #gMonth
    #gDay
    #gYearMonth
    #gMonthDay
    #time
    #dateTime
    * SG-GentleIntroduction.xml: refers generally -- fixed to point to
    bibliography.

    I also found 4 direct links to the URL of a particular version
    of that document, as follows.
    * BIB: appropriate
    * data.duration.w3c.xml: refers specifically to #duration, the
    duration datatype

    I will open a new FR ticket to discuss how we should handle the
    remaining references.

    1. We should be a bit more consistent in our language. Specifically:

    a) The W3C recommendation doesn't use the term "temporal
    expression", so perhaps we should replace this with "the
    primitive datatypes defined in Appendix D".

    I disagree. On a quick review of occurrences, we use "temporal
    expression" completely appropriately. The one possible exception
    (perhaps the one Kevin had in mind) is in the description of
    data.temporal.iso and data.temporal.w3c. There the phrase is correctly
    used, but arguably we could be more precise, e.g.:

    defines the range of attribute values used to normalize a temporal
    expression to the international standard ...

    I have not made this change, but will put it into a new ticket so that
    Council will consider it.

    b) I suspect "date & time" is supposed to refer to what the W3C
    recommendation calls "dateTime".

    Kevin is correct, the W3C name for the datatype that expresses a date
    and time within that date (i.e., what in English is referred to as a
    "date and time") is "dateTime". I don't know if Kevin is implying that
    the TEI Guidelines should also say "dateTime" here, but they certainly
    should not. a) The phrases in question are written in English and
    refer to the concept, not in standardese referring to the datatype. b)
    One of the phrases in question is talking about ISO formats, not W3C
    formats.

    This issue is "closed-wont-fix" as far as I'm concerned.

    c) "using the Gregorian calendar" seems redundant since as far as I
    can tell the W3C recommendation refers only to the Gregorian
    calendar.

    Yes, it is redundant. But it is a good idea to be redundant here, as
    many scholars don't realize that using W3C date formats implies use of
    the Gregorian system. You can use proleptic Gregorian in these
    formats, though, and perhaps we should say that. I plan to open a new
    ticket so Council can consider adding a phrase about proleptic
    Gregorian.

    1. ... drop the phrase "Any string representing a valid date, time,
      or one of a variety of combinations." (from att.datable.iso)
      since it's misleading given ...

    Not sure what Kevin is referring to here. That phrase does not appear
    in att.datable.iso, and has not since before the bug report was
    submitted. I did not find it anywhere in the current GLs (but did not
    look through the whole GLs historically, just in att.datable.iso).

    This issue is "closed-works-for-me" as far as I'm concerned.

     
  • Syd Bauman
    Syd Bauman
    2014-07-27

    • status: open --> closed
     
  • Kevin Hawkins
    Kevin Hawkins
    2014-07-27

    For the record ...

    Point (a), regarding "temporal expression", was indeed meant to refer to data.temporal.iso, whose text used to appear within ref-att.datable.iso.html by inclusion (see, for example, http://www.tei-c.org/Vault/P5/2.5.0/doc/tei-p5-doc/en/html/ref-att.datable.iso.html ). It no longer appears at ref-att.datable.iso.html, but raising a new ticket is fine if Syd feels we could be more precise.

    As for the phrase "Any string representing a valid date, time,
    or one of a variety of combinations.", it used to appear within within ref-att.datable.iso.html by inclusion (see, for example, http://www.tei-c.org/Vault/P5/2.5.0/doc/tei-p5-doc/en/html/ref-att.datable.iso.html ). It no longer appears at ref-att.datable.iso.html, so it's no longer a concern to me.