EML

Hi Owen,

Your changes to literature look good. Generally it looks much more
comprehensive wrt to EndNote. Here are a few issues I saw from my quick look:

1) LitCitation is a sequence containing a single choice. You can get rid of the
sequence -- it is unneeded.

2) You haven't followed our type and element naming conventions. Elements
should always start with a lower case letter and capitalize the first letter fo
each subsequent word. Types should start with a capital and then capitalize
each word. For example, the element "personalCommunication" should be of type
"PersonalCommunication", and the element "map" should be of type "Map".

3) You are missing lots of documentation. We need the standard tooltip,
summary, description, example, and lineage documentation tags to be present for
every element and attribute. This documentation is what defines the spec.
Without it people will have no guidance as to the contents of each field.

4) You broke the file formatting that we use. Please reformat the file with
indentations for elements (2 spaces per level) and a maximum line length of 80
characters. This helps the files be more readable in various text environments.

5) I'm confused about what happened to "Chapter". I still think it is needed.
Is the new "section" element in book supposed to contain the chapter title?
Maybe the documentation would clear this up. Doesn't EndNote have a BookChapter
type?

6) you clearly made some changes that we didn't discuss at Sevilleta. It would
be useful if you documented your rationale for what you did in this bug. For
example, item (6) was to change thesis/degree into thesis/institution, but you
added a university element instead. Describing the changes you made for each of
the points (1-11) in this bug will help speed up the review process for the rest
of us.

7) Do you see a need for software? Is that what that final element is with the
funny name?

8) Someone who knows endnote better should review this as well before we check
it in.

9) The DTD needs to be updated to reflect these changes as well.

10) You made publicationPlace be a ResponsibleParty. I don't think that is
needed, and I didn't think we decided to do that at SEV. It just needs to be a
simple string. Can you justify the more complex structure?

11) geographicCov should be written out fully as "geographicCoverage"

Thanks.

I am in the process of documenting eml-literature right now. That should clear
up most of your questions.

The funny software name as the last element is there because I think a case
could be made to place software in literature as well, especially if we accept
audioVisual as type. So the eml-software module could be plugged in there if
folks decide to do so.

Troy Maddux our DBA reviewed all the lit types with me yesterday. He knows
endnote pretty well and he currently is in the process of implementing
their 'data model' in our sql server rdbms.

Ive looked at the latest attachement. here are my comments:

1) remove editors from editedBook. the creators ARE the editors of an edited
book.

2)bring back chapter. there is a "bookSection" complex type that isnt being
used - im assuming that this is supposed to be for Chapter.

3) publication place doesnt need to repeat. a citation need only reference one
publication location, regardles of how many offices a press may have.

4) drop software - we will have eml-software for this.

5) drop personal communication unless this is meant to refer to a written
communcation that is actually archived somewhere.

6) drop section from book, editedbook, etc. if the citation is directed at a
section of a larger item, then you should use the article or chapter elements,
and not cite the larger item.

7. i think we will find it awkward to support the responsible party format for
things like publisher, pubplace, etc. Its already being a ROYAL pain to parse
and unparse author strings into first, given and last names when going to and
from vendor formats like endnote. However, to be consistent with authors, we
should use RP for editors as well.

still have clean up work with documentation

finished documentation.

1) LitCitation is a sequence containing a single choice. You can get rid of the
sequence -- it is unneeded.

DONE - I inherited this.

2) You haven't followed our type and element naming conventions. Elements
should always start with a lower case letter and capitalize the first letter for
each subsequent word. Types should start with a capital and then capitalize
each word. For example, the element "personalCommunication" should be of type
"PersonalCommunication", and the element "map" should be of type "Map".

DONE

3) You are missing lots of documentation. We need the standard tooltip,
summary, description, example, and lineage documentation tags to be present for
every element and attribute. This documentation is what defines the spec.
Without it people will have no guidance as to the contents of each field.

4) You broke the file formatting that we use. Please reformat the file with
indentations for elements (2 spaces per level) and a maximum line length of 80
characters. This helps the files be more readable in various text environments.

5) I'm confused about what happened to "Chapter". I still think it is needed.
Is the new "section" element in book supposed to contain the chapter title?
Maybe the documentation would clear this up. Doesn't EndNote have a BookChapter
type?

Answer:

Here's my posting to eml-dev and Corrina's response. This is why I got rid of
Chapter and placed section in every type of reference. I just extracted the
relevent question:

Question 2:

EndNote has the reference type Book Section which takes care of chapter.
Remember we have a reference type in eml called chapter. But Book Section
has a finer granularity. So for example the section of a book being
referenced could be a section of a chapter. So the reference could be Book
chapter 15 section 1 (15.1) rather that all of chapter 15. Or table 15.7
could be referenced and so on. Would this be useful to have this level of
granularity. The reason I'm asking is that we've already implied it is
because we have a chapter reference type. So if folks think this is useful
I'd like to propose that we get rid of Chapter altogether and add an
optional <section> element to book, article, edited book, report and so on.
This will give us this finer granularity to what we are citing.

Calling it section seems to make it more useful.

Corinna

6) you clearly made some changes that we didn't discuss at Sevilleta. It would
be useful if you documented your rationale for what you did in this bug. For
example, item (6) was to change thesis/degree into thesis/institution, but you
added a university element instead. Describing the changes you made for each of
the points (1-11) in this bug will help speed up the review process for the rest
of us.

Seel responses 1-11 below.

7) Do you see a need for software? Is that what that final element is with the
funny name?

I think a case could be made to place the softwarePackage module here,
especially
if folks agree on the audioVisual Type. I can go either way with it. EndNote
has a software module. That in of itself not a compelling reason to have
software here.
Let me know what folks think about putting software here and I can make this
element of complex type softwarePackage.

8) Someone who knows endnote better should review this as well before we check
it in.

Troy Maddux our DBA at the network office knows EndNote well and he did a
comprehensive overview of all my suggested changes.

9) The DTD needs to be updated to reflect these changes as well.

Changes as decided upon at the Sevilleta EML meeting, April 24-25, 2002:
Responsible: Owen

1) Move ISSN to be a child of "article"

Done

2) move ISBN to be a child of Book and Chapter

Done

3) add types for proceedings and for conference paper (follow end note)

Done

4) add publisher (type=RespParty) to Book, Chapter, Report, Thesis

Done

5) add PubPlace to Book, Chapter, Report, Thesis

Done

6) Change thesis/degree to thesis/institution

Endnote uses university, I used this instead of institution. Don’t have real
strong feelings about this if folks want institution instead.

7) add "editedBook" type that extends "Book" type by adding a "bookEditor+"
field (type=RespParty)

Done

8) drop pubInfo from thesis

not sure it was ever there.

9) Do a comprehensive review of all types to be sure they can capture the
information that is typically put in end note by ecologists and that the content
models make sense

I added three new types that are in EndNote that we did not already have or
agreed to add at the Sev.

personnal Communication: Letter, memo, email, discussion with college that is
characterized, etc…

audio Visual: this is a composite of EndNote types: audiovisual,
film/broadcast, electronic source.

Generic: generic type with a bunch of fields for citations that don’t belong in
any of the other types

10) Peter's notes also say to add a type for presentation, map

Done

11) add "totalPages" with content model "?" to report

Done

10) You made publicationPlace be a ResponsibleParty. I don't think that is
needed, and I didn't think we decided to do that at SEV. It just needs to be a
simple string. Can you justify the more complex structure?

The example that was batted about at the Sev. where the publisher and the
publicationPlace for the World Watch Institute may or may not be the same
place.
Seems that responsibleParty level information may be applicable for both.

In this example the World Watch Institute is the publicationPlace, it has an
organizationName, address, onlineURL, etc... as does its publisher. In every
type where a publisher is applicable I made publisher mandatory except for
thesis
and report and the publicationPlace was left as optional and unbounded because
it seemed to me that the publisher was the more important of the two pieces of
information especially if one wanted to get a copy of the referenced book,
article etc...

I dropped publication and used institution in report or in the case of thesis,
university,
because I thought publicationPlace too general when in these cases a specific
name
like university or institution made more sense. Endnote does it this way.

11) geographicCov should be written out fully as "geographicCoverage"

Done

------- Additional Comments From peter.mccartney@asu.edu 2002-05-21 11:10 -----
--
Ive looked at the latest attachement. here are my comments:

1) remove editors from editedBook. the creators ARE the editors of an edited
book.

Right now we have creator and associatedParty in Resource and editors for an
edited book in Literature. Number 7 (see above) of agreed upon changes says to
add bookEditor to editedBook type that we have agreed to add. I read this all
to mean that creators are the authors of the essays, articles etc within the
edited book and that the editors are the editors. Someone set me straight if
this is wrong assumption.

2)bring back chapter. there is a "bookSection" complex type that isnt being
used - im assuming that this is supposed to be for Chapter.

See above explanation for why chapter was dropped to Matt’s question number 5.
If we agree to add section to increase granularity of a citation then having a
Chapter or bookSection is redundant. I removed the bookSection complex type.
If folks do not want this finer granularity then I can remove the sections
and/or bring back Chapter or bookSection.

3) publication place doesnt need to repeat. a citation need only reference one
publication location, regardles of how many offices a press may have.

See summary/description documentation to citation element to the differences
between publisher and publicationPlace. This is how I interpreted the two from
the Sev. Discussions.

4) drop software - we will have eml-software for this.

See response to Matt’s question #7 above about case for software being placed
here.

5) drop personal communication unless this is meant to refer to a written
communcation that is actually archived somewhere.

I’m envisioning personalCommunication as being either a hard or soft copy that
has been distributed or ‘published’ to one or more recipients.

6) drop section from book, editedbook, etc. if the citation is directed at a
section of a larger item, then you should use the article or chapter elements,
and not cite the larger item.

See explanation to Matt’s question #5 above.

7. i think we will find it awkward to support the responsible party format for
things like publisher, pubplace, etc. Its already being a ROYAL pain to parse
and unparse author strings into first, given and last names when going to and
from vendor formats like endnote. However, to be consistent with authors, we
should use RP for editors as well.

PublicationPlace, publisher, university, institution are potentially possessing
of the information in responsibleParty and so I would argue we should support
it. If all one wanted to put for publicationPlace was Arizona State, for
example, then it would only require one sub-element since address, phone etc..
are all OPTIONAL. So for example:

<publicationPlace>
<organizationName>
Arizona State
</organizationName>
</publicationPlace>

I do not consider this onerous to construct from endnote for example.

by defining publicationPlace, publisher etc… as responsibleParty all the
address, phone other optional info can be placed in the proper sub-elements if
one chooses.

Changes incorporated. However, the last comments from McCartney have not been
addressed (both here in Bugzilla and his recent email. These are substantial
proposed changes, so we opted to not make them until we could discuss them with
Owen. Moving milestone for this module forward.

Just to beat the horse again, here is my current list of changes

a. Drop section from book
b. Drop editors from edited book
c. Add bookChapter or bookSection
d. Drop conference proceedings. If these are published, then they are a
book. The information about the event and venue is part of the title.
e. Drop publicationPlace – the locational information is already in
publisher
f. Drop presentationPlace. Move the proceedings information from
conferenceProceedings to this module.
g. Drop institution from report. Institutional affiliation of authors is
already in the RP information of the authors.
h. Make report number optional. This may be part of the title or non-
existent
i. Drop publisher from thesis. If it is published then it is a book.
j. Drop software package. This is covered under eml-software
k. Drop the unnecessary sequence element containing access and project.

I agreed to handle this during the last conference call, so I'm reassigning the
bug to myself.

Completed revisions to eml-literature. Here's a review of what I did (there's a
special surprise at the end :)...

a.
Drop section from book

DONE

b.
Drop editors from edited book

DONE

c.
Add bookChapter or bookSection

Added Chapter complex type and "chapter" element as a reference type.

d.
Drop conference proceedings. If these are published, then they are a
book. The information about the event and venue is part of the title.

DID NOT DROP IT. Kept it to maintain compatibility with EndNote. It extends
book chapter and adds the few fields needed for the EndNote
conferenceProceedings type.

e.
Drop publicationPlace – the locational information is already in
publisher

KEPT it. Publication place may very well differ fromthe mailing address of the
publisher. The address in RP seemed like an inappropriate place to me to put
the publicationPlace. I did, however, convert this to a string, as a
"publicationPlace" itself can in no way be construed to be a person,
organization, or role (which is what RP represents).

f.
Drop presentationPlace. Move the proceedings information from
conferenceProceedings to this module.

PRESENTATION type dropped altogether. No corresponding type in EndNote.

g.
Drop institution from report. Institutional affiliation of authors is
already in the RP information of the authors.

Kept it. Again, the address of the authors may not correspond with the
institution sponsoring the report. For example, many SFI reports would have
"Santa Fe Institute" as the institution, but the authors are not from SFI. Same
could go for NCEAS, or NSF, etc.

h.
Make report number optional. This may be part of the title or non-
existent

DONE.

i.
Drop publisher from thesis. If it is published then it is a book.

DONE.

j.
Drop software package. This is covered under eml-software

DONE. it was gone before.

k.
Drop the unnecessary sequence element containing access and project.

DONE. project is gone.

In addition to these changes that were suggested above, I also had an epiphany
and went for it... I made each of the reference types include the ResourceGroup
directly, rather than having ResourceGroup be part of CitationType. This is
minorly more verbose in the schema, but makes much more sense in instance
documents because all of the fields of a reference are included inside of the
type element, like this...

<citation>
<article>
<title>fake title</title>
<creator>...</creator>
...
<journal>Ecology</journal>
...
</article>
</citation>

I personally think this is much cleaner and more understandable than before.

Finally, I reworked the documentation for the whole module, created a test
instance documented, and verified that everything validates under the schema
using "ant test". I think this takes care of all outstanding issues with
eml-literature. Will someone review it please? Thanks.

re: technical items.

So how do i cite a paper or poster presented at xxth annual meeting of the
Ecological Socienty of America, Spokane, August 1999 that is not published in
any proceedings volume? is that what you are calling a proceedings? i've always
understood (and ive been around a little longer than EndNote) a proceedings to
be the publication of papers presented at a conference, which to me is a book -
"Proceedings of thexxxxx" might appear as part of the title, but if you look
the thing up in the library, its a book. Many presentations are not published,
so i cannot use your structure for conferenceProceedings to cite them - i dont
have an entry for the require fields publisher, editor, or publisher place. Nor
can i use audioVisual because i dont have the required publisher information
nor is there a place to put the conference name, venue and date (its gratifying
to see that i can indicate a "performer" in case someone else read the paper
for me)

I follow youre argument that a report has two main parties - the instituion
that produces it and the one that sponsored it, but i still think the only one
that really matters for bibliographic reasons is whichever one actually
published it - the particulars of who reported to who is usually embedded in
the title and im not sure we need to define a structure for sorting them out
(sort of like URLs?). In any case, but i dont see it there even though you say
you kept it.

regarding epiphany:
Steven Stevens had this same epiphany over a year ago and I liked it then for
the same reasons you do now. The problem was, it broke tidiness of the
resourceBase extension that you all had introduced at the time. Up until now,
all of the elements found in resource base were exactly in the same place
relative to the document root. Now they are not which means we cannot do
searches with root-relative paths without looking first to see what kind of xml
document it is so we know where the resource group is imported. For example, in
Xanthoria we use a simple config file to tell the search engine that schema x
and y are both extended from schema z and that any xpath expression that works
for z will also work for the others. If we we've changed the rules, then I have
to be more explicit and say that schema x extends z at "/" and schema y extends
z at "/citation/" and i cant send out exactly the same message to targets that
have eml-citation as i would to ones that have eml-dataset.

So what is a resource - a schema who's root extends resourcebase or one that
contains nodes that extend resourcebase? why does spatialVector not extend
resource base, instead of being a choice undeneath dataset? for most GIS users
the concept of a dataset containing an entity is as foreign as citation
containing article. I think these are decisions that shouldnt be made in double-
digit betas.

I agree that this arrangment is more readable visually, but I do remember
distincly someone telling me in another context that EML is meant to be machine
parsed and that readability of the instance file was not important. Given that
sentiment, i would say that a change that affects machine parsing in favor of
readability is inconsistent with this philosopy.

Thanks for the comments. I had not realized the technical implications of my
epiphany, so I'll change it back to the way it was (after I wait for any further
comments on the issue). I thought it would just be cleaner. We don't have as
much of a reliance in our software on absolute locations of elements (we use a
lot of relative XPath searches), so it didn't occur to me to be a problem.
Given that it is a major change, and it will cause some problems, I think it
best to change it back to having ResourceGroup as a part of CitationType. When
I change it back, instances will look like this:

<citation>
<title>fake title</title>
<creator>...</creator>
...
<article>
<journal>Ecology</journal>
...
</article>
</citation>

This is less attractive to me, but the same information is present so we won't
have any trouble making our software deal with it.

As far as conferenceProceedings go, they are intended for proceedings which are
in fact published in some written form. If I can photocopy the proceedings of
conference X, then I think it is citable here (cardinality issues
notwithstanding). If I assume that a conferenceProceeding is something that has
been published, then can I take your argument to mean that you would like to see
Presentation added back in as a reference type (I was removing at your request
in the first place :)? I think I misunderstood your original request in Comment #9.

I'd be happy to change cardinality in conferenceProceedings and elsewhere. As I
was going through literature I felt that cardinality was somewhat arbitrary, but
for the most part I didn't make changes except where your notes indicated
explicitly to relax the restrictions. I'd prefer that everything be optional in
literature unless it is absolutely fundamental to the particular reference type.
Is that reasonable? But, what is fundamental in each reference type? In
EndNote every field is optional, so we could go that route and I think it would
be fine. I'm open to suggestions.

I'm trying hard to follow this bug's issues, but I'm struggling.

Running diffs on eml-literature.xsd 1.32 against 1.33, the entire file
diffs because 1.33 uses CR-LF EOLs. Is there one file format or the
other which is standard in the archive? Most seem to be UNIX format,
w/ CR EOL's.

So, I stripped CR-LF's to diff.

See other comments below:

So how do i cite a paper or poster presented at xxth annual meeting
of the Ecological Socienty of America, Spokane, August 1999 that is
not published in any proceedings volume?

I'd be happy to change cardinality in conferenceProceedings and
elsewhere. As I was going through literature I felt that
cardinality was somewhat arbitrary, but for the most part I didn't
make changes except where your notes indicated explicitly to relax
the restrictions. I'd prefer that everything be optional in
literature unless it is absolutely fundamental to the particular
reference type. Is that reasonable? But, what is fundamental in
each reference type? In EndNote every field is optional, so we
could go that route and I think it would be fine. I'm open to
suggestions.

Why don't you consult some other well-established sources, in addition
to EndNote. BibTeX uses the following Entry-Types, for example:

See:
http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html
for a brief summary, including description of fields.

@article - An article from a journal or magazine.

@book - A book with an explicit publisher.

@booklet - A work that is printed and bound, but without a named
publisher or sponsoring institution.

@inbook - A part of a book, which may be a chapter (or section or
whatever) and/or a range of pages.

@incollection - A part of a book having its own title.

@inproceedings - An article in a conference proceedings.

@manual - Technical documentation.

@mastersthesis - A Master's thesis.

@misc - Use this type when nothing else fits.

@phdthesis - A PhD thesis.

@proceedings - The proceedings of a conference.

@techreport - A report published by a school or other institution,
usually numbered within a series.

@unpublished - A document having an author and title, but not formally
published.

BibTex has been in use for almost 20 years and is used in a broad
array of science and humanities disciplines. I'm not advocating the
use of BibTeX, just that the data structures have been debated and
determined...the point is, lots of people have thought about citation
issues, why do we have to re-invent the wheel in EML? BibTeX is a
standard output format of EndNote. Also, there are nascent XML
representations of BibTex, and BibTeXML <-> DocBook efforts eg.:
http://bibtexml.sourceforge.net/

Look at the distinctions (regarding requred elements) between the
Book, Proceedings and InProceedings data structures (OPT fields are
optional, ALT are alternate, others are required).

@Book{,
ALTauthor = {},
ALTeditor = {},
title = {},
publisher = {},
year = {},
OPTkey = {},
OPTvolume = {},
OPTnumber = {},
OPTseries = {},
OPTaddress = {},
OPTedition = {},
OPTmonth = {},
OPTnote = {},
OPTannote = {}
}

@Proceedings{,
title = {},
year = {},
OPTkey = {},
OPTeditor = {},
OPTvolume = {},
OPTnumber = {},
OPTseries = {},
OPTaddress = {},
OPTmonth = {},
OPTorganization = {},
OPTpublisher = {},
OPTnote = {},
OPTannote = {}
}

@InProceedings{,
author = {},
title = {},
booktitle = {},
OPTcrossref = {},
OPTkey = {},
OPTpages = {},
OPTyear = {},
OPTeditor = {},
OPTvolume = {},
OPTnumber = {},
OPTseries = {},
OPTaddress = {},
OPTmonth = {},
OPTorganization = {},
OPTpublisher = {},
OPTnote = {},
OPTannote = {}
}

Some of the issues which are addressed below are solved in BibTex with
higher-granularity definitions, ie. address, note or annote.

Similarly, the entry-types 'Unpublished' and 'Miscellaneous' cover the
broad array of unorthodox citations without specifying all the
details. So, PersonalCommunication would simply be an instance of
'Miscellaneous' with the note field tagged 'Personal Communication';
likewise for audioVisual, etc. etc.

e.
Drop publicationPlace – the locational information is already in
publisher

This is called 'address' in BibTeX. And apparently there are some
usage conventions:

address

Usually the address of the publisher or other type of
  institution. For major publishing houses, van Leunen recommends
  omitting the information entirely. For small publishers, on the
  other hand, you can help the reader by giving the complete address.

Drop presentationPlace. Move the proceedings information from
conferenceProceedings to this module.

PRESENTATION type dropped altogether. No corresponding type in EndNote.

Would fall under miscellaneous.

g.
Drop institution from report. Institutional affiliation of authors is
already in the RP information of the authors.

Institution is a standard field in 'Technical Report' in BibTex.

@TechReport{,
author = {},
title = {},
institution = {},
year = {},
OPTkey = {},
OPTtype = {},
OPTnumber = {},
OPTaddress = {},
OPTmonth = {},
OPTnote = {},
OPTannote = {}
}

h.
Make report number optional. This may be part of the title or non-
existent

i.
Drop publisher from thesis. If it is published then it is a book.

@PhdThesis{,
author = {},
title = {},
school = {},
year = {},
OPTkey = {},
OPTtype = {},
OPTaddress = {},
OPTmonth = {},
OPTnote = {},
OPTannote = {}
}

regarding epiphany:

The decision on something like this ought to be detemined on it's
merits or lack-of. Although the difficulties addressed by Peters
comments are real, there would be clear programmatic solutions to
those.

A better criteria might be:
Is EML's clarity or utility enhanced by this proposition or not?

The eml-resource module contains general information that describes
  dataset resources, literature resources, collection resources, and
  software resources. It is intended to provide overview information
  about the resource, including title, abstract, keywords, contacts,
  and the links to associated metadata and data for the given
  resource.

But in the case of eml-literature, many of the bibliographic
references might be completely external to the the data/projects being
documented in that instance. The current structural relationship
between eml-resource and eml-literature presumes involvement of the
'creator' in the dataset, doesn't it? A work being cited, however,
wouldn't necessarily be by a defined 'creator' in EML, but just as
likely could be an author of a relevant document, who has no reason to
be defined in EML beyond his authorship status in that particular
cited document (a methods paper; a seminal work defining a research
theme, etc.). So, extending creator in this way to provide an
'author' in the various entry-types is kind of mutant.

Or am I totally misreading this issue?

OK, undid my epiphany. ResourceGroup is back as a child of CitationType.

Still need to create a "Presentation" type as agreed on the last conference
call. Then literature will be done.

Presentation type added back in as requested. Changes for literature are now
complete. Marking bug RESOLVED FIXED.

Original Bugzilla ID was 492